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.

Description

Functions

Function Documentation

◆ QDMI_device_session_query_device_property()

◆ QDMI_device_session_query_site_property()

◆ QDMI_device_session_query_operation_property()