QmiDevice

## 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);

## 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()`.

## Property Details

### The `"device-file"` property

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

File to the underlying QMI device.