stream_connect :: QUARC MATLAB Functions

navigation bar

stream_connect

Connects to a server.

Syntax

[stream, would_block] = stream_connect(uri, nonblocking, send_buffer_size, receive_buffer_size)
[stream, would_block] = stream_connect(uri, nonblocking, buffer_size)               % use buffer size for send and receive buffers
[stream, would_block] = stream_connect(uri, nonblocking)                            % uses default buffer size of 8000
[stream, would_block] = stream_connect(uri, send_buffer_size, receive_buffer_size)  % blocking with specified buffer sizes
[stream, would_block] = stream_connect(uri, buffer_size)                            % blocking with specified buffer size
[stream, would_block] = stream_connect(uri)                                         % blocking with default buffer size of 8000

Description

Connects to a server. The communication protocol, hostname, port and options are specified via the first argument, which takes the form of a Universal Resource Identifier (URI). For example, 'tcpip://remhost:18000' indicates that a connection will be made using the TCP/IP protocol to a server on the remhost machine serving on TCP/IP port 18000. Likewise, 'shmem://mymemory:1' indicates that a connection will be made using the shared memory protocol to a server on the same machine serving on shared memory 'mymemory' and port 1. Refer to the help on Universal Resource Identifiers or the Stream Connect block for Simulink for more information.

Streams are normally blocking. For blocking streams, the stream_connect call will not return until either the connection is made or a timeout occurs. For non-blocking streams, the stream_connect call will return immediately. However, if would_block is true then the connection is pending and stream_poll must be called with the 'connect' flag to complete the connection.

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 stream_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 finished with the stream, the stream must be closed with stream_close or stream_close_all.

Parameters

uri

A string containing the URI. eg. 'tcpip://quanser-dev:18000' or 'shmem://comm_server:1'.

nonblocking

A boolean indicating whether the stream is nonblocking (true or 1) or blocking (false or 0).

buffer_size

A scalar indicating the buffer size to use for the send and receive buffers for the stream. Must be greater than 1 when only two or three arguments are specified.

send_buffer_size

A scalar indicating the buffer size to use for the send buffer for the stream. Must be greater than 1 when only three arguments are specified.

receive_buffer_size

A scalar indicating the buffer size to use for the receive buffer for the stream. Must be greater than 1 when only three arguments are specified.

Outputs

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 is pending, 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

Blocking I/O Example

stream = stream_connect('tcpip://remhost:18000');     % Connect via TCP/IP to port 18000 on remhost.
...
stream_close(stream);                                 % Close the stream to release resources.

Non-Blocking I/O Example

[stream, would_block] = stream_connect('tcpip://remhost:18000', true); % Connect non-blocking via TCP/IP to port 18000 on remhost.
if would_block                                                         % Stream is in the process of connecting but not yet connected.
    satisfied = stream_poll(stream, 30, 'connect');                    % Wait up to 30 seconds for it to finish connecting.
    if satisfied <= 0                                                  % Failed to finish connecting within the timeout interval.
        stream_close(stream);                                          % Make sure stream resources are freed before issuing error message.
        error('Could not connect to tcpip://remhost:18000');           % Issue error message that we could not connect.
    end
end                                                                    % If would_block was false then we connected immediately.

% At this point we are connected.
            ...
stream_close(stream);                                                  % Close the stream to release resources.