QmiDevice

QmiDevice — Generic QMI device handling routines

Synopsis

#define             QMI_DEVICE_FILE
struct              QmiDevice;
void                qmi_device_new                      (GFile *file,
                                                         GCancellable *cancellable,
                                                         GAsyncReadyCallback callback,
                                                         gpointer user_data);
QmiDevice *         qmi_device_new_finish               (GAsyncResult *res,
                                                         GError **error);
GFile *             qmi_device_get_file                 (QmiDevice *self);
GFile *             qmi_device_peek_file                (QmiDevice *self);
const gchar *       qmi_device_get_path                 (QmiDevice *self);
const gchar *       qmi_device_get_path_display         (QmiDevice *self);
gboolean            qmi_device_is_open                  (QmiDevice *self);
enum                QmiDeviceOpenFlags;
void                qmi_device_open                     (QmiDevice *self,
                                                         QmiDeviceOpenFlags flags,
                                                         guint timeout,
                                                         GCancellable *cancellable,
                                                         GAsyncReadyCallback callback,
                                                         gpointer user_data);
gboolean            qmi_device_open_finish              (QmiDevice *self,
                                                         GAsyncResult *res,
                                                         GError **error);
gboolean            qmi_device_close                    (QmiDevice *self,
                                                         GError **error);
void                qmi_device_allocate_client          (QmiDevice *self,
                                                         QmiService service,
                                                         guint8 cid,
                                                         guint timeout,
                                                         GCancellable *cancellable,
                                                         GAsyncReadyCallback callback,
                                                         gpointer user_data);
QmiClient *         qmi_device_allocate_client_finish   (QmiDevice *self,
                                                         GAsyncResult *res,
                                                         GError **error);
enum                QmiDeviceReleaseClientFlags;
void                qmi_device_release_client           (QmiDevice *self,
                                                         QmiClient *client,
                                                         QmiDeviceReleaseClientFlags flags,
                                                         guint timeout,
                                                         GCancellable *cancellable,
                                                         GAsyncReadyCallback callback,
                                                         gpointer user_data);
gboolean            qmi_device_release_client_finish    (QmiDevice *self,
                                                         GAsyncResult *res,
                                                         GError **error);
void                qmi_device_set_instance_id          (QmiDevice *self,
                                                         guint8 instance_id,
                                                         guint timeout,
                                                         GCancellable *cancellable,
                                                         GAsyncReadyCallback callback,
                                                         gpointer user_data);
gboolean            qmi_device_set_instance_id_finish   (QmiDevice *self,
                                                         GAsyncResult *res,
                                                         guint16 *link_id,
                                                         GError **error);
void                qmi_device_command                  (QmiDevice *self,
                                                         QmiMessage *message,
                                                         guint timeout,
                                                         GCancellable *cancellable,
                                                         GAsyncReadyCallback callback,
                                                         gpointer user_data);
QmiMessage *        qmi_device_command_finish           (QmiDevice *self,
                                                         GAsyncResult *res,
                                                         GError **error);
                    QmiDeviceServiceVersionInfo;
void                qmi_device_get_service_version_info (QmiDevice *self,
                                                         guint timeout,
                                                         GCancellable *cancellable,
                                                         GAsyncReadyCallback callback,
                                                         gpointer user_data);
GArray *            qmi_device_get_service_version_info_finish
                                                        (QmiDevice *self,
                                                         GAsyncResult *res,
                                                         GError **error);

Object Hierarchy

  GObject
   +----QmiDevice

Implemented Interfaces

QmiDevice implements GAsyncInitable.

Properties

  "device-file"              GFile*                : Read / Write / Construct Only

Description

QmiDevice is a generic type in charge of controlling the access of multiple QmiClient objects to the managed QMI port.

A QmiDevice can only handle one single QMI port.

Details

QMI_DEVICE_FILE

#define QMI_DEVICE_FILE "device-file"


struct QmiDevice

struct QmiDevice;

The QmiDevice structure contains private data and should only be accessed using the provided API.


qmi_device_new ()

void                qmi_device_new                      (GFile *file,
                                                         GCancellable *cancellable,
                                                         GAsyncReadyCallback callback,
                                                         gpointer user_data);

