QDMI Device Session Interface

Description

Provides functions to manage sessions between the driver and device.

A device session is a connection between a driver and a device that allows the driver to interact with the device. Sessions are used to authenticate with the device and to manage resources required for the interaction with the device.

The typical workflow for a device session is as follows:

• Allocate a session with QDMI_device_session_alloc.
• Set parameters for the session with QDMI_device_session_set_parameter.
• Initialize the session with QDMI_device_session_init.
• Run code to interact with the device using the device query interface and the device job interface.
• Free the session with QDMI_device_session_free when it is no longer needed.

Typedefs
typedef struct QDMI_Device_Session_impl_d *	QDMI_Device_Session
	A handle for a device session.

Functions
int	QDMI_device_session_alloc (QDMI_Device_Session *session)
	Allocate a new device session.
int	QDMI_device_session_set_parameter (QDMI_Device_Session session, QDMI_Device_Session_Parameter param, size_t size, const void *value)
	Set a parameter for a device session.
int	QDMI_device_session_init (QDMI_Device_Session session)
	Initialize a device session.
void	QDMI_device_session_free (QDMI_Device_Session session)
	Free a QDMI device session.

Typedef Documentation

QDMI_Device_Session

typedef struct QDMI_Device_Session_impl_d* QDMI_Device_Session

A handle for a device session.

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

Function Documentation

QDMI_device_session_alloc()

int QDMI_device_session_alloc

(

QDMI_Device_Session *

session

)

Allocate a new device session.

This is the main entry point for a driver to establish a session with a device. The returned handle can be used throughout the device 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_device_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_device_session_set_parameter

QDMI_device_session_init

QDMI_device_session_set_parameter()

int QDMI_device_session_set_parameter	(	QDMI_Device_Session	session,
		QDMI_Device_Session_Parameter	param,
		size_t	size,
		const void *	value )

Set a parameter for a device 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_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 already initialized.

QDMI_ERROR_FATAL if an unexpected error occurred.

See also

QDMI_device_session_init

Remarks

Calling this function with value set to NULL is expected to allow checking if the device supports the specified parameter without setting a value. See the QDMI_session_set_parameter documentation for an example.

QDMI_device_session_init()

int QDMI_device_session_init

(

QDMI_Device_Session

session

)

Initialize a device session.

This function initializes the device session and prepares it for use. The session must be initialized before it can be used as part of the device query interface or the device job interface. If a device requires authentication, the required authentication information must be set using QDMI_device_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_device_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_device_session_set_parameter

QDMI_device_session_query_device_property

QDMI_device_session_query_site_property

QDMI_device_session_query_operation_property

QDMI_device_session_create_device_job

QDMI_device_session_free()

void QDMI_device_session_free

(

QDMI_Device_Session

session

)

Free a QDMI device session.

This function frees the memory allocated for the session. Using a session handle after it was freed is undefined behavior.

Parameters

[in]

session

The session to free.