Description

The QDMI Device implementation of the DCDB at Leibniz Supercomputing Centre.

The Data Center Data Base (DCDB) is a modular, continuous, and holistic monitoring framework targeted at HPC telemetries. This device implementation allows a QDMI Client to query the telemetry data from LRZ's DCDB Instance.

Classes
struct	DCDB_QDMI_Device_TelemetrySensor_Query_impl_d
	Device-side implementation of the encapsulated type `QDMI_Device_TelemetrySensor_Query`. More...

Macros
#define	ADD_STRING_PROPERTY(prop_name, prop_value, prop, size, value, size_ret)
	Adds a string property to the device.

#define	ADD_SINGLE_VALUE_PROPERTY(prop_name, prop_type, prop_value, prop, size, value, size_ret)
	Adds a primitive typed value property to the device.

#define	ADD_LIST_PROPERTY(prop_name, prop_type, prop_values, prop, size, value, size_ret)
	Adds a list typed value property to the device.

Functions
static QDMI_Device_Status *	DCDB_QDMI_get_device_status (void)
	Static function to maintain the device status.

QDMI_Device_Status	DCDB_QDMI_read_device_status (void)
	The local function to read the device status.

void	DCDB_QDMI_set_device_status (QDMI_Device_Status status)
	The local function to set the device status.

int	DCDB_QDMI_device_initialize ()
	The function to initiate the DCDB Device.

int	DCDB_QDMI_device_finalize ()
	The function to finalize the DCDB Device.

int	DCDB_QDMI_device_session_alloc (DCDB_QDMI_Device_Session *session)
	The function to allocate a session for the DCDB device.

int	DCDB_QDMI_device_session_init (DCDB_QDMI_Device_Session session)
	The function to init the session.

void	DCDB_QDMI_device_session_free (DCDB_QDMI_Device_Session session)
	The function to free the session.

int	DCDB_QDMI_device_session_set_parameter (DCDB_QDMI_Device_Session session, const QDMI_Device_Session_Parameter param, const size_t size, const void *value)
	Set a parameter for the device session.

int	DCDB_QDMI_device_session_create_device_job (DCDB_QDMI_Device_Session session, DCDB_QDMI_Device_Job *job)
	Creates a job.

void	DCDB_QDMI_device_job_free (DCDB_QDMI_Device_Job job)
	Frees the job.

int	DCDB_QDMI_device_job_set_parameter (DCDB_QDMI_Device_Job job, const QDMI_Device_Job_Parameter param, const size_t size, const void *value)
	Sets parameters for the job.

int	DCDB_QDMI_device_job_submit (DCDB_QDMI_Device_Job job)
	Submits the job to the device.

int	DCDB_QDMI_device_job_cancel (DCDB_QDMI_Device_Job job)
	Cancels a submitted job to the device.

int	DCDB_QDMI_device_job_check (DCDB_QDMI_Device_Job job, QDMI_Job_Status *status)
	Checks the status of the job.

int	DCDB_QDMI_device_job_wait (DCDB_QDMI_Device_Job job, size_t timeout)
	Waits the job to be completed.

int	DCDB_QDMI_device_job_get_results (DCDB_QDMI_Device_Job job, QDMI_Job_Result result, const size_t size, void data, size_t size_ret)
	Gets the results of the job.

int	DCDB_QDMI_device_session_query_device_property (DCDB_QDMI_Device_Session session, const QDMI_Device_Property prop, const size_t size, void value, size_t size_ret)
	Queries the device's properties.

int	DCDB_QDMI_device_session_query_site_property (DCDB_QDMI_Device_Session session, DCDB_QDMI_Site site, const QDMI_Site_Property prop, const size_t size, void value, size_t size_ret)
	Queries a site property.

int	DCDB_QDMI_device_session_query_operation_property (DCDB_QDMI_Device_Session session, DCDB_QDMI_Operation operation, const size_t num_sites, const DCDB_QDMI_Site sites, const size_t num_params, const double params, const QDMI_Operation_Property prop, const size_t size, void value, size_t size_ret)
	Queries a operation property.

int	DCDB_QDMI_device_session_query_telemetrysensor_property (DCDB_QDMI_Device_Session session, DCDB_QDMI_TelemetrySensor telemetrysensor, QDMI_TelemetrySensor_Property prop, size_t size, void value, size_t size_ret)
	Query a telemetry sensor property.

int	DCDB_QDMI_device_session_create_device_telemetrysensor_query (DCDB_QDMI_Device_Session session, DCDB_QDMI_Device_TelemetrySensor_Query *query)
	Create a telemetry sensor query.