Asynchronously creates a QmiDevice object to manage file. When the operation is finished, callback will be invoked. You can then call qmi_device_new_finish() to get the result of the operation.

file :

a GFile.

cancellable :

optional GCancellable object, NULL to ignore.

callback :

a GAsyncReadyCallback to call when the initialization is finished.

user_data :

the data to pass to callback function.

qmi_device_new_finish ()

QmiDevice *         qmi_device_new_finish               (GAsyncResult *res,
                                                         GError **error);

Finishes an operation started with qmi_device_new().

res :

a GAsyncResult.

error :

Return location for error or NULL.

Returns :

A newly created QmiDevice, or NULL if error is set.

qmi_device_get_file ()

GFile *             qmi_device_get_file                 (QmiDevice *self);

Get the GFile associated with this QmiDevice.

self :

a QmiDevice.

Returns :

a GFile that must be freed with g_object_unref().

qmi_device_peek_file ()

GFile *             qmi_device_peek_file                (QmiDevice *self);

Get the GFile associated with this QmiDevice, without increasing the reference count on the returned object.

self :

a QmiDevice.

Returns :

a GFile. Do not free the returned object, it is owned by self.

qmi_device_get_path ()

const gchar *       qmi_device_get_path                 (QmiDevice *self);

Get the system path of the underlying QMI device.

self :

a QmiDevice.

Returns :

the system path of the device.

qmi_device_get_path_display ()

const gchar *       qmi_device_get_path_display         (QmiDevice *self);

Get the system path of the underlying QMI device in UTF-8.

self :

a QmiDevice.

Returns :

UTF-8 encoded system path of the device.

qmi_device_is_open ()

gboolean            qmi_device_is_open                  (QmiDevice *self);

Checks whether the QmiDevice is open for I/O.

self :

a QmiDevice.

Returns :

TRUE if self is open, FALSE otherwise.

enum QmiDeviceOpenFlags

typedef enum {
    QMI_DEVICE_OPEN_FLAGS_NONE              = 0,
    QMI_DEVICE_OPEN_FLAGS_VERSION_INFO      = 1 << 0,
    QMI_DEVICE_OPEN_FLAGS_SYNC              = 1 << 1,
    QMI_DEVICE_OPEN_FLAGS_NET_802_3         = 1 << 2,
    QMI_DEVICE_OPEN_FLAGS_NET_RAW_IP        = 1 << 3,
    QMI_DEVICE_OPEN_FLAGS_NET_QOS_HEADER    = 1 << 4,
    QMI_DEVICE_OPEN_FLAGS_NET_NO_QOS_HEADER = 1 << 5
} QmiDeviceOpenFlags;

Flags to specify which actions to be performed when the device is open.

QMI_DEVICE_OPEN_FLAGS_NONE

No flags.

QMI_DEVICE_OPEN_FLAGS_VERSION_INFO

Run version info check when opening.

QMI_DEVICE_OPEN_FLAGS_SYNC

Synchronize with endpoint once the device is open. Will release any previously allocated client ID.

QMI_DEVICE_OPEN_FLAGS_NET_802_3

set network port to "802.3" mode; mutually exclusive with QMI_DEVICE_OPEN_FLAGS_NET_RAW_IP

QMI_DEVICE_OPEN_FLAGS_NET_RAW_IP

set network port to "raw IP" mode; mutally exclusive with QMI_DEVICE_OPEN_FLAGS_NET_802_3

QMI_DEVICE_OPEN_FLAGS_NET_QOS_HEADER

set network port to transmit/receive QoS headers; mutually exclusive with QMI_DEVICE_OPEN_FLAGS_NET_NO_QOS_HEADER

QMI_DEVICE_OPEN_FLAGS_NET_NO_QOS_HEADER

set network port to not transmit/receive QoS headers; mutually exclusive with QMI_DEVICE_OPEN_FLAGS_NET_QOS_HEADER

qmi_device_open ()

void                qmi_device_open                     (QmiDevice *self,
                                                         QmiDeviceOpenFlags flags,
                                                         guint timeout,
                                                         GCancellable *cancellable,
                                                         GAsyncReadyCallback callback,
                                                         gpointer user_data);

Asynchronously opens a QmiDevice for I/O.

When the operation is finished callback will be called. You can then call qmi_device_open_finish() to get the result of the operation.

