Table of Contents
stream_get_boolean_property
Gets the values of the specified boolean properties of the stream.
Description
This function gets the values of the specified boolean properties. Not all protocol drivers support
boolean properties. If the protocol does not support boolean properties then calling this function
will return -QERR_NOT_SUPPORTED
. If a particular boolean property is not recognized
then it will return -QERR_PROPERTY_NOT_RECOGNIZED
.
The stream property functions allow more flexibility in controlling the behaviour of the underlying protocol. For example, a boolean property is used to gain exclusive access to the I2C bus for the i2c protocol.
Protocols may have custom boolean properties. However, there are a set of standard boolean properties which are listed below:
Property |
Access |
Description |
---|---|---|
STREAM_PROPERTY_IS_READ_ONLY |
Read only |
Indicates whether the stream is read-only. This property is currently used by the file protocol. |
STREAM_PROPERTY_IS_WRITE_ONLY |
Read only |
Indicates whether the stream is write-only. This property is currently used by the file protocol. |
STREAM_PROPERTY_IS_EXCLUSIVE |
Read/Write |
Indicates whether the stream currently has exclusive access to the underlying communication channel. This property is currently used by the I2C protocols to gain exclusive access to the I2C bus. In particular, any stream operations done while this property is true will be issued as a combined I2C message so that other bus masters cannot use the bus between stream operations. Combined messages are typically used to read from slave device registers or memory. A write operation sends the register address and is followed by a read to get the register contents. The Stream Write-Read block uses this property to perform atomic write-read operations for this very purpose on the I2C bus. |
STREAM_PROPERTY_NO_READ_AHEAD |
Read only |
Indicates whether the stream disallows reading ahead to fill the stream receive buffer. For some protocols, like I2C, reading ahead does not make sense because I2C devices generally only provide data upon request. |
Prototype
t_error stream_get_boolean_property(t_stream stream, const t_stream_boolean_property properties[], t_uint num_properties, t_boolean buffer[]);
Parameters
t_stream stream
A stream established using stream_listen, stream_connect or stream_accept.
const t_stream_boolean_property * properties
An array of property codes containing the properties to be retrieved.
t_uint num_properties
The number of property codes in the properties array.
t_boolean * buffer
An array in which the property values will be returned. The value at a particular index corresponds to the property code at the same index in the properties array.
Return value
Returns 0 on success. If an error occurs then a negative error code is returned. If the protocol does not support boolean
properties then -QERR_NOT_SUPPORTED
is returned. If a property code is not recognized then it will
return -QERR_PROPERTY_NOT_RECOGNIZED
.
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 |
Examples
t_stream client; const char uri[] = "file:myfile.txt?mode=r"; const t_boolean nonblocking = false; const t_int send_buffer_size = 8000; const t_int receive_buffer_size = 8000; result = stream_connect(uri, nonblocking, send_buffer_size, receive_buffer_size, &client); if (result == 0) { t_stream_boolean_property codes = { STREAM_PROPERTY_IS_READ_ONLY }; t_boolean values[ARRAY_LENGTH(codes)]; result = stream_get_boolean_property(client, codes, ARRAY_LENGTH(codes), values); if (result >= 0) // then property value retrieved ... }
See Also
Copyright ©2024 Quanser Inc. This page was generated 2024-10-17. Submit feedback to Quanser about this page.
Link to this page.