Object

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.

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

# Notes

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.

Name | Parameters | Description
--- | --- | ---
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.

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 464 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.