QDMI Client Session Interface

Description

Provides functions to manage sessions between the client and driver.

A session is a connection between a client and a QDMI driver that allows the client to interact with the driver and the devices it manages.

The typical workflow for a client session is as follows:

• Allocate a session with QDMI_session_alloc.
• Set parameters for the session with QDMI_session_set_parameter.
• Initialize the session with QDMI_session_init.
• Query the available devices with QDMI_session_query_session_property.
• Run client code to interact with the retrieved QDMI_Device handles using the client query interface and the client job interface.
• Free the session with QDMI_session_free when it is no longer needed.

Typedefs
typedef struct QDMI_Session_impl_d *	QDMI_Session
	A handle for a session.
typedef enum QDMI_SESSION_PARAMETER_T	QDMI_Session_Parameter
	Session parameter type.
typedef enum QDMI_SESSION_PROPERTY_T	QDMI_Session_Property
	Session property type.

Enumerations
enum	QDMI_SESSION_PARAMETER_T {   QDMI_SESSION_PARAMETER_TOKEN = 0 , QDMI_SESSION_PARAMETER_USERNAME = 1 , QDMI_SESSION_PARAMETER_PROJECTID = 2 , QDMI_SESSION_PARAMETER_MAX = 3 ,   QDMI_SESSION_PARAMETER_CUSTOM1 = 999999995 , QDMI_SESSION_PARAMETER_CUSTOM2 = 999999996 , QDMI_SESSION_PARAMETER_CUSTOM3 = 999999997 , QDMI_SESSION_PARAMETER_CUSTOM4 = 999999998 ,   QDMI_SESSION_PARAMETER_CUSTOM5 = 999999999 }
	Enum of the session parameters that can be set via QDMI_session_set_parameter. More...
enum	QDMI_SESSION_PROPERTY_T {   QDMI_SESSION_PROPERTY_DEVICES = 0 , QDMI_SESSION_PROPERTY_MAX = 1 , QDMI_SESSION_PROPERTY_CUSTOM1 = 999999995 , QDMI_SESSION_PROPERTY_CUSTOM2 = 999999996 ,   QDMI_SESSION_PROPERTY_CUSTOM3 = 999999997 , QDMI_SESSION_PROPERTY_CUSTOM4 = 999999998 , QDMI_SESSION_PROPERTY_CUSTOM5 = 999999999 }
	Enum of the session properties that can be queried via QDMI_session_query_session_property. More...

Functions
int	QDMI_session_alloc (QDMI_Session *session)
	Allocate a new session.
int	QDMI_session_set_parameter (QDMI_Session session, QDMI_Session_Parameter param, size_t size, const void *value)
	Set a parameter for a session.
int	QDMI_session_init (QDMI_Session session)
	Initialize a session.
int	QDMI_session_query_session_property (QDMI_Session session, QDMI_Session_Property prop, size_t size, void *value, size_t *size_ret)
	Query a property of a session.
void	QDMI_session_free (QDMI_Session session)
	Free a session.

Typedef Documentation

QDMI_Session

typedef struct QDMI_Session_impl_d* QDMI_Session

A handle for a session.

An opaque pointer to a type defined by the driver that encapsulates all information about a session between a client and a QDMI driver.

Enumeration Type Documentation

QDMI_SESSION_PARAMETER_T

enum QDMI_SESSION_PARAMETER_T

Enum of the session parameters that can be set via QDMI_session_set_parameter.

If not noted otherwise, parameters are optional and drivers must not require them to be set.

Enumerator
QDMI_SESSION_PARAMETER_TOKEN	0	char* (string) The token to use for the session. The token is used for authentication within the session. The driver documentation must document if the implementation requires this parameter to be set.
QDMI_SESSION_PARAMETER_USERNAME	1	char* (string) The username to use for the session. The username is used for authentication within the session. The driver documentation must document if the implementation requires this parameter to be set.
QDMI_SESSION_PARAMETER_PROJECTID	2	char* (string) The project ID to use for the session. Can be used to associate the session with a certain project, for example, for accounting purposes. The driver documentation must document if the implementation requires this parameter to be set.
QDMI_SESSION_PARAMETER_MAX	3	The maximum value of the enum. It can be used by drivers for bounds checking and validation of function parameters. Attention This value must remain the last regular member of the enum besides the custom members and must be updated when new members are added.
QDMI_SESSION_PARAMETER_CUSTOM1	999999995	This enum value is reserved for a custom parameter. The driver defines the meaning and the type of this parameter. Attention The value of this enum member must not be changed to maintain binary compatibility.
QDMI_SESSION_PARAMETER_CUSTOM2	999999996	See also QDMI_SESSION_PARAMETER_CUSTOM1
QDMI_SESSION_PARAMETER_CUSTOM3	999999997	See also QDMI_SESSION_PARAMETER_CUSTOM1
QDMI_SESSION_PARAMETER_CUSTOM4	999999998	See also QDMI_SESSION_PARAMETER_CUSTOM1
QDMI_SESSION_PARAMETER_CUSTOM5	999999999	See also QDMI_SESSION_PARAMETER_CUSTOM1

QDMI_SESSION_PROPERTY_T

enum QDMI_SESSION_PROPERTY_T

Enum of the session properties that can be queried via QDMI_session_query_session_property.

If not noted otherwise, properties are optional and drivers must not require them to be set.

