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
  • Position related
  • Readers
  • Writers

Constructor

Its constructor takes 2 forms.

• new BinFile()
  Creates the object with empty values.
  
  

• new BinFile(path, [mode])
  Creates the object and opens a file with specified mode.

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

  
  

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

Properties

Name	Description
Path	The opened file's path
Size	Size of currently open file
Pos	Current file position offset
Valid	Boolean indicating there is a valid file currently open

Open & Close

• <obj>.Open(path, mode)
  Opens a file with specified mode. If any file is already open using this object, it is automatically closed first.

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

  Returns: true if successful.
  
  

• <obj>.Close()
  Closes currently open file if any.

Position related

• <obj>.AtEnd()
  Check whether End of File has reached.

  Returns: true if <obj>.Pos is at the end.
  
  

• <obj>.Seek(pos)
  Change the file position to specified value.

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

  Returns: true if successful.

Readers

• <obj>.ReadText([size], [from], [enc])
  Reads a specific number of bytes from the file as a text string of specified Encoding. All the arguments are optional.

  Argument	Description
  size	No of bytes to be read. The default value is -1. If size is negative all the remaining bytes are utilized to construct the text.
  from	Address from where the bytes need to be read. The default value is -1. If the from address is negative, then the bytes are read from .Pos, which is then incremented.
  enc	Encoding of the text. Default is ASCII.

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

• <obj>.ReadHex([size], [from])
  Reads a specific number of bytes from the file as a hex string. All arguments are optional.

  Argument	Description
  size	No of bytes to be read. The default value is -1. If size is negative all the remaining bytes are returned as hex.
  from	Address from where the bytes need to be read. The default value is -1. If the from address is negative, then the bytes are read from .Pos, which is then incremented.

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

• <obj>.ReadInt8([from])
  <obj>.ReadInt16([from])
  <obj>.ReadInt32([from])
  Reads 8 / 16 / 32 bits (1 / 2 / 4 bytes) from the file as a signed integer.

  Argument	Description
  from	Address from where the byte needs to be read. The default value is -1. If the from address is negative, then the bytes are read from .Pos, which is then incremented.

  Returns: the retrieved integer if successful otherwise 0.
  
  

• <obj>.ReadUint8([from])
  <obj>.ReadUint16([from])
  <obj>.ReadUint32([from])
  Reads 8 / 16 / 32 bits (1 / 2 / 4 bytes) from the file as an unsigned integer.

  Argument	Description
  from	Address from where the byte needs to be read. The default value is -1. If the from address is negative, then the bytes are read from .Pos, which is then incremented.

  Returns: the retrieved integer if successful otherwise 0.

Writers

• <obj>.WriteText(str, [to], [enc])
  Write a text string of specified Encoding to the file.

  Argument	Description
  str	The text string to be written.
  to	The address at which the string should be written. The default value is -1. If the to address is negative, then the data is written at .Pos, which is then incremented.
  enc	Encoding of the text. Default is ASCII.

  Returns: true if successful else false.
  
  

• <obj>.WriteHex(str, [to])
  Write a hex string to the file.

  Argument	Description
  str	The hex string to be written.
  to	The address at which the string should be written. The default value is -1. If the to address is negative, then the data is written at .Pos, which is then incremented.

  Returns: true if successful else false.
  
  

• <obj>.WriteInt8(value, [to])
  <obj>.WriteInt16(value, [to])
  <obj>.WriteInt32(value, [to])
  Write a signed 8 / 16 / 32 bit (1 / 2 / 4 byte) integer to the file.

  Argument	Description
  value	The integer value to be written.
  to	The address at which the integer should be written. The default value is -1. If the to address is negative, then the data is written at .Pos, which is then incremented.

  Returns: true if successful else false.
  
  

• <obj>.WriteUint8(value, [to])
  <obj>.WriteUint16(value, [to])
  <obj>.WriteUint32(value, [to])
  Write an unsigned 8 / 16 / 32 bit (1 / 2 / 4 byte) integer to the file.

  Argument	Description
  value	The integer value to be written.
  to	The address at which the integer should be written. The default value is -1. If the to address is negative, then the data is written at .Pos, which is then incremented.

  Returns: true if successful else false.