int	DCDB_QDMI_device_telemetrysensor_query_set_parameter (DCDB_QDMI_Device_TelemetrySensor_Query query, QDMI_Device_TelemetrySensor_Query_Parameter param, size_t size, const void *value)
	Set a parameter for a telemetry sensor query.

void	submit_query (DCDB_QDMI_Device_TelemetrySensor_Query query)
	The auxiliary function to submit a telemetry sensor query.

int	DCDB_QDMI_device_telemetrysensor_query_submit (DCDB_QDMI_Device_TelemetrySensor_Query query)
	Submit a telemetry sensor query to the device.

int	DCDB_QDMI_device_telemetrysensor_query_get_results (DCDB_QDMI_Device_TelemetrySensor_Query query, QDMI_TelemetrySensor_Query_Result result, size_t size, void data, size_t size_ret)
	Retrieve the results of a telemetry sensor query.

int	DCDB_QDMI_device_telemetrysensor_query_check_status (DCDB_QDMI_Device_TelemetrySensor_Query query, QDMI_TelemetrySensor_Query_Status *status)
	Check the status of the telemetry sensor query.

int	DCDB_QDMI_device_telemetrysensor_query_wait (DCDB_QDMI_Device_TelemetrySensor_Query query, size_t timeout)
	Wait for a telemetry sensor query to finish.

int	DCDB_QDMI_device_telemetrysensor_query_cancel (DCDB_QDMI_Device_TelemetrySensor_Query query)
	Cancel an already submitted telemetry sensor query.

void	DCDB_QDMI_device_telemetrysensor_query_free (DCDB_QDMI_Device_TelemetrySensor_Query query)
	Free a telemetry sensor query.

int	DCDB_QDMI_device_job_query_property (DCDB_QDMI_Device_Job job, QDMI_Device_Job_Property prop, size_t size, void value, size_t size_ret)
	Query a job property.

Macro Definition Documentation

◆ ADD_STRING_PROPERTY

#define ADD_STRING_PROPERTY	(	prop_name,
		prop_value,
		prop,
		size,
		value,
		size_ret )

Value:

  {                                                                            \
    if ((prop) == (prop_name)) {                                               \
      if ((value) != NULL) {                                                   \
        if ((size) < strlen(prop_value) + 1) {                                 \
          return QDMI_ERROR_INVALIDARGUMENT;                                   \
        }                                                                      \
        strncpy((char *)(value), prop_value, (size) - 1);                      \
        ((char *)(value))[(size) - 1] = '\0';                                  \
      }                                                                        \
      if ((size_ret) != NULL) {                                                \
        *(size_ret) = strlen(prop_value) + 1;                                  \
      }                                                                        \
      return QDMI_SUCCESS;                                                     \
    }                                                                          \
  }

Adds a string property to the device.

This macro copies the value of the prop_value to the value if prop_name and the prop matches. If specified, the required size is written in size_ret.

Parameters

prop_name	The name of the property
prop_value	The string value of the property (`char*`)
prop	The property name passed as input
size	The size of the memory pointed to by `value`.
value	Pointer to the memory location where `prop_value` will be copied.
size_ret	If specified, the required size is written.

Returns: If successful, QDMI_SUCCESS. If the size is not sufficient, QDMI_ERROR_INVALIDARGUMENT

Note: This value is taken adapted from the example C++ device in the QDMI repository.

◆ ADD_SINGLE_VALUE_PROPERTY

#define ADD_SINGLE_VALUE_PROPERTY	(	prop_name,
		prop_type,
		prop_value,
		prop,
		size,
		value,
		size_ret )

Value:

  {                                                                            \
    if ((prop) == (prop_name)) {                                               \
      if ((value) != NULL) {                                                   \
        if ((size) < sizeof(prop_type)) {                                      \
          return QDMI_ERROR_INVALIDARGUMENT;                                   \
        }                                                                      \
        *(prop_type *)(value) = prop_value;                                    \
      }                                                                        \
      if ((size_ret) != NULL) {                                                \
        *(size_ret) = sizeof(prop_type);                                       \
      }                                                                        \
      return QDMI_SUCCESS;                                                     \
    }                                                                          \
  }

Adds a primitive typed value property to the device.

This macro copies the value of the prop_value to the value if prop_name and the prop matches. If specified, the required size is written in size_ret.

Parameters

prop_name	The name of the property
prop_type	The type of the property, i.e, `char`, `ìnt`.
prop_value	The value of the property.
prop	The property name passed as input
size	The size of the memory pointed to by `value`.
value	Pointer to the memory location where `prop_value` will be copied.
size_ret	If specified, the required size is written.

Returns: If successful, QDMI_SUCCESS. If the size is not sufficient, QDMI_ERROR_INVALIDARGUMENT

Note: This value is taken adapted from the example C++ device in the QDMI repository.

