stream_ignore :: Quanser C Functions

navigation bar

stream_ignore

Receives data over a client stream.

Description

This function receives data over a client stream. However this data is simply discarded. It is not returned to the caller. It attempts to receive length bytes from the communication channel.

If stream_listen or stream_connect was called with the non-blocking flag set to false (0), then this function blocks until all the data is read. If the connection has been closed gracefully then it returns 0 only once there is no more data to receive. Otherwise it returns the number of bytes read before the connection closed. Once all the data in the stream buffer is exhausted it will return 0 to indicate the connection has been closed. If an error occurs, then it returns a negative error code.

If stream_listen or stream_connect was called with the non-blocking flag set to true (1), then this function does not block. If no data is available at all then it returns -QERR_WOULD_BLOCK. In this case, the stream_poll function may be used with the STREAM_POLL_RECEIVE flag to determine when data becomes available. Otherwise it returns the number of bytes received.

This function does not support two threads calling stream_receive at the same time. However, stream_send or stream_flush may be called by another thread at the same time as stream_receive.

The semantics of this function differ from the BSD recv() socket function because it receives length bytes in blocking mode rather than the number of bytes that were sent in a single send() call at the peer. The semantics differ because this function attempts to "read ahead" by keeping the stream buffer full, thereby minimizing the number of receive operations performed on the internal connection. Also, due to buffering of the stream_send operation, the number of send() calls made at the peer may not correspond to the number expected.

Prototype

t_int
stream_ignore(t_stream stream, t_int length);

Parameters

t_stream stream

A client stream established using stream_connect or stream_accept.

t_int length

The number of bytes to ignore.

Return value

The number of bytes received, which may be less than length bytes for non-blocking streams. If no more data is available and the connection has been closed gracefully then 0 is returned. If an error occurs then a negative error code is returned.

Error codes

This function does not return any error code.

Requirements

Include Files	Libraries
quanser_stream.h	quanser_communications.lib;quanser_runtime.lib;quanser_common.lib