Read Method

Reads data from the receive queue.

Syntax

Visual Basic

object.Read NumBytesToRead, Timeout, NumBytesRead

Visual C++

object.Read(long NumBytesToRead, long Timeout, long &NumBytesRead)

Delphi

function object.Read(NumBytesToRead: Integer; Timeout: Integer; out pNumBytesRead: Integer): WideString;

Example

Visual Basic

Dim read_buffer As String
Dim num_bytes_read As Long

read_buffer = myPortController.Read                       'Reads everything in the receive queue
read_buffer = myPortController.Read (10)                  'Reads 10 bytes from receive queue

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

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

Visual C++

CString strReadBuffer;
long num_bytes_read;

strReadBuffer = m_myPortController.Read(0, 0, &num_bytes_read);     // Reads everything in the receive queue
strReadBuffer = m_myPortController.Read(10, 0, &num_bytes_read);    // Reads 10 bytes from receive queue

strReadBuffer = m_myPortController.Read(10, 5000, &num_bytes_read); // Times out after five seconds if 10
                                                                    // bytes have not been read

Delphi

var
  strReadBuffer: WideString;       // declare variables in the proper place
  num_bytes_read: Integer;

strReadBuffer := myPortController.Read(0, 0, num_bytes_read);     // Reads everything in the receive queue
strReadBuffer := myPortController.Read(10, 0, num_bytes_read);    // Reads 10 bytes from receive queue

strReadBuffer := myPortController.Read(10, 5000, num_bytes_read); // Times out after five seconds if 10
                                                                  // bytes have not been read

Remarks

• The NumBytesToRead and Timeout parameters are optional (to omit these parameters in VC++ and Delphi, simply pass 0 as the value). When the NumBytesToRead parameter is omitted all data currently in the receive buffer is read. When the Timeout parameter is omitted, 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 EvtCharReceived events. See Using PortController Events for more information

• NumBytesRead is optional in VB but required in VC++ and Delphi. The number of bytes read by the function in returned into this parameter.

• If the operation does not complete in the time specified by the Timeout parameter, the function returns NO data. 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.

• This method may be used to read binary data in Visual Basic and Delphi, but should not be used to read binary data in Visual C++. See Reading and Writing Binary Data for more information on working with binary data.

Returns

A VB String / VC++ CString / Delphi WideString containing the read data.

Errors

• Attempting to read from the receive queue when the port is closed will cause the 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 the PortController to throw an "Invalid argument" exception.

See Also