◆ ADD_LIST_PROPERTY

#define ADD_LIST_PROPERTY	(	prop_name,
		prop_type,
		prop_values,
		prop,
		size,
		value,
		size_ret )

Value:

  {                                                                            \
    if ((prop) == (prop_name)) {                                               \
      if ((value) != nullptr) {                                                \
        if ((size) < (prop_values).size() * sizeof(prop_type)) {               \
          return QDMI_ERROR_INVALIDARGUMENT;                                   \
        }                                                                      \
        memcpy(static_cast<void *>(value),                                     \
               static_cast<const void *>((prop_values).data()),                \
               (prop_values).size() * sizeof(prop_type));                      \
      }                                                                        \
      if ((size_ret) != nullptr) {                                             \
        *size_ret = (prop_values).size() * sizeof(prop_type);                  \
      }                                                                        \
      return QDMI_SUCCESS;                                                     \
    }                                                                          \
  }

Adds a list typed value property to the device.

This macro copies the value of the prop_value to the value if prop_name and the prop matches. If specified, the required size is written in size_ret.

Parameters

prop_name	The name of the property
prop_type	The type of the property, i.e, `double`, `ìnt`.
prop_values	The values of the property.
prop	The property name passed as input
size	The size of the memory pointed to by `value`.
value	Pointer to the memory location where `prop_value` will be copied.
size_ret	If specified, the required size is written.

Returns: If successful, QDMI_SUCCESS. If the size is not sufficient, QDMI_ERROR_INVALIDARGUMENT

Note: This value is taken adapted from the example C++ device in the QDMI repository.

Function Documentation

◆ DCDB_QDMI_get_device_status()

static QDMI_Device_Status * DCDB_QDMI_get_device_status ( void )

static

Static function to maintain the device status.

Returns: A pointer to the device status.

Note: This function should not be used outside of this file. Therefore, it is not part of any header file.

◆ DCDB_QDMI_read_device_status()

QDMI_Device_Status DCDB_QDMI_read_device_status ( void )

The local function to read the device status.

Returns: The current device status.

Note: This function should not be used outside of this file. Therefore, it is not part of any header file.

◆ DCDB_QDMI_set_device_status()

void DCDB_QDMI_set_device_status ( QDMI_Device_Status status )

The local function to set the device status.

Parameters

status the new device status.

Note: This function should not be used outside of this file. Therefore, it is not part of any header file.

◆ DCDB_QDMI_device_initialize()

int DCDB_QDMI_device_initialize ( )

The function to initiate the DCDB Device.

This function is called to turn on the device's functionalities. The device can only be used after this function is called.

Returns: QDMI_SUCCESS.

◆ DCDB_QDMI_device_finalize()

int DCDB_QDMI_device_finalize ( )

The function to finalize the DCDB Device.

The QDMI_Client calls this function to turn off the device's functionalities. After this function is called, the device cannot be used.

Returns: QDMI_SUCCESS.

◆ DCDB_QDMI_device_session_alloc()

int DCDB_QDMI_device_session_alloc ( DCDB_QDMI_Device_Session * session )

The function to allocate a session for the DCDB device.

The function is the main entry point for a driver to establish a session with the DCDB Device. The returned handle can be used to refer to the session throughout the device session interface.

Parameters

[out] session A handle to the session that is allocated. Must not be NULL. The session must be freed by calling DCDB_QDMI_device_session_free when it is no longer used.

Returns: QDMI_SUCCESS if the session was allocated successfully.; QDMI_ERROR_INVALIDARGUMENT if the session is NULL.; QDMI_ERROR_OUTOFMEM if memory space ran out.; QDMI_ERROR_FATAL if an unexpected error occurred.

See also: DCDB_QDMI_device_session_init; DCDB_QDMI_device_session_set_parameter; DCDB_QDMI_device_session_free

◆ DCDB_QDMI_device_session_init()

int DCDB_QDMI_device_session_init ( DCDB_QDMI_Device_Session session )

The function to init the session.

This function establishes a connection to the DCDB host using DCDB_QDMI_Device_Session_impl_d::connect function.

Parameters

[out] session A handle to the session that is initialted. Must not be NULL. The session must be freed by calling DCDB_QDMI_device_session_free when it is no longer used.

Returns: QDMI_SUCCESS if the session was allocated successfully.; QDMI_ERROR_INVALIDARGUMENT if the session is NULL.; QDMI_ERROR_FATAL if an unexpected error occurred.

See also: DCDB_QDMI_device_session_alloc; DCDB_QDMI_device_session_set_parameter; DCDB_QDMI_device_session_free

◆ DCDB_QDMI_device_session_free()

void DCDB_QDMI_device_session_free ( DCDB_QDMI_Device_Session session )