Enumerator
QDMI_SESSION_PROPERTY_DEVICES	0	QDMI_Device* (QDMI_Device list) The devices the client has access to.
QDMI_SESSION_PROPERTY_MAX	1	The maximum value of the enum. It can be used by drivers for bounds checking and validation of function parameters. Attention This value must remain the last regular member of the enum besides the custom members and must be updated when new members are added.
QDMI_SESSION_PROPERTY_CUSTOM1	999999995	This enum value is reserved for a custom property. The driver defines the meaning and the type of this property. Attention The value of this enum member must not be changed to maintain binary compatibility.
QDMI_SESSION_PROPERTY_CUSTOM2	999999996	See also QDMI_SESSION_PROPERTY_CUSTOM1
QDMI_SESSION_PROPERTY_CUSTOM3	999999997	See also QDMI_SESSION_PROPERTY_CUSTOM1
QDMI_SESSION_PROPERTY_CUSTOM4	999999998	See also QDMI_SESSION_PROPERTY_CUSTOM1
QDMI_SESSION_PROPERTY_CUSTOM5	999999999	See also QDMI_SESSION_PROPERTY_CUSTOM1

Function Documentation

QDMI_session_alloc()

int QDMI_session_alloc

(

QDMI_Session *

session

)

Allocate a new session.

This is the main entry point for a client to establish a session with a QDMI driver. The returned handle can be used throughout the client session interface to refer to the session.

Parameters

[out]

session

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

Returns

QDMI_SUCCESS if the session was allocated successfully.

QDMI_ERROR_INVALIDARGUMENT if session is NULL.

QDMI_ERROR_OUTOFMEM if memory space ran out.

QDMI_ERROR_FATAL if an unexpected error occurred.

See also

QDMI_session_set_parameter

QDMI_session_init

QDMI_session_set_parameter()

int QDMI_session_set_parameter	(	QDMI_Session	session,
		QDMI_Session_Parameter	param,
		size_t	size,
		const void *	value )

Set a parameter for a session.

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_Session_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 driver supports the specified param and, when value is not NULL, the value of the parameter was set successfully.

QDMI_ERROR_NOTSUPPORTED if the driver 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_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 already initialized.

QDMI_ERROR_FATAL if an unexpected error occurred.

See also

QDMI_session_init

Note

By calling this function with value set to NULL, the function can be used to check if the driver supports the specified parameter without setting a value.

For example, to check whether the driver supports setting a token for authentication, the following code pattern can be used:

// Check if the driver supports setting a token.
auto ret = QDMI_session_set_parameter(
  session, QDMI_SESSION_PARAMETER_TOKEN, 0, nullptr);
if (ret == QDMI_ERROR_NOTSUPPORTED) {
 // The driver does not support setting a token.
}
 
// Set the token.
std::string token = "token";
ret = QDMI_session_set_parameter(
  session, QDMI_SESSION_PARAMETER_TOKEN, token.size() + 1, token.c_str());

QDMI_session_init()

int QDMI_session_init

(

QDMI_Session

session

)

Initialize a session.

This function initializes the session and prepares it for use. The session must be initialized before properties can be queried using QDMI_session_query_session_property. Some devices may require authentication information to be set using QDMI_session_set_parameter before calling this function. A session may only be successfully initialized once.

Parameters

[in]

session

The session to initialize. Must not be NULL.

Returns

QDMI_SUCCESS if the session was initialized successfully.

QDMI_ERROR_PERMISSIONDENIED if the session could not be initialized due to missing permissions. This could be due to missing authentication information that should be set using QDMI_session_set_parameter.

QDMI_ERROR_INVALIDARGUMENT if session is NULL.

QDMI_ERROR_BADSTATE if the session is not in a state allowing initialization, for example, because the session is already initialized.

QDMI_ERROR_FATAL if an unexpected error occurred.

See also

QDMI_session_set_parameter

QDMI_session_query_session_property

QDMI_session_query_session_property()

int QDMI_session_query_session_property	(	QDMI_Session	session,
		QDMI_Session_Property	prop,
		size_t	size,
		void *	value,
		size_t *	size_ret )

Query a property of a session.

Parameters

[in]	session	The session to query. Must not be NULL.
[in]	prop	The property to query. Must be one of the values specified for QDMI_Session_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_Session_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 driver supports the specified property and, when value is not NULL, the property was successfully retrieved.

QDMI_ERROR_NOTSUPPORTED if the driver 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.

Note

By calling this function with value set to NULL, the function can be used to check if the driver 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 will be returned in size_ret if size_ret is not NULL.

For example, to query the devices available in a session, the following code pattern can be used:

// Query the size of the property.
size_t size;
auto ret = QDMI_session_query_session_property(
  session, QDMI_SESSION_PROPERTY_DEVICES, 0, nullptr, &size);
 
// Allocate memory for the property.
auto devices = std::vector<QDMI_Device>(size / sizeof(QDMI_Device));
 
// Query the property.
ret = QDMI_session_query_session_property(
  session, prop, size, static_cast<void*>(devices.data()), nullptr);

Attention

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

QDMI_session_free()

void QDMI_session_free

(

QDMI_Session

session

)

Free a session.

This function frees the memory allocated for the session. Accessing a (dangling) handle to a device that was attached to the session after the session was freed is undefined behavior.

Parameters

[in]

session

The session to free.