WriteBinary Method

Writes binary data to the output queue.

Syntax

[Visual Basic]
object.WriteBinary(WriteBuffer [, NumBytesToWrite, Timeout])

[C#]
object.WriteBinary(WriteBuffer [, NumBytesToWrite, Timeout])

[C++]
object->WriteBinary(WriteBuffer [, NumBytesToWrite, Timeout])

Parameters

object

An object expression that evaluates to a PortController object.

WriteBuffer

A Byte Array containing the data to be written to the output queue.

[optional] NumBytesToWrite

An Int32 indicating the number of bytes to be written to the output queue.

[optional] Timeout

An Int32 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 perform a write and return immediately. Setting this parameter to a negative value causes the function to wait until the write operation completes before returning.

Return Value

An Int32 indicating the number of bytes written to the output queue. If Timeout is 0 or omitted, the return value will be 0 if either no data was written, or no data has yet been written.

Remarks

• The NumBytesToWrite and Timeout parameters are optional. When the NumBytesToWrite parameter is omitted (or set to 0) the entire specified string is written to the output queue. When the Timeout parameter is omitted (or set to 0), the function does not wait for the operation to complete before returning.
• If Timeout is a negative value, this function will block until the write operation completes. This will likely lock up the application and its UI if the device receiving the data has indicated it is not ready to receive data and handshaking is enabled.

Errors

• Attempting to write to the output queue when the port is closed will cause the PortController to throw a "Port is closed." exception.
• If an error occurs during the write, a "An error occurred while trying to place data in output queue." exception is thrown.
• Attempting to set NumBytesToWrite to a negative value will cause the PortController to throw an "Invalid argument" exception.
• If there are greater than 10000 write operations queued for processing (occurs when Timeout is omitted or 0), a "Maximum outstanding write operations limit has been reached" exception is thrown and the write operation is ignored. This error will never occur when requiring a write operation to complete before control is returned by specifying a non-zero value for Timeout.

Example

[Visual Basic]
Dim BinaryWriteBuffer() As Byte = {&H1, &H0, &H3}
myPortController.WriteBinary(BinaryWriteBuffer)  'writes all bytes

[C#]
Byte[] BinaryWriteBuffer = {0x01, 0x00, 0x03};
myPortController.WriteBinary(BinaryWriteBuffer); // writes all bytes

[C++]
Byte BinaryWriteBuffer __gc[] = {0x01, 0x00, 0x03};
myPortController->WriteBinary(BinaryWriteBuffer); // writes all bytes

See Also