The function to free the session.

This function frees the session. After the session is freed, it cannot be used. While freing, the existing connection closes as well.

Parameters

[in] session A handle to the session that is freed.

See also: DCDB_QDMI_device_session_alloc; DCDB_QDMI_device_session_init; DCDB_QDMI_device_session_set_parameter

◆ DCDB_QDMI_device_session_set_parameter()

int DCDB_QDMI_device_session_set_parameter	(	DCDB_QDMI_Device_Session	session,
		const QDMI_Device_Session_Parameter	param,
		const size_t	size,
		const void *	value )

Set a parameter for the device session.

This function is used to set parameters for not-initiated, yet allocated sessions. The set parameters are used to connecting to the DCDB host.

Parameters

[in]	session	A handle to the session to set the parameter for. Must not be `NULL`.
[in]	param	The parameter to set. Must be one of the values specified for QDMI_Device_Session_Parameter
[in]	size	The size of the data pointed by `value` in bytes. Must not be zero, except when `value` is `NULL`, in which case it is ignored.
[in]	value	A pointer to the memory location that contains the value of the parameter to be set. The data pointed to by `value` is copied and can be safely reused after this function returns. If this is `NULL`, it is ignored.

Returns

QDMI_SUCCESS if the device supports the specified QDMI_Device_Session_Parameter and, when value is not NULL, the value of the parameter was set successfully.

QDMI_ERROR_NOTSUPPORTED if the device does not support the parameter or the value of the parameter.

QDMI_ERROR_INVALIDARGUMENT if

session is NULL,
param is invalid, or
value is not NULL and size is zero or not the expected size for the parameter (if specified by the QDMI_Device_Session_Parameter documentation).

QDMI_ERROR_BADSTATE if the parameter cannot be set in the current state of the session, for example, because the session is not allocated or is initialized.

QDMI_ERROR_FATAL if an unexpected error occurred.

See also: DCDB_QDMI_device_session_alloc; DCDB_QDMI_device_session_init; DCDB_QDMI_device_session_free

◆ DCDB_QDMI_device_session_create_device_job()

int DCDB_QDMI_device_session_create_device_job	(	DCDB_QDMI_Device_Session	session,
		DCDB_QDMI_Device_Job *	job )

Creates a job.

Despite the presence of the functions from the QDMI Device Job Interface, they are not operational since the DCDB device does not support QDMI_Job.

Parameters

[in]	session	The session to create the job on.
[out]	job	A pointer to a handle that will store the created job.

Returns: QDMI_ERROR_NOTSUPPORTED

◆ DCDB_QDMI_device_job_free()

void DCDB_QDMI_device_job_free ( DCDB_QDMI_Device_Job job )

Frees the job.

Parameters

[in] job The job to free.

See also: DCDB_QDMI_device_session_create_device_job

◆ DCDB_QDMI_device_job_set_parameter()

int DCDB_QDMI_device_job_set_parameter	(	DCDB_QDMI_Device_Job	job,
		const QDMI_Device_Job_Parameter	param,
		const size_t	size,
		const void *	value )

Sets parameters for the job.

See also: DCDB_QDMI_device_session_create_device_job

Parameters

[in]	job	A handle to a job for which to set `param`.
[in]	param	The parameter whose value will be set.
[in]	size	The size of the data pointed to by `value` in bytes.
[in]	value	A pointer to the memory location that contains the value of the parameter to be set.

Returns: QDMI_ERROR_NOTSUPPORTED

◆ DCDB_QDMI_device_job_submit()

int DCDB_QDMI_device_job_submit ( DCDB_QDMI_Device_Job job )

Submits the job to the device.

Parameters

[in] job The job to submit.

See also: DCDB_QDMI_device_session_create_device_job

Returns: QDMI_ERROR_NOTSUPPORTED

◆ DCDB_QDMI_device_job_cancel()

int DCDB_QDMI_device_job_cancel ( DCDB_QDMI_Device_Job job )

Cancels a submitted job to the device.

Parameters

[in] job The job to cancel.

See also: DCDB_QDMI_device_session_create_device_job

Returns: QDMI_ERROR_NOTSUPPORTED

◆ DCDB_QDMI_device_job_check()

int DCDB_QDMI_device_job_check	(	DCDB_QDMI_Device_Job	job,
		QDMI_Job_Status *	status )

Checks the status of the job.

Parameters

[in]	job	The job to check the status of.
[out]	status	The status of the job.

See also: DCDB_QDMI_device_session_create_device_job

Returns: QDMI_ERROR_NOTSUPPORTED

◆ DCDB_QDMI_device_job_wait()

int DCDB_QDMI_device_job_wait	(	DCDB_QDMI_Device_Job	job,
		size_t	timeout )

