BinaryStream Class

BinaryStream objects are used to read and write data to and from a binary file. The benefit of using BinaryStreams rather than text streams is that you can read from and write to any position in the file.

Events

None

Properties

EOF

Handle

LastErrorCode

Length

LittleEndian

Position


Methods

Close

ReadSingle

WriteInt32

Read

ReadUInt16

WriteInt32

ReadBoolean

ReadUInt32

WriteInt64

ReadDouble

ReadUInt64

WriteInt64

ReadInt16

ReadUInt8

WriteInt8

ReadInt32

Write

WriteInt8

ReadInt64

WriteBoolean

WritePString

ReadInt8

WriteDouble

WriteSingle

ReadPString

WriteInt16

WriteUInt16


More information available in parent classes: Object

Text files must be read sequentially from the start to the end.


Constructors

Use these constructors to back the BinaryStream from a MemoryBlock or a String instead of a file on disk.

NameParametersDescription
BinaryStream mb as MemoryBlock Creates a BinaryStream from a MemoryBlock. All BinaryStream functions are supported. If the MemoryBlock was created from a Declare, then the Length property of the BinaryStream will always report -1.
BinaryStream Handle as Integer, Type as Integer Type is one of the HandleType class constants and Handle is the appropriate handle type specified by the Type parameter. The HandleType class constants are as follows: 1- HandleTypeWin32Handle. A Windows32 OS handle. 2- HandleTypeFilePointer. A file pointer. 3- HandleTypeFileNumber. A file descriptor. 4- HandleTypeMacFileRefNum. A file reference number. 5- HandleTypeMacFileSpecPointer. An FSSpec. For instance, you can use a Declare to open a file with whatever permissions that you wish, and then pass the Handle to a stream object's constructor
BinaryStream s as String Creates a BinaryStream from a String. All BinaryStream functions except writing and setting the length are supported. Since the string is immutable, the BinaryStream behavior is read only and the write methods of the stream produce an error.


Notes

What is the LittleEndian property? The Windows and Linux operating systems store binary values in the reverse order from the Mac OS. If you were using the ReadShort or ReadLong methods to read data from a file that was in Little Endian format, you would get incorrect data. REALbasic reads data in Big Endian format. Most Macintosh files are in Big Endian format. If you are reading a file that is in Little Endian format, you will need to set the Little Endian property to True before you begin reading the file. This applies to writing data with WriteShort and WriteLong.

You can use the constants TargetLittleEndian and TargetBigEndian to determine which byte order is being used for a particular compile.

For example, in big endian (like the Mac OS), the value 258 would be stored as:

01 02

while in Little Endian, it would be stored as:

02 01

If the LittleEndian property is set incorrectly, then you would read the value as 513.

Because REALbasic has the LittleEndian property, you can write your code to be OS-independent. Set the LittleEndian property to True if the file format is intrinsically little endian (i.e. GIF files), otherwise leave it as False.

The BinaryStream class implements the Readable and Writeable class interfaces. If you implement either or both of these interfaces, you must provide the methods and parameters as specified by those class interfaces.

For more information about class interfaces and how to implement them, see the section "Class Interfaces" on page 455 of the User's Guide.


Example

This example reads each pair of bytes from a file and writes them in reverse order to a new file. The user chooses the source file using the Open-file dialog box and saves the new file using the Save as dialog box.

Dim WriteToFile as BinaryStream
Dim ReadFromFile as BinaryStream
Dim f as FolderItem
f= GetOpenFolderItem("text")
If f <> Nil Then
 ReadFromFile=f.OpenAsBinaryFile( False)
 ReadFromFile.littleEndian= True
 f= GetSaveFolderItem("","")
 If f <> Nil Then
  WriteToFile=f.CreateBinaryFile("text")
  While Not ReadFromFile.EOF
   WriteToFile.WriteShort ReadFromFile.ReadShort
  wend
 WriteToFile.close
End If
ReadFromFile.close
End If

See Also

FolderItem, MemoryBlock, TextInputStream, TextOutputStream classes; TargetBigEndian, TargetLittleEndian constants.