Receive Method

Description

Receive an arbitrary amount of data. The specified String or Byte array is filled with bytes from the remote host.

Syntax

Visual Basic
Public Function Receive( _ ByRef Data As Variant _ ) As Long

Parameters

Data: String, Byte array, or DartStream Object. Bytes from the network are copied into this variable.

Return Value

The number of Unicode characters or bytes copied into the Data variable.

Remarks

You can use this method only when the State is tcpConnected or tcpClosing; otherwise, a ptNotConnected error is generated. When State is tcpClosing, you can use the Receive, Fill, or Search methods to flush the buffer and cause the State to change to tcpClosed.

Data can be specified as a dimensioned or undimensioned String, Byte array, or DartStream Object:

A String of length greater than 0 or a dimensioned Byte array of length greater than 0 indicates that the existing contents should be overwritten with received bytes. The String or Byte array is not resized. When receiving data, the actual amount transferred never exceeds the size of the Data parameter, but the Count returned may indicate that only part of the String or Byte array contains received bytes. Note Count should always be checked because the size of the Data parameter does not indicate how many bytes or characters were actually received.
A String of length 0 or an un-dimensioned Byte array is resized to the length of the available data before received bytes are copied into it. The returned Count matches the new size of the String or Byte array. If the same Data variable is used on a successive call, the variable is considered to be of size greater than 0 and is not resized.

When Data is specified as a String, all bytes are converted to 16-bit Unicode characters according to the default ANSI code page specified on the system. If the code page is not ASCII, multi-byte characters convert to single Unicode characters. This is not as efficient as receiving into a large Byte array. The most efficient transfer is possible when a large global Byte array is allocated once, and all network data is repeatedly read into the same array (a single memory transfer takes place directly from the system buffers into the global Byte array allocated in the user's application).

If Timeout is greater than 0, the method completes without error if at least 1 byte is received (a positive Count is returned) or the remote host closes the connection (a 0 Count is returned). A ptTimeout error is generated if at least 1 byte cannot be received within the Timeout period and the connection is still ptConnected. If Timeout is 0, then Count indicates the length of the actual data received, and may be 0 if no data was immediately available (this does not indicate a closed connection). If a ptTimeout error is generated, the session is aborted, and all system resources are released.

The remote host can close the connection at any time. If the remote host closes the connection and there is still data in the system to receive, then the State changes to ptClosing to indicate this condition. You can safely use this method to receive data when the State is either ptConnected or ptClosing. You may call this method with Timeout greater than 0 and the remote host closes the connection while you are waiting for Data. In this case no error is generated, but a 0 Count is returned and State will be ptClosed when the method returns.

Blocked returns True while performing a blocking method (Timeout is greater than 0).

Note Some environments, such as JavaScript, do not support the passing of parameters by reference. Consequently, such methods as Receive cannot be used by passing in a String. You can use the DartStream Object to circumvent this limitation (see the ReadString method Remarks section for a Java sample).

Error Codes
The Receive method may generate the following error codes (refer to the ErrorConstants topic for a complete list of error codes):

ptAbort
ptBlocked
ptConnectionAborted
ptConnectionReset
ptInvalidParam1 (Data is not a String or Byte array)
ptNetworkDown
ptNetworkReset
ptNotConnected
ptTimeout

Example

This VB example shows how to establish a Telnet connection and view the details in a VT Control.

Receive Method Example (Visual Basic)

Private Sub Telnet1_Receive()
On Error GoTo OnError ' use intrinsic error handling
	Dim s() As Byte
	Dim r As Long
	' when data arrives, receive it and put it into the VT Control
	r = Telnet1.Receive(s)
	If r > 0 Then
	Vt1.Display s
	End If
	Exit Sub
OnError: ' Any error jumps here
	Debug.Print "Error #" + CStr(Err.Number) + ": " + Err.Description
End Sub