Waits the job to be completed.

Parameters

[in]	job	The job to wait for.
[in]	timeout	The timeout in seconds.

See also: DCDB_QDMI_device_session_create_device_job

Returns: QDMI_ERROR_NOTSUPPORTED

◆ DCDB_QDMI_device_job_get_results()

int DCDB_QDMI_device_job_get_results	(	DCDB_QDMI_Device_Job	job,
		QDMI_Job_Result	result,
		const size_t	size,
		void *	data,
		size_t *	size_ret )

Gets the results of the job.

See also: DCDB_QDMI_device_session_create_device_job

Parameters

[in]	job	The job to retrieve the results from.
[in]	result	The result to retrieve.
[in]	size	The size of the buffer pointed to by `data` in bytes.
[out]	data	A pointer to the memory location where the results will be stored.
[out]	size_ret	The actual size of the data being queried in bytes.

Returns: QDMI_ERROR_NOTSUPPORTED

◆ DCDB_QDMI_device_session_query_device_property()

int DCDB_QDMI_device_session_query_device_property	(	DCDB_QDMI_Device_Session	session,
		const QDMI_Device_Property	prop,
		const size_t	size,
		void *	value,
		size_t *	size_ret )

Queries the device's properties.

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 is 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 the value is not NULL, the property was successfully retrieved.

QDMI_ERROR_NOTSUPPORTED if the device does not support the property.

QDMI_ERROR_INVALIDARGUMENT if

the session is NULL,
the prop is invalid, or
the value is not NULL and the 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.

See also: ADD_STRING_PROPERTY; ADD_SINGLE_VALUE_PROPERTY; ADD_LIST_PROPERTY

◆ DCDB_QDMI_device_session_query_site_property()

int DCDB_QDMI_device_session_query_site_property	(	DCDB_QDMI_Device_Session	session,
		DCDB_QDMI_Site	site,
		const QDMI_Site_Property	prop,
		const size_t	size,
		void *	value,
		size_t *	size_ret )

Queries a site property.

The DCDB device does not have any QDMI_Site to query.

Parameters

[in]	session	The session used for the query.
[in]	site	The site to query.
[in]	prop	The property to query.
[in]	size	The size of the memory pointed to by `value` in bytes.
[out]	value	A pointer to the memory location where the value of the property will be stored.
[out]	size_ret	The actual size of the data being queried in bytes.

Returns: QDMI_ERROR_NOTSUPPORTED.

◆ DCDB_QDMI_device_session_query_operation_property()

int DCDB_QDMI_device_session_query_operation_property	(	DCDB_QDMI_Device_Session	session,
		DCDB_QDMI_Operation	operation,
		const size_t	num_sites,
		const DCDB_QDMI_Site *	sites,
		const size_t	num_params,
		const double *	params,
		const QDMI_Operation_Property	prop,
		const size_t	size,
		void *	value,
		size_t *	size_ret )

Queries a operation property.

Parameters

