stream_poke_unit :: Quanser C Functions

navigation bar

stream_poke_unit

Writes a "unit" to the stream buffer, where the size of a "unit" is determined by the unit_size parameter.

Description

This function writes a "unit" to the stream buffer, where the size of a "unit" is determined by the unit_size parameter. It attempts to store the unit in the stream buffer. If there is enough room available in the stream buffer then it stores the data in the buffer and returns immediately. However, the stream pointer is not advanced, so the data is not written to the actual communication channel. The data will only be written to the underlying communication channel if stream_poke_end is called. If an error occurs, then it returns a negative error code. If the connection is closed it is considered an error condition.

If the stream has been configured to swap bytes using stream_set_swap_bytes or stream_set_byte_order then this function will swap the order of the bytes within the unit when they are poked.

If stream_listen or stream_connect was called with the non-blocking flag set to false (0), then this function may block attempting to flush the stream buffer (to write out data previously sent and still waiting in the stream buffer). Once the unit is poked into the buffer then 1 is returned. If an error occurs then the error code is returned and the stream should be closed.

If stream_listen or stream_connect was called with the non-blocking flag set to true (1), then this function does not block. It returns 1 if the data is poked successfully. If the unit could not be poked without blocking, then -QERR_WOULD_BLOCK is returned. If an error occurs then the error code is returned and the stream should be closed.

This function does not support two threads poking or flushing data at the same time. However, data may be poked or the stream flushed by another thread at the same time as data is being received.

The BSD socket API has no equivalent to this function.

Prototype

t_int
stream_poke_unit(t_stream stream, t_stream_poke_state * state, const void * unit, t_int unit_size);

Parameters

t_stream stream

A client stream established using stream_connect or stream_accept.

t_stream_poke_state * state

The poke state initialized using stream_poke_begin.

const void * unit

A pointer to the value to be poked.

t_int unit_size

The size of the value.

Return value

Returns 1 on success. 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