Reads the specified number of 8-bit integers from the stream.

Namespace:  Quanser.Communications
Assembly:  Quanser.Communications (in Quanser.Communications.dll)

Syntax

Visual Basic (Declaration)
Public Function Receive ( _
	buffer As SByte() _
) As Integer
C#
public int Receive(
	sbyte[] buffer
)
Visual C++
public:
int Receive(
	array<signed char>^ buffer
)
JavaScript
function receive(buffer);

Parameters

buffer
Type: array< System..::.SByte >[]()[]
The buffer in which to store the values read. The length of this buffer determines the number of elements this method attempts to read. The number of elements read may be less than the number of elements in the buffer, so be sure to check the return value to see how many elements were actually read.

Return Value

The number of 8-bit integers received, which may be less than the number of elements in the buffer for non-blocking streams. If no more data is available and the connection has been closed gracefully then 0 is returned. If no 8-bit integers are received and the method would block then -ErrorCode.WouldBlock is returned for non-blocking streams. If an error occurs then a StreamException is thrown.

Remarks

This method receives data over a client stream. It attempts to receive buffer.Length 8-bit integers from the communication channel.

If Listen or Connect was called with the non-blocking flag set to false, then this method blocks until all the data is read. If the connection has been closed gracefully then it returns 0 only once there is no more data to receive. Otherwise it returns the number of 8-bit integers read before the connection closed. Once all the data in the stream buffer is exhausted it will return 0 to indicate the connection has been closed. If an error occurs, then it throws a StreamException.

If Listen or Connect was called with the non-blocking flag set to true, then this method does not block. If no data is available at all then it returns -ErrorCode.WouldBlock. In this case, the Poll(Timeout, Int32) method may be used with the Receive flag to determine when data becomes available. Otherwise it returns the number of 8-bit integers received.

This method does not support two threads calling Receive at the same time. However, Send or Flush()()() may be called by another thread at the same time as Receive.

The semantics of this method differ from the BSD recv() socket function because it receives buffer.Length bytes in blocking mode rather than the number of bytes that were sent in a single send() call at the peer. The semantics differ because this method attempts to "read ahead" by keeping the stream buffer full, thereby minimizing the number of receive operations performed on the internal connection. Also, due to buffering of the Send operation, the number of send() calls made at the peer may not correspond to the number expected.

Unlike the ReceiveArray(array<SByte>[]()[]) method, this method does not require that the internal stream receive buffer be as large as the array of 8-bit integers received. Hence, it allows smaller stream buffers to be used. The size of the stream receive buffer is set when the stream is created using the Connect or Accept method.

Examples

This code snippet shows how to read up to five 8-bit integers from a stream.
C# Copy Code
sbyte [] buffer = new sbyte [5];
int numElementsRead;

numElementsRead = stream.Receive(buffer);
if (numElementsRead == 0) {
    /* Connection was closed at the peer. Close our end also. */
    stream.Close();
} else if (numElementsRead > 0) {
    /* ... process data received ... */
}
Visual Basic Copy Code
Dim buffer(4) As SByte ' create a 5 element vector
Dim numElementsRead As Integer

numElementsRead = stream.Receive(buffer)
If numElementsRead = 0 Then
    ' Connection was closed at the peer. Close our end also.
    stream.Close()
ElseIf numElementsRead > 0 Then
    ' ... process data received ...
End If
Visual C++ Copy Code
array<char>^ buffer = gcnew array<char>(5);
int numElementsRead;

numElementsRead = stream->Receive(buffer);
if (numElementsRead == 0) {
    /* Connection was closed at the peer. Close our end also. */
    stream->Close();
} else if (numElementsRead > 0) {
    /* ... process data received ... */
}

Exceptions

ExceptionCondition
Quanser.Communications..::.StreamException If an error occurs then an exception is thrown. This situation typically arises if an error has occurred in the underlying communication channel, such as the connection being lost unexpectedly.

See Also