self :

a QmiDevice.

flags :

mask of QmiDeviceOpenFlags specifying how the device should be opened.

timeout :

maximum time, in seconds, to wait for the device to be opened.

cancellable :

optional GCancellable object, NULL to ignore.

callback :

a GAsyncReadyCallback to call when the operation is finished.

user_data :

the data to pass to callback function.

qmi_device_open_finish ()

gboolean            qmi_device_open_finish              (QmiDevice *self,
                                                         GAsyncResult *res,
                                                         GError **error);

Finishes an asynchronous open operation started with qmi_device_open().

self :

a QmiDevice.

res :

a GAsyncResult.

error :

Return location for error or NULL.

Returns :

TRUE if successful, FALSE if error is set.

qmi_device_close ()

gboolean            qmi_device_close                    (QmiDevice *self,
                                                         GError **error);

Synchronously closes a QmiDevice, preventing any further I/O.

Closing a QmiDevice multiple times will not return an error.

self :

a QmiDevice

error :

Return location for error or NULL.

Returns :

TRUE if successful, FALSE if error is set.

qmi_device_allocate_client ()

void                qmi_device_allocate_client          (QmiDevice *self,
                                                         QmiService service,
                                                         guint8 cid,
                                                         guint timeout,
                                                         GCancellable *cancellable,
                                                         GAsyncReadyCallback callback,
                                                         gpointer user_data);

Asynchronously allocates a new QmiClient in self.

If QMI_CID_NONE is given in cid, a new client ID will be allocated; otherwise a client with the given cid will be generated.

When the operation is finished callback will be called. You can then call qmi_device_allocate_client_finish() to get the result of the operation.

Note: Clients for the QMI_SERVICE_CTL cannot be created with this method; instead get/peek the implicit one from self.

self :

a QmiDevice.

service :

a valid QmiService.

cid :

a valid client ID, or QMI_CID_NONE.

timeout :

maximum time to wait.

cancellable :

optional GCancellable object, NULL to ignore.

callback :

a GAsyncReadyCallback to call when the operation is finished.

user_data :

the data to pass to callback function.

qmi_device_allocate_client_finish ()

QmiClient *         qmi_device_allocate_client_finish   (QmiDevice *self,
                                                         GAsyncResult *res,
                                                         GError **error);

Finishes an operation started with qmi_device_allocate_client().

self :

a QmiDevice.

res :

a GAsyncResult.

error :

Return location for error or NULL.

Returns :

a newly allocated QmiClient, or NULL if error is set.

enum QmiDeviceReleaseClientFlags

typedef enum {
    QMI_DEVICE_RELEASE_CLIENT_FLAGS_NONE        = 0,
    QMI_DEVICE_RELEASE_CLIENT_FLAGS_RELEASE_CID = 1 << 0
} QmiDeviceReleaseClientFlags;

Flags to specify which actions to be performed when releasing the client.

QMI_DEVICE_RELEASE_CLIENT_FLAGS_NONE

No flags.

QMI_DEVICE_RELEASE_CLIENT_FLAGS_RELEASE_CID

Release the CID when releasing the client.

qmi_device_release_client ()

void                qmi_device_release_client           (QmiDevice *self,
                                                         QmiClient *client,
                                                         QmiDeviceReleaseClientFlags flags,
                                                         guint timeout,
                                                         GCancellable *cancellable,
                                                         GAsyncReadyCallback callback,
                                                         gpointer user_data);

Asynchronously releases the QmiClient from the QmiDevice.

Once the QmiClient has been released, it cannot be used any more to perform operations.

When the operation is finished callback will be called. You can then call qmi_device_release_client_finish() to get the result of the operation.

self :

a QmiDevice.

client :

the QmiClient to release.

flags :

mask of QmiDeviceReleaseClientFlags specifying how the client should be released.

timeout :

maximum time to wait.

cancellable :

optional GCancellable object, NULL to ignore.

callback :

a GAsyncReadyCallback to call when the operation is finished.

user_data :

the data to pass to callback function.

qmi_device_release_client_finish ()

gboolean            qmi_device_release_client_finish    (QmiDevice *self,
                                                         GAsyncResult *res,
                                                         GError **error);

Finishes an operation started with qmi_device_release_client().

