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

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

Syntax

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

Parameters

buffer
Type: array< System..::.Int16 >[]()[]
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 16-bit integers received, which may be less than the number of elements in the buffer for non-blocking streams. If fewer bytes are available than the size of a 16-bit integer and the connection has been closed gracefully then 0 is returned. If no 16-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 16-bit integers from the communication channel. If the stream has been configured to swap bytes using the SetSwapBytes(Boolean) method then it will swap the order of the bytes within each 16-bit integer that it receives or sends.

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 Listen or Connect was called with the non-blocking flag set to true, then this method does not block. If fewer bytes are available than the size of a 16-bit integer 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 16-bit integers received.

If the connection has been closed gracefully then it returns 0 only if there are fewer bytes to receive than the size of a 16-bit integer. Otherwise it returns the number of 16-bit integers read before the connection closed. Once there are fewer bytes left to receive than the size of a 16-bit integer then it will return 0 to indicate the connection has been closed. Use Receive(array<SByte>[]()[]) to receive any remaining bytes if required. If an error occurs, then it throws a StreamException.

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 BSD socket API has no equivalent to this method.

Unlike the ReceiveArray(array<Int16>[]()[]) method, this method does not require that the internal stream receive buffer be as large as the array of 16-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 16-bit integers from a stream.
C# Copy Code
short [] buffer = new short [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 Short ' 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<short>^ buffer = gcnew array<short>(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