[in]	session	The session used for the query.
[in]	operation	The operation to query.
[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.
[in]	num_params	The number of parameters that the operation takes.
[in]	params	A pointer to a list of parameters the operation takes.
[in]	prop	The property to query.
[in]	size	The size of the memory pointed to by `value` in bytes.
[out]	value	A pointer to the memory location where the value of the property will be stored.
[out]	size_ret	The actual size of the data being queried in bytes.

The DCDB device does not have any QDMI_Operation to query.

Returns: QDMI_ERROR_NOTSUPPORTED.

◆ DCDB_QDMI_device_session_query_telemetrysensor_property()

int DCDB_QDMI_device_session_query_telemetrysensor_property	(	DCDB_QDMI_Device_Session	session,
		DCDB_QDMI_TelemetrySensor	telemetrysensor,
		QDMI_TelemetrySensor_Property	prop,
		size_t	size,
		void *	value,
		size_t *	size_ret )

Query a telemetry sensor property.

Parameters

[in]	session	The session used for the query.
[in]	telemetrysensor	The telemetry to query.
[in]	prop	The property to query.
[in]	size	The size of the memory pointed to by `value` in bytes.
[out]	value	A pointer to the memory location where the value of the property will be stored.
[out]	size_ret	The actual size of the data being queried in bytes.

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

See also: ADD_STRING_PROPERTY; ADD_SINGLE_VALUE_PROPERTY; ADD_LIST_PROPERTY

◆ DCDB_QDMI_device_session_create_device_telemetrysensor_query()

int DCDB_QDMI_device_session_create_device_telemetrysensor_query	(	DCDB_QDMI_Device_Session	session,
		DCDB_QDMI_Device_TelemetrySensor_Query *	query )

Create a telemetry sensor query.

This is the main entry point for a driver to create a telemetry sensor query for a device. The returned handle can be used throughout the "device telemetry sensor query interface" to refer to the telemetry sensor query.

Parameters

[in]	session	The session to create the telemetry sensor query on. Must not be `NULL`.
[out]	query	A pointer to a handle that will store the created telemetry sensor query. Must not be `NULL`. The telemetry sensor query must be freed by calling DCDB_QDMI_device_telemetrysensor_query_free when it is no longer used.

Returns: QDMI_SUCCESS if the telemetry sensor query was successfully created.; QDMI_ERROR_INVALIDARGUMENT if session or query are NULL.; QDMI_ERROR_BADSTATE if the session is not in a state allowing the creation of a telemetry sensor query, for example, because the session is not initialized.; QDMI_ERROR_FATAL if telemetry sensor query creation failed due to a fatal error.

See also: DCDB_QDMI_device_telemetrysensor_query_set_parameter; DCDB_QDMI_device_telemetrysensor_query_submit; DCDB_QDMI_device_telemetrysensor_query_get_results; DCDB_QDMI_device_telemetrysensor_query_wait; DCDB_QDMI_device_telemetrysensor_query_check_status; DCDB_QDMI_device_telemetrysensor_query_cancel; DCDB_QDMI_device_telemetrysensor_query_free

◆ DCDB_QDMI_device_telemetrysensor_query_set_parameter()

int DCDB_QDMI_device_telemetrysensor_query_set_parameter	(	DCDB_QDMI_Device_TelemetrySensor_Query	query,
		QDMI_Device_TelemetrySensor_Query_Parameter	param,
		size_t	size,
		const void *	value )

Set a parameter for a telemetry sensor query.

Parameters

[in]	query	A handle to a telemetry sensor query for which to set `param`. Must not be `NULL`.
[in]	param	The parameter whose value will be set. Must be one of the values specified for QDMI_Device_TelemetrySensor_Query_Parameter.
[in]	size	The size of the data pointed to by `value` in bytes. Must not be zero, except when `value` is `NULL`, in which case it is ignored.
[in]	value	A pointer to the memory location that contains the value of the parameter to be set. The data pointed to by `value` is copied and can be safely reused after this function returns. If this is `NULL`, it is ignored.

Returns

QDMI_SUCCESS if the device supports the specified QDMI_Device_Telemetry_Query_Parameter param and, when value is not NULL, the parameter was successfully set.

QDMI_ERROR_NOTSUPPORTED if the device does not support the parameter or the value of the parameter.

QDMI_ERROR_INVALIDARGUMENT if

query is NULL,
param is invalid, or
value is not NULL and size is zero or not the expected size for the parameter (if specified by the QDMI_Device_Telemetry_Query_Parameter documentation).

QDMI_ERROR_BADSTATE if the parameter cannot be set in the current state of the telemetry sensor query, for example, because the telemetry sensor query is already submitted.

QDMI_ERROR_FATAL if setting the parameter failed due to a fatal error.

See also: DCDB_QDMI_Device_TelemetrySensor_Query_impl_d; DCDB_QDMI_device_session_create_telemetry_query; DCDB_QDMI_device_telemetrysensor_query_submit; DCDB_QDMI_device_telemetrysensor_query_get_results; DCDB_QDMI_device_telemetrysensor_query_wait; DCDB_QDMI_device_telemetrysensor_query_check_status; DCDB_QDMI_device_telemetrysensor_query_cancel; DCDB_QDMI_device_telemetrysensor_query_free

◆ submit_query()

void submit_query ( DCDB_QDMI_Device_TelemetrySensor_Query query )

The auxiliary function to submit a telemetry sensor query.

This function is used in the DCDB_QDMI_device_telemetrysensor_query_submit to submit a telemetry sensor query asynchronously

Parameters

[in] query The telemetry sensor query to submit. Must not be NULL.

See also: DCDB_QDMI_device_telemetrysensor_query_submit

◆ DCDB_QDMI_device_telemetrysensor_query_submit()

int DCDB_QDMI_device_telemetrysensor_query_submit ( DCDB_QDMI_Device_TelemetrySensor_Query query )

Submit a telemetry sensor query to the device.

This functions asynchronously submit the telemetry sensor query using the submit_query function. The DCDB_QDMI_device_telemetrysensor_query_check_status function can be used to check the status of the telemetry sensor query.

Parameters

[in] query The telemetry sensor query to submit. Must not be NULL.

Returns: QDMI_SUCCESS if the job was successfully submitted.; QDMI_ERROR_INVALIDARGUMENT if job is NULL.; QDMI_ERROR_BADSTATE if the job is in an invalid state.; QDMI_ERROR_FATAL if the job submission failed.

See also: DCDB_QDMI_device_session_create_telemetry_query; DCDB_QDMI_device_telemetrysensor_query_set_parameter; DCDB_QDMI_device_telemetrysensor_query_get_results; DCDB_QDMI_device_telemetrysensor_query_wait; DCDB_QDMI_device_telemetrysensor_query_check_status; DCDB_QDMI_device_telemetrysensor_query_cancel; DCDB_QDMI_Device_TelemetrySensor_Query_free

◆ DCDB_QDMI_device_telemetrysensor_query_get_results()

int DCDB_QDMI_device_telemetrysensor_query_get_results	(	DCDB_QDMI_Device_TelemetrySensor_Query	query,
		QDMI_TelemetrySensor_Query_Result	result,
		size_t	size,
		void *	data,
		size_t *	size_ret )

Retrieve the results of a telemetry sensor query.

Parameters

[in]	query	The telemetry sensor query to retrieve the results from. Must not be `NULL`.
[in]	result	The result to retrieve. Must be one of the values specified for QDMI_TelemetrySensor_Query_Result.
[in]	size	The size of the buffer pointed to by `data` in bytes. Must be greater or equal to the size of the return type specified for the QDMI_TelemetrySensor_Query_Result `result`, except when `data` is `NULL`, in which case it is ignored.
[out]	data	A pointer to the memory location where the results 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 result and, when data is not NULL, the results were successfully retrieved.

QDMI_ERROR_INVALIDARGUMENT if

query is NULL,
query has not finished,
query was canceled,
result is invalid, or
data is not NULL and size is smaller than the size of the data being queried.

QDMI_ERROR_NOTSUPPORTED if result is not supported.

See also: DCDB_QDMI_device_session_create_telemetry_query; DCDB_QDMI_device_telemetrysensor_query_set_parameter; DCDB_QDMI_device_telemetrysensor_query_submit; DCDB_QDMI_device_telemetrysensor_query_wait; DCDB_QDMI_device_telemetrysensor_query_check_status; DCDB_QDMI_device_telemetrysensor_query_cancel; DCDB_QDMI_Device_TelemetrySensor_Query_free

◆ DCDB_QDMI_device_telemetrysensor_query_check_status()

int DCDB_QDMI_device_telemetrysensor_query_check_status	(	DCDB_QDMI_Device_TelemetrySensor_Query	query,
		QDMI_TelemetrySensor_Query_Status *	status )

Check the status of the telemetry sensor query.

This function is non-blocking and returns immediately with the telemetry sensor query status. Since DCDB_QDMI_device_telemetrysensor_query_submit submits the telemetry sensor query asynchronously, The QDMI_Client must check the status of the telemetry sensor query before calling the DCDB_QDMI_device_telemetrysensor_query_get_results.

Parameters

[in]	query	The telemetry sensor query to check the status of. Must not be `NULL`.
[out]	status	The status of the telemetry sensor query. Must not be `NULL`.

Returns: QDMI_SUCCESS if the telemetry sensor query status was successfully checked.; QDMI_ERROR_INVALIDARGUMENT if query or status is NULL.

See also: DCDB_QDMI_device_session_create_telemetry_query; DCDB_QDMI_device_telemetrysensor_query_set_parameter; DCDB_QDMI_device_telemetrysensor_query_submit; DCDB_QDMI_device_telemetrysensor_query_wait; DCDB_QDMI_device_telemetrysensor_query_get_results; DCDB_QDMI_device_telemetrysensor_query_cancel; DCDB_QDMI_Device_TelemetrySensor_Query_free

◆ DCDB_QDMI_device_telemetrysensor_query_wait()

int DCDB_QDMI_device_telemetrysensor_query_wait	(	DCDB_QDMI_Device_TelemetrySensor_Query	query,
		size_t	timeout )

Wait for a telemetry sensor query to finish.

This function blocks until the submit_query function has finished or has been canceled.

Parameters

[in]	query	The telemetry sensor query to wait for. Must not be `NULL`.
[in]	timeout	The timeout in seconds.

Returns: QDMI_SUCCESS if the telemetry sensor query is finished or canceled.; QDMI_ERROR_INVALIDARGUMENT if query is NULL.

See also: DCDB_QDMI_device_session_create_telemetry_query; DCDB_QDMI_device_telemetrysensor_query_set_parameter; DCDB_QDMI_device_telemetrysensor_query_submit; DCDB_QDMI_device_telemetrysensor_query_check_status; DCDB_QDMI_device_telemetrysensor_query_get_results; DCDB_QDMI_device_telemetrysensor_query_cancel; DCDB_QDMI_Device_TelemetrySensor_Query_free

◆ DCDB_QDMI_device_telemetrysensor_query_cancel()

int DCDB_QDMI_device_telemetrysensor_query_cancel ( DCDB_QDMI_Device_TelemetrySensor_Query query )

Cancel an already submitted telemetry sensor query.

This function changes the status of the telemetry sensor query to QDMI_TELEMETRYSENSOR_QUERY_STATUS_CANCELED.

Parameters

[in] query The telemetry sensor query to cancel. Must not be NULL.

Returns: QDMI_SUCCESS if the telemetry sensor query was successfully canceled.; QDMI_ERROR_INVALIDARGUMENT if query is NULL or the job already has the status QDMI_TELEMETRYSENSOR_QUERY_STATUS_DONE.

See also: DCDB_QDMI_device_session_create_telemetry_query; DCDB_QDMI_device_telemetrysensor_query_set_parameter; DCDB_QDMI_device_telemetrysensor_query_submit; DCDB_QDMI_device_telemetrysensor_query_check_status; DCDB_QDMI_device_telemetrysensor_query_get_results; DCDB_QDMI_device_telemetrysensor_query_wait; DCDB_QDMI_Device_TelemetrySensor_Query_free

◆ DCDB_QDMI_device_telemetrysensor_query_free()

void DCDB_QDMI_device_telemetrysensor_query_free ( DCDB_QDMI_Device_TelemetrySensor_Query query )

Free a telemetry sensor query.

Free the resources associated with a telemetry sensor query. Using a telemetry sensor query handle after it has been freed is undefined behavior.

Parameters

[in] query The telemetry sensor query to free.

See also: DCDB_QDMI_device_session_create_telemetry_query; DCDB_QDMI_device_telemetrysensor_query_set_parameter; DCDB_QDMI_device_telemetrysensor_query_submit; DCDB_QDMI_device_telemetrysensor_query_check_status; DCDB_QDMI_device_telemetrysensor_query_get_results; DCDB_QDMI_device_telemetrysensor_query_wait; DCDB_QDMI_device_telemetrysensor_query_cancel

◆ DCDB_QDMI_device_job_query_property()

int DCDB_QDMI_device_job_query_property	(	DCDB_QDMI_Device_Job	job,
		QDMI_Device_Job_Property	prop,
		size_t	size,
		void *	value,
		size_t *	size_ret )

Query a job property.

See also: DCDB_QDMI_device_session_create_device_job

Parameters

[in]	job	A handle to a job for which to query `prop`. Must not be `NULL`.
[in]	prop	The property to query. Must be one of the values specified for QDMI_Device_Job_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_ERROR_NOTSUPPORTED

Description

Classes

Macros

Functions

Macro Definition Documentation

◆ ADD_STRING_PROPERTY

◆ ADD_SINGLE_VALUE_PROPERTY

◆ ADD_LIST_PROPERTY

Function Documentation

◆ DCDB_QDMI_get_device_status()

◆ DCDB_QDMI_read_device_status()

◆ DCDB_QDMI_set_device_status()

◆ DCDB_QDMI_device_initialize()

◆ DCDB_QDMI_device_finalize()

◆ DCDB_QDMI_device_session_alloc()

◆ DCDB_QDMI_device_session_init()

◆ DCDB_QDMI_device_session_free()

◆ DCDB_QDMI_device_session_set_parameter()

◆ DCDB_QDMI_device_session_create_device_job()

◆ DCDB_QDMI_device_job_free()

◆ DCDB_QDMI_device_job_set_parameter()

◆ DCDB_QDMI_device_job_submit()

◆ DCDB_QDMI_device_job_cancel()

◆ DCDB_QDMI_device_job_check()

◆ DCDB_QDMI_device_job_wait()

◆ DCDB_QDMI_device_job_get_results()

◆ DCDB_QDMI_device_session_query_device_property()

◆ DCDB_QDMI_device_session_query_site_property()

◆ DCDB_QDMI_device_session_query_operation_property()

◆ DCDB_QDMI_device_session_query_telemetrysensor_property()

◆ DCDB_QDMI_device_session_create_device_telemetrysensor_query()

◆ DCDB_QDMI_device_telemetrysensor_query_set_parameter()

◆ submit_query()

◆ DCDB_QDMI_device_telemetrysensor_query_submit()

◆ DCDB_QDMI_device_telemetrysensor_query_get_results()

◆ DCDB_QDMI_device_telemetrysensor_query_check_status()

◆ DCDB_QDMI_device_telemetrysensor_query_wait()

◆ DCDB_QDMI_device_telemetrysensor_query_cancel()

◆ DCDB_QDMI_device_telemetrysensor_query_free()

◆ DCDB_QDMI_device_job_query_property()