Reads an array of 32-bit integers from the stream.

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

Syntax

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

Parameters

buffer
Type: array< System..::.Int32 >[]()[]
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 will be equal to the number of elements in the buffer or no elements will be read.

Return Value

Returns 1 on success. If not enough data is available and the connection has been closed gracefully then 0 is returned. If not enough 32-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 an array of 32-bit integers over a client stream. It differs from the Receive(array<Int32>[]()[]) method in that it treats the entire array as an atomic unit. It either receives all of the array or none of it. This method is particularly useful for non-blocking streams because it ensures that all the values requested are read at one time.

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 32-bit integer sent or received.

Unlike the Receive(array<Int32>[]()[]) method, the size of the stream receive buffer must be at least as large as the array of 32-bit integers being received.

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 32-bit integers are available than the size of the entire array 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 1.

If the connection has been closed gracefully then it returns 0 only if there are fewer 32-bit integers to receive than the size of the entire array. Otherwise it returns 1. Once there are fewer 32-bit integers left to receive than the size of the entire array 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 ReceiveArray at the same time. However, SendArray or Flush()()() may be called by another thread at the same time as ReceiveArray.

The BSD socket API has no equivalent to this method.

Examples

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

numElementsRead = stream.ReceiveArray(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 Integer ' create a 5 element vector
Dim numElementsRead As Integer

numElementsRead = stream.ReceiveArray(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<int>^ buffer = gcnew array<int>(5);
int numElementsRead;

numElementsRead = stream->ReceiveArray(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