stream_get_boolean_property :: Quanser C Functions

navigation bar

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
    
    ...
}