Note that even if the release operation returns an error, the client should anyway be considered released, and shouldn't be used afterwards.

self :

a QmiDevice.

res :

a GAsyncResult.

error :

Return location for error or NULL.

Returns :

TRUE if successful, or NULL if error is set.

qmi_device_set_instance_id ()

void                qmi_device_set_instance_id          (QmiDevice *self,
                                                         guint8 instance_id,
                                                         guint timeout,
                                                         GCancellable *cancellable,
                                                         GAsyncReadyCallback callback,
                                                         gpointer user_data);

Sets the instance ID of the QmiDevice.

When the operation is finished callback will be called. You can then call qmi_device_set_instance_id_finish() to get the result of the operation.

self :

a QmiDevice.

instance_id :

the instance ID.

timeout :

maximum time to wait.

cancellable :

optional GCancellable object, NULL to ignore.

callback :

a GAsyncReadyCallback to call when the operation is finished.

user_data :

the data to pass to callback function.

qmi_device_set_instance_id_finish ()

gboolean            qmi_device_set_instance_id_finish   (QmiDevice *self,
                                                         GAsyncResult *res,
                                                         guint16 *link_id,
                                                         GError **error);

Finishes an operation started with qmi_device_set_instance_id().

self :

a QmiDevice.

res :

a GAsyncResult.

link_id :

a placeholder for the output guint16, or NULL if not required.

error :

Return location for error or NULL.

Returns :

TRUE if successful, FALSE if error is set.

qmi_device_command ()

void                qmi_device_command                  (QmiDevice *self,
                                                         QmiMessage *message,
                                                         guint timeout,
                                                         GCancellable *cancellable,
                                                         GAsyncReadyCallback callback,
                                                         gpointer user_data);

Asynchronously sends a QmiMessage to the device.

When the operation is finished callback will be called. You can then call qmi_device_command_finish() to get the result of the operation.

self :

a QmiDevice.

message :

the message to send.

timeout :

maximum time, in seconds, to wait for the response.

cancellable :

a GCancellable, or NULL.

callback :

a GAsyncReadyCallback to call when the operation is finished.

user_data :

the data to pass to callback function.

qmi_device_command_finish ()

QmiMessage *        qmi_device_command_finish           (QmiDevice *self,
                                                         GAsyncResult *res,
                                                         GError **error);

Finishes an operation started with qmi_device_command().

self :

a QmiDevice.

res :

a GAsyncResult.

error :

Return location for error or NULL.

Returns :

a QmiMessage response, or NULL if error is set. The returned value should be freed with qmi_message_unref().

QmiDeviceServiceVersionInfo

typedef struct {
    QmiService service;
    guint16 major_version;
    guint16 minor_version;
} QmiDeviceServiceVersionInfo;

Version information for a service.

QmiService service;

a QmiService.

guint16 major_version;

major version of the service.

guint16 minor_version;

minor version of the service.

qmi_device_get_service_version_info ()

void                qmi_device_get_service_version_info (QmiDevice *self,
                                                         guint timeout,
                                                         GCancellable *cancellable,
                                                         GAsyncReadyCallback callback,
                                                         gpointer user_data);

Asynchronously requests the service version information of the device.

When the operation is finished, callback will be invoked in the thread-default main loop of the thread you are calling this method from.

You can then call qmi_device_get_service_version_info_finish() to get the result of the operation.

self :

a QmiDevice.

timeout :

maximum time to wait for the method to complete, in seconds.

cancellable :

a GCancellable or NULL.

callback :

a GAsyncReadyCallback to call when the request is satisfied.

user_data :

user data to pass to callback.

qmi_device_get_service_version_info_finish ()

GArray *            qmi_device_get_service_version_info_finish
                                                        (QmiDevice *self,
                                                         GAsyncResult *res,
                                                         GError **error);

Finishes an operation started with qmi_device_get_service_version_info().

self :

a QmiDevice.

res :

a GAsyncResult.

error :

Return location for error or NULL.

Returns :

a GArray of QmiDeviceServiceVersionInfo elements, or NULL if error is set. The returned value should be freed with g_array_unref().

Property Details

The "device-file" property

  "device-file"              GFile*                : Read / Write / Construct Only

File to the underlying QMI device.