Table of Contents
stream_receive
Receives data over a client stream.
Description
This function receives data over a client stream. It attempts to receive buffer_size 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.
Unlike the stream_receive_byte_array function, this function does not require that the stream receive buffer be at least buffer_size bytes in length. Hence, it allow smaller stream buffers to be used.
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 buffer_size 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_receive(t_stream stream, void * buffer, t_int buffer_size);
Parameters
t_stream stream
A client stream established using stream_connect or stream_accept.
void * buffer
A buffer of at least buffer_size bytes in which the received data will be stored.
t_int buffer_size
The number of bytes available in the buffer.
Return value
The number of bytes received, which may be less than buffer_size 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 |
See Also
Copyright ©2024 Quanser Inc. This page was generated 2024-10-17. Submit feedback to Quanser about this page.
Link to this page.