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