Writes the specified array of 32-bit integers to the stream send buffer.

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

Syntax

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

Parameters

buffer
Type: array< System..::.Int32 >[]()[]
The buffer containing the values to write. The length of this buffer determines the number of elements this method attempts to send. The number of elements written is always equal to the length of this buffer if the data is sent successfully. This method never sends part of the array. It sends all of it or none of it.

Return Value

Returns 1 on success. If the entire array could not be written to the stream buffer 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 writes data to the stream send buffer. It attempts to store buffer.Length 32-bit integers in the internal stream buffer. It differs from the Send(array<Int32>[]()[]) method in that it treats the entire array as an atomic unit. It either writes all of the array or none of it. If there is enough room available in the stream buffer then it stores the data in the buffer and returns immediately. The data is not written to the actual communication channel until the stream is flushed using Flush()()() or there is no more room available in the stream buffer. If an error occurs, then it throws a StreamException. If the connection is closed it is considered an error condition.

This method is particularly useful for non-blocking streams because it ensures that all the values requested are written at one time.

Unlike the Send(array<Int32>[]()[]) method, the size of the stream send buffer must be at least as large as the number of 32-bit integers sent. The size of the stream send buffer is set when the stream is created using the Connect or Accept method.

If Listen or Connect was called with the non-blocking flag set to false, then this method may block attempting to flush the stream buffer. All the data will be consumed and 1 is returned. Some of the data may remain in the stream buffer and not be sent until the next time Flush()()() is called or there is no more room available in the stream buffer. If an error occurs then the a StreamException is thrown and the stream should be closed.

If Listen or Connect was called with the non-blocking flag set to true, then this method does not block. It returns 1 if the entire array is sent successfully. If the entire array could not be sent without blocking, then -ErrorCode.WouldBlock is returned. In this case, the Poll(Timeout, Int32) method may be used with the Send flag to determine when space in the buffer becomes available. If an error occurs then a StreamException is thrown and the stream should be closed.

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

The BSD socket API has no equivalent to this method.

Examples

This code snippet shows how to write an array of five 32-bit integers to a stream.
C# Copy Code
int [] buffer = { 2147483647, -2147483648, 31, 41, 59 };
int numElementsWritten;

numElementsWritten = stream.SendArray(buffer);
if (numElementsWritten > 0) {
    /* ... generate next data to send ... */
}
Visual Basic Copy Code
Dim buffer() As Integer = {2147483647, -2147483648, 31, 41, 59}
Dim numElementsWritten As Integer

numElementsWritten = stream.SendArray(buffer)
If numElementsWritten > 0 Then
    ' ... generate next data to send ...
End If
Visual C++ Copy Code
array<int>^ buffer = { 2147483647, -2147483648, 31, 41, 59 };
int numElementsWritten;

numElementsWritten = stream->SendArray(buffer);
if (numElementsWritten > 0) {
    /* ... generate next data to send ... */
}

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