BinFile

BinFile

BinFile class is used for accessing & modifying an existing binary file or creating a new one in the file system from QJS scripts.

Table of Contents

• Constructor
• Properties
• Functions
  • Open
  • Close
  • AtEnd
  • Seek
  • ReadText
  • ReadHex
  • ReadInt*
  • ReadUint*
  • WriteText
  • WriteHex
  • WriteInt*
  • WriteUint*

Constructor

A BinFile instance can be constructed using 1 of 2 syntaxes as shown below.

Syntax:

new BinFile()
new BinFile(path, [mode])

Argument	Description
path	The file to be opened. Any relative paths will be relative to the WARP folder.
mode	Optional mode in which the file should be opened. Valid values are: r = read only w = write only rw = read/write a = append r is the default mode.

Once the object is created, the following properties & functions become available.

Properties

Property name	Description
<obj>.Path	The opened file's path
<obj>.Size	Size of currently open file
<obj>.Pos	Current file position offset
<obj>.Valid	Boolean indicating there is a valid file currently open

Functions

Open

Used for opening a file with an existing BinFile instance .

If the instance already has a file opened, it will be closed automatically.

Syntax:

<obj>.Open(path, mode)

Argument	Description
path	The file to be opened. Any relative paths will be relative to the WARP folder.
mode	Optional mode in which the file should be opened. Valid values are: r = read only w = write only rw = read/write a = append r is the default mode.

Returns: true if successfully opened else false

Close

Closes the currently open file (if any)

Syntax:

<obj>.Close()

AtEnd

Checks whether the internal position has reached the End Of File.

Syntax:

<obj>.AtEnd()

Returns: true if it is at EOF else false

Seek

Changes the internal position to specified value (only if it is valid one).

Syntax:

<obj>.Seek(pos)

Argument	Description
pos	The new position requested. Only works if the value is within the file limits.

Returns: true if position set successfully else false

ReadText

Reads a specific number of bytes from the file as a text string of specified Encoding. All the arguments are optional.

Syntax:

<obj>.ReadText([size], [from], [enc])

Argument	Description
size	Optional no. of bytes to be read. If omitted or negative, all the remaining bytes are utilized to construct the text.
from	Optional address from where the bytes need to be read. If omitted or negative, then the bytes are read from <obj>.Pos, which is then incremented.
enc	Optional Encoding of the text. If omitted, ASCII text gets returned.

Returns: the retrieved text string if successful otherwise an empty string.

ReadHex

Reads a specific number of bytes from the file as a hex string. All arguments are optional.

Syntax:

<obj>.ReadHex([size], [from])

Argument	Description
size	Optional no. of bytes to be read. If omitted or negative, all the remaining bytes are utilized to construct the hex string.
from	Optional address from where the bytes need to be read. If omitted or negative, then the bytes are read from <obj>.Pos, which is then incremented.

Returns: the retrieved hex string if successful otherwise an empty string.

ReadInt*

Reads 8 / 16 / 32 bits (1 / 2 / 4 bytes) from the file as a signed integer.

Syntax:

<obj>.ReadInt8([from])
<obj>.ReadInt16([from])
<obj>.ReadInt32([from])

Argument	Description
from	Optional address from where the bytes need to be read. If omitted or negative, then the bytes are read from <obj>.Pos, which is then incremented.

Returns: the retrieved integer if successful otherwise 0

ReadUint*

Reads 8 / 16 / 32 bits (1 / 2 / 4 bytes) from the file as an unsigned integer.

Syntax:

<obj>.ReadUint8([from])
<obj>.ReadUint16([from])
<obj>.ReadUint32([from])

Argument	Description
from	Optional address from where the bytes need to be read. If omitted or negative, then the bytes are read from <obj>.Pos, which is then incremented.

Returns: the retrieved integer if successful otherwise 0.

WriteText

Write a text string of specified Encoding to the file.

Syntax:

<obj>.WriteText(str, [to], [enc])

Argument	Description
str	The text string to be written.
to	Optional address at which the string should be written. If omitted or negative, then the data is written at <obj>.Pos, which is then incremented.
enc	Optional Encoding of the text. If omitted, the text is treated as ASCII.

Returns: true if successful else false.

WriteHex

Write a hex string to the file.

Syntax:

<obj>.WriteHex(str, [to])

Argument	Description
str	The hex string to be written.
to	Optional address at which the string should be written. If omitted or negative, then the data is written at <obj>.Pos, which is then incremented.

Returns: true if successful else false.

WriteInt*

Write a signed 8 / 16 / 32 bit (1 / 2 / 4 byte) integer to the file.

Syntax:

<obj>.WriteInt8(value, [to])
<obj>.WriteInt16(value, [to])
<obj>.WriteInt32(value, [to])**  

Argument	Description
value	The integer value to be written.
to	Optional address at which the string should be written. If omitted or negative, then the data is written at <obj>.Pos, which is then incremented.

Returns: true if successful else false.

WriteUint*

Write an unsigned 8 / 16 / 32 bit (1 / 2 / 4 byte) integer to the file.

Syntax:

<obj>.WriteUint8(value, [to])
<obj>.WriteUint16(value, [to])
<obj>.WriteUint32(value, [to])

Argument	Description
value	The integer value to be written.
to	Optional address at which the string should be written. If omitted or negative, then the data is written at <obj>.Pos, which is then incremented.

Returns: true if successful else false.

Return to top

Further reading

• TextFile
• Inbuilt API
• Writing scripts
• Usage Guide