ReadBinary Method

Reads binary data from the receive queue.

Syntax

[Visual Basic]
object.ReadBinary([NumBytesToRead, Timeout, NumBytesRead])

[C#]
object.ReadBinary([NumBytesToRead, Timeout, NumBytesRead])

[C++]
object->ReadBinary([NumBytesToRead, Timeout, NumBytesRead])

Parameters

object

An object expression that evaluates to a PortController object.

[optional] NumBytesToRead

An Int32 indicating the number of bytes to read from the receive queue. Omitting this parameter (or setting it to 0) causes PortController to read all data in the receive queue.

[optional] Timeout

An Int32 integer indicating the amount of time in milliseconds to wait before terminating the operation. Omitting this parameter (or setting it to 0) causes the function to wait indefinitely for the operation to complete before returning.

[optional] NumBytesRead

An Int32 containing the number of bytes actually read from the receive queue.

Return Value

A Byte array containing the read data

Remarks

• The NumBytesToRead and Timeout parameters are optional. When the NumBytesToRead parameter is omitted (or set to 0) all data currently in the receive buffer is read. When the Timeout parameter is omitted (or set to 0), the function waits indefinitely for the operation to complete before returning.
• This function is used most effectively in the handler functions for the DataReceived and EventCharReceived events.
• If the operation does not complete in the time specified by the Timeout parameter, the function returns a blank string. For example, if the NumBytesToRead parameter is 10 and timeout elapses with only 5 bytes having been received, the receive queue is not read and the function returns no data.

Errors

• Attempting to read from the receive queue when the port is closed will cause PortController to throw a "Port is closed." exception.

• If an error occurs during the read, a "An error occurred while trying to read data from the receive queue." exception is thrown.

• Attempting to set Timeout or NumBytesToRead to a negative value will cause PortController to throw an "Invalid argument" exception.

Example

[Visual Basic]
Dim readBuffer As Byte()
Dim num_bytes_read As Int32

readBuffer = myPortController.ReadBinary()                      'Reads everything in the receive queue
readBuffer = myPortController.ReadBinary(10)                    'Reads 10 bytes from receive queue

readBuffer = myPortController.ReadBinary(10, 5000)              'Times out after five seconds if 10 bytes have
                                                                'not been read

readBuffer = myPortController.ReadBinary(0, 0, num_bytes_read)  'Read everything and get number of bytes read


[C#]
Byte[] readBuffer;
Int32 num_bytes_read;

readBuffer = myPortController.ReadBinary();         // Reads everything in the receive queue
readBuffer = myPortController.ReadBinary(10);       // Reads 10 bytes from receive queue

readBuffer = myPortController.ReadBinary(10, 5000); // Times out after five seconds if 10
                                                    // bytes have not been read

readBuffer = myPortController.ReadBinary(0, 0, out num_bytes_read); // Read everything and get number of bytes read


[C++]
Byte readBuffer[];
Int32 num_bytes_read;

readBuffer = myPortController->ReadBinary();         // Reads everything in the receive queue
readBuffer = myPortController->ReadBinary(10);       // Reads 10 bytes from receive queue

readBuffer = myPortController->ReadBinary(10, 5000); // Times out after five seconds if 10
                                                     // bytes have not been read

readBuffer = myPortController->ReadBinary(0, 0, num_bytes_read); // Read everything and get number of bytes read

See Also