QDMI Device Query Interface

Description

Provides functions to query properties of a device.

The query interface enables to query static and dynamic properties of a device and its constituents in a unified fashion. It operates on QDMI_Device_Session handles created via the device session interface.

Functions
int	QDMI_device_session_query_device_property (QDMI_Device_Session session, QDMI_Device_Property prop, size_t size, void *value, size_t *size_ret)
	Query a device property.
int	QDMI_device_session_query_site_property (QDMI_Device_Session session, QDMI_Site site, QDMI_Site_Property prop, size_t size, void *value, size_t *size_ret)
	Query a site property.
int	QDMI_device_session_query_operation_property (QDMI_Device_Session session, QDMI_Operation operation, size_t num_sites, const QDMI_Site *sites, size_t num_params, const double *params, QDMI_Operation_Property prop, size_t size, void *value, size_t *size_ret)
	Query an operation property.

Function Documentation

QDMI_device_session_query_device_property()

int QDMI_device_session_query_device_property	(	QDMI_Device_Session	session,
		QDMI_Device_Property	prop,
		size_t	size,
		void *	value,
		size_t *	size_ret )

Query a device property.

Parameters

[in]	session	The session used for the query. Must not be NULL.
[in]	prop	The property to query. Must be one of the values specified for QDMI_Device_Property.
[in]	size	The size of the memory pointed to by value in bytes. Must be greater or equal to the size of the return type specified for prop, except when value is NULL, in which case it is ignored.
[out]	value	A pointer to the memory location where the value of the property will be stored. If this is NULL, it is ignored.
[out]	size_ret	The actual size of the data being queried in bytes. If this is NULL, it is ignored.

Returns

QDMI_SUCCESS if the device supports the specified property and, when value is not NULL, the property was successfully retrieved.

QDMI_ERROR_NOTSUPPORTED if the device does not support the property.

QDMI_ERROR_INVALIDARGUMENT if

• session is NULL,
• prop is invalid, or
• value is not NULL and size is less than the size of the data being queried.

QDMI_ERROR_BADSTATE if the property cannot be queried in the current state of the session, for example, because the session is not initialized.

QDMI_ERROR_FATAL if an unexpected error occurred.

Remarks

Calling this function with value set to NULL is expected to allow checking if the device supports the specified property without retrieving the property and without the need to provide a buffer for it. Additionally, the size of the buffer needed to retrieve the property is returned in size_ret if size_ret is not NULL. See the QDMI_device_query_device_property documentation for an example.

Attention

May only be called after the session has been initialized with QDMI_device_session_init.

QDMI_device_session_query_site_property()

int QDMI_device_session_query_site_property	(	QDMI_Device_Session	session,
		QDMI_Site	site,
		QDMI_Site_Property	prop,
		size_t	size,
		void *	value,
		size_t *	size_ret )

Query a site property.

Parameters

[in]	session	The session used for the query. Must not be NULL.
[in]	site	The site to query. Must not be NULL.
[in]	prop	The property to query. Must be one of the values specified for QDMI_Site_Property.
[in]	size	The size of the memory pointed to by value in bytes. Must be greater or equal to the size of the return type specified for prop, except when value is NULL, in which case it is ignored.
[out]	value	A pointer to the memory location where the value of the property will be stored. If this is NULL, it is ignored.
[out]	size_ret	The actual size of the data being queried in bytes. If this is NULL, it is ignored.

Returns

QDMI_SUCCESS if the device supports the specified property and, when value is not NULL, the property was successfully retrieved.

QDMI_ERROR_NOTSUPPORTED if the device does not support the property.

QDMI_ERROR_INVALIDARGUMENT if

• session or site is NULL,
• prop is invalid, or
• value is not NULL and size is less than the size of the data being queried.

QDMI_ERROR_BADSTATE if the property cannot be queried in the current state of the session, for example, because the session is not initialized.

QDMI_ERROR_FATAL if an unexpected error occurred.

Remarks

Calling this function with value set to NULL is expected to allow checking if the device supports the specified property without retrieving the property and without the need to provide a buffer for it. Additionally, the size of the buffer needed to retrieve the property is returned in size_ret if size_ret is not NULL. See the QDMI_device_query_site_property documentation for an example.

Attention

May only be called after the session has been initialized with QDMI_device_session_init.

QDMI_device_session_query_operation_property()

int QDMI_device_session_query_operation_property	(	QDMI_Device_Session	session,
		QDMI_Operation	operation,
		size_t	num_sites,
		const QDMI_Site *	sites,
		size_t	num_params,
		const double *	params,
		QDMI_Operation_Property	prop,
		size_t	size,
		void *	value,
		size_t *	size_ret )

Query an operation property.

Parameters

[in]	session	The session used for the query. Must not be NULL.
[in]	operation	The operation to query. Must not be NULL.
[in]	num_sites	The number of sites that the operation is applied to.
[in]	sites	A pointer to a list of handles where the sites that the operation is applied to are stored. If this is NULL, it is ignored.
[in]	num_params	The number of parameters that the operation takes.
[in]	params	A pointer to a list of parameters the operation takes. If this is NULL, it is ignored.
[in]	prop	The property to query. Must be one of the values specified for QDMI_Operation_Property.
[in]	size	The size of the memory pointed to by value in bytes. Must be greater or equal to the size of the return type specified for the QDMI_Operation_Property prop, except when value is NULL, in which case it is ignored.
[out]	value	A pointer to the memory location where the value of the property will be stored. If this is NULL, it is ignored.
[out]	size_ret	The actual size of the data being queried in bytes. If this is NULL, it is ignored.

Returns

QDMI_SUCCESS if the device supports the specified property and, when value is not NULL, the property was successfully retrieved.

QDMI_ERROR_NOTSUPPORTED if the property is not supported by the device or if the queried property cannot be provided for the given sites or parameters.

QDMI_ERROR_INVALIDARGUMENT if

• session or operation are NULL,
• prop is invalid, or
• value is not NULL and size is less than the size of the data being queried.

QDMI_ERROR_BADSTATE if the property cannot be queried in the current state of the session, for example, because the session is not initialized.

QDMI_ERROR_FATAL if an unexpected error occurred.

Remarks

Calling this function with sites set to NULL is expected to allow querying properties of the device that are independent of the sites. A device will return QDMI_ERROR_NOTSUPPORTED if the queried property is site-dependent and sites is NULL.

Calling this function with params set to NULL is expected to allow querying properties of the device that are independent of the values of the parameters. A device will return QDMI_ERROR_NOTSUPPORTED if the queried property is parameter-dependent and params is NULL.

Calling this function with value set to NULL is expected to allow checking if the device supports the specified property without retrieving the property and without the need to provide a buffer for it. Additionally, the size of the buffer needed to retrieve the property is returned in size_ret if size_ret is not NULL. See the QDMI_device_query_operation_property documentation for an example.

Attention

May only be called after the session has been initialized with QDMI_device_session_init.