Class

Xojo.IO.BinaryStream

Warning

This item was deprecated in version 2020r2. Please use BinaryStream as a replacement.

Description

The BinaryStream class is an input/output mechanism for reading and writing arbitrary binary data. It can be used with MemoryBlocks and FolderItems.

Properties

Name

Type

Read-Only

Shared

IsClosed

Boolean

✓

Length

UInt64

LittleEndian

Boolean

Position

UInt64

Enumerations

Xojo.IO.BinaryStream.LockModes

LockModes

The type of locking modes for the binary stream. (Read, Write, ReadWrite, Exclusive)

Enum

Description

Read

Read access.

Write

Write access.

ReadWrite

Read and write access.

Exclusive

Exclusive lock; nothing else can access the file.

Property descriptions

Xojo.IO.BinaryStream.IsClosed

IsClosed As Boolean

Determines if the binary stream has been closed.

This property is read-only.

Xojo.IO.BinaryStream.Length

Length As UInt64

Gets or sets the length of the file in bytes. If you set the Length property to a value smaller than its current value, it truncates the file. If the BinaryStream is backed by a MemoryBlock, it returns MemoryBlock.Size. Raises an exception if setting the Length of a BinaryStream backed by a MemoryBlock with unknown size.

Xojo.IO.BinaryStream.LittleEndian

LittleEndian As Boolean

Gets or sets the byte order when reading or writing to a BinaryStream. A value of True sets the byte order to little endian.

Xojo.IO.BinaryStream.Position

Position As UInt64

Gets or sets the current position within the BinaryStream. The first position is numbered zero. To move the position to the end of the stream, set the Position to Length.

To append to the end of a file, set the Position to the Length and then Write.

Method descriptions

Xojo.IO.BinaryStream.Close

Close

Closes an existing BinaryStream. Raises an exception if the stream is already closed.

Xojo.IO.BinaryStream.Constructor

Constructor(mb As MemoryBlock)

Note

Constructors are special methods called when you create an object with the New keyword and pass in the parameters above.

Creates a BinaryStream from a MemoryBlock.

A BinaryStream created using a MemoryBlock will automatically re-size the MemoryBlock as needed to contain any additional data written to the stream.

Create binary data from an Image in the iOS project:

' MyImage is an iOSImage in the project
Var binaryData As New BinaryStream(MyImage.ToData("public.PNG"))

Xojo.IO.BinaryStream.Create

Create(file As FolderItem) As BinaryStream

Creates a new BinaryStream, bound to the passed File. Raises a RuntimeException if File is Nil, does not exist, is not accessible or another error occurs.

Using Xojo.IO
Using Xojo.Core

Var f As FolderItem = SpecialFolder.Documents.Child("MyFile.data")
Var bStream As BinaryStream
bStream = BinaryStream.Create(f)

Var data As MemoryBlock
Var t As Text = "Text for the binary file."
data = TextEncoding.UTF8.ConvertTextToData(t)
bStream.Write(data)
bStream.Close

Xojo.IO.BinaryStream.EOF

EOF As Boolean

Returns True if the BinaryStream position = the file length. If the stream is closed this function always returns True.

Xojo.IO.BinaryStream.Flush

Flush

Immediately sends the contents of internal write buffers to disk or to the output stream.

Xojo.IO.BinaryStream.FromHandle

FromHandle(handle As Ptr, type As Xojo.IO.HandleTypes) As BinaryStream

Creates a new BinaryStream from an OS handle.

Xojo.IO.BinaryStream.Handle

Handle(type As Xojo.IO.HandleTypes) As Ptr

Given a handle type, gets a handle to the current stream . File Descriptor, File Pointer, or a Windows32 OS handle.

Xojo.IO.BinaryStream.Open

Open(file As FolderItem, mode As LockModes) As BinaryStream

Opens the passed FolderItem as a binary stream with the specified lock mode. If an error occurs, an IOException is raised.

Read all the data from a file:

Using Xojo.Core
Using Xojo.IO
Var f As FolderItem = SpecialFolder.Documents.Child("MyFile.data")
Var bStream As BinaryStream
bStream = BinaryStream.Open(f, BinaryStream.LockModes.Read)

Var data As MemoryBlock
data = bStream.Read(bStream.Length)

bStream.Close

To append data to a binary file, open the file in read/write mode and then call the Write method once you have reached EOF:

Using Xojo.IO
Using Xojo.Core

Var f As FolderItem = SpecialFolder.Documents.Child("MyFile.data")
Var bStream As BinaryStream
bStream = BinaryStream.Open(f, BinaryStream.LockModes.ReadWrite)

Var data As MemoryBlock
data = bStream.Read(bStream.Length) ' reached EOF

Var mb As MemoryBlock
Var t As Text = "Text to append"
mb = TextEncoding.UTF8.ConvertTextToData(t)
bStream.Write(mb) ' data is appended to the BinaryStream
bStream.Close

Xojo.IO.BinaryStream.Read

Read(count As Integer) As MemoryBlock

Reads the specified number of bytes. Raises an exception if the file is not readable.

Read 1K into a MemoryBlock:

Var data As MemoryBlock
data = bStream.Read(1024)

Read the entire file into a MemoryBlock:

Var data As MemoryBlock
data = bStream.Read(bStream.Length)

Xojo.IO.BinaryStream.ReadBoolean

ReadBoolean As Boolean

Reads a Boolean from the stream. Raises an exception if the file is not readable.

Xojo.IO.BinaryStream.ReadCurrency

ReadCurrency As Currency

Xojo.IO.BinaryStream

Xojo.IO.BinaryStream.ReadDouble

ReadDouble As Double

Reads a Double from the stream. Raises an exception if the file is not readable.

Xojo.IO.BinaryStream.ReadInt16

ReadInt16 As Int16

Reads an Int16 from the stream. Raises an exception if the file is not readable.

Xojo.IO.BinaryStream.ReadInt32

ReadInt32 As Int32

Reads an Int32 from the stream. Raises an exception if the file is not readable.

Xojo.IO.BinaryStream.ReadInt64

ReadInt64 As Int64

Reads an Int64 from the stream. Raises an exception if the file is not readable.

Xojo.IO.BinaryStream.ReadInt8

ReadInt8 As Int8

Reads an Int8 from the stream. Raises an exception if the file is not readable.

Xojo.IO.BinaryStream.ReadSingle

ReadSingle As Single

Reads a Single from the stream. Raises an exception if the file is not readable.

Xojo.IO.BinaryStream.ReadText

ReadText(count As Integer, encoding As TextEncoding) As String

Reads the next count bytes from the stream. Raises an exception if the file is not readable or if encoding is Nil.

Xojo.IO.BinaryStream.ReadUInt16

ReadUInt16 As UInt16

Reads a UInt16 from the stream. Raises an exception if the file is not readable.

Xojo.IO.BinaryStream.ReadUInt32

ReadUInt32 As UInt32

Reads a UInt32 from the stream. Raises an exception if the file is not readable.

Xojo.IO.BinaryStream.ReadUInt64

ReadUInt64 As UInt64

Reads a UInt64 from the stream. Raises an exception if the file is not readable.

Xojo.IO.BinaryStream.ReadUInt8

ReadUInt8 As UInt8

Reads a UInt8 from the stream. Raises an exception if the file is not readable.

Xojo.IO.BinaryStream.Write

Write(block As MemoryBlock)

Writes the bytes in the memoryblock. Raises an exception if the stream is not writable or the MemoryBlock has an unknown size.

Xojo.IO.BinaryStream.WriteBoolean

WriteBoolean(value As Boolean)

Writes a Boolean to the stream. Raises an exception if the stream is not writable.

Xojo.IO.BinaryStream.WriteCurrency

WriteCurrency(value As Currency)

Writes a Currency to the stream. Raises an exception if the stream is not writable.

Xojo.IO.BinaryStream.WriteDouble

WriteDouble(value As Double)

Writes a Double to the stream. Raises an exception if the stream is not writable.

Xojo.IO.BinaryStream.WriteInt16

WriteInt16(value As Int16)

Writes an Int16 to the stream. Raises an exception if the stream is not writable.

Xojo.IO.BinaryStream.WriteInt32

WriteInt32(value As Int32)

Writes an Int32 to the stream. Raises an exception if the stream is not writable.

Xojo.IO.BinaryStream.WriteInt64

WriteInt64(value As Int64)

Writes an Int64 to the stream. Raises an exception if the stream is not writable.

Xojo.IO.BinaryStream.WriteInt8

WriteInt8(value As Int8)

Writes an Int8 to the stream. Raises an exception if the stream is not writable.

Xojo.IO.BinaryStream.WriteSingle

WriteSingle(value As Single)

Writes a Single to the stream. Raises an exception if the stream is not writable.

Xojo.IO.BinaryStream.WriteText

WriteText(value As String, encoding As TextEncoding)

Writes the bytes in the Text. Raises an exception if the stream is not writable, or encoding is Nil.

Xojo.IO.BinaryStream.WriteUInt16

WriteUInt16(value As UInt16)

Writes a UInt16 to the stream. Raises an exception if the stream is not writable.

Xojo.IO.BinaryStream.WriteUInt32

WriteUInt32(value As UInt32)

Writes a UInt32 to the stream. Raises an exception if the stream is not writable.

Xojo.IO.BinaryStream.WriteUInt64

WriteUInt64(value As UInt64)

Writes a UInt64 to the stream. Raises an exception if the stream is not writable.

Xojo.IO.BinaryStream.WriteUInt8

WriteUInt8(value As UInt8)

Writes a UInt8 to the stream. Raises an exception if the stream is not writable.

Notes

The Read/Write methods raise an exception when reading or writing past the end of the stream. File IO prevents thread switching.

Sample code

Load an image that is copied to an iOS app using a Copy Files Build Step:

Var f As FolderItem = SpecialFolder.GetResource("MyImage.JPG")

Var b As BinaryStream
b = BinaryStream.Open(f, BinaryStream.LockModes.Read)

Var mb As New MemoryBlock(b.Read(b.Length))

b.Close

Var image As iOSImage
image = Image.FromData(mb)

ImageView1.Image = image

Compatibility

All project types on all supported operating systems.

See also

Object parent class; FolderItem, MemoryBlock classes