quanser.communications.stream.accept :: QUARC MATLAB Functions

navigation bar

quanser.communications.stream.accept

Accepts a connection from a client.

Syntax

[new_stream, would_block] = stream.accept(send_buffer_size, receive_buffer_size)
[new_stream, would_block] = stream.accept(buffer_size)  % use buffer size for both send and receive buffers.
[new_stream, would_block] = stream.accept               % use default buffer size of 8000.

Description

Accepts a connection from a client and returns a new stream for communicating with that client. The stream argument must have been created using the quanser.communications.stream.listen function. Only listening streams can accept connections. In general, the listening stream may be used to accept more than one connection. The only exceptions are protocols which do not support multiple connections over the same communication channel at the same time, like the serial protocol.

Streams are normally blocking. For blocking streams, the stream_accept call will not return until a connection is made. For non-blocking listening streams, the stream_accept call will return immediately. However, if would_block is true then no connection was made. In this case the new_stream output is not valid and should not be used. The poll function may be used with the 'accept' flag to determine when a connection is pending.

Streams maintain an internal buffer. Reading and writing from a stream reads and writes to or from this buffer. The underlying communication channel is only accessed when the buffer is empty (in the case of reads) or the buffer is full (in the case of writes). A buffer that is not full may be prematurely written to the underlying communication channel using the flush function. The send_buffer_size and receive_buffer_size arguments indicate the size of this internal buffer for send and receive operations respectively.

When a connection is accepted, the new_stream output is a handle to a new stream representing the connection. This stream handle may be used to send and receive data over the connection. The listening stream is not closed and may be used to accept additional client connections.

When finished with the stream, the stream must be closed with close or quanser.communications.stream.close_all.

Parameters

stream

A listening stream created using quanser.communications.stream.listen.

buffer_size

A scalar indicating the buffer size to use for the send and receive buffers of the new stream.

send_buffer_size

A scalar indicating the buffer size to use for the send buffer of the new stream.

receive_buffer_size

A scalar indicating the buffer size to use for the receive buffer of the new stream.

Outputs

new_stream

A handle to the connected stream for use with the other Quanser Stream functions.

would_block

A logical scalar used with non-blocking streams to indicate if a connection was not accepted, in which case would_block is true. Otherwise would_block is false. Failure to supply this second argument for non-blocking streams will result in an error. If this argument is supplied for a blocking stream then it always returns false.

Examples

        client = stream.accept;     % Accept a connection.
        ...
        client.close;               % Close the client stream to release resources.
        stream.close;               % Close the listening stream to release resources.