QmiDevice: libqmi-glib Reference Manual

## QmiDevice QmiDevice — Generic QMI device handling routines |

## Functions

void | qmi_device_new ()
QmiDevice * | qmi_device_new_finish ()
GFile * | qmi_device_get_file ()
GFile * | qmi_device_peek_file ()
const gchar * | qmi_device_get_path ()
const gchar * | qmi_device_get_path_display ()
const gchar * | qmi_device_get_wwan_iface ()
QmiDeviceExpectedDataFormat | qmi_device_get_expected_data_format ()
gboolean | qmi_device_set_expected_data_format ()
gboolean | qmi_device_is_open ()
void | qmi_device_open ()
gboolean | qmi_device_open_finish ()
gboolean | qmi_device_close ()
void | qmi_device_allocate_client ()
QmiClient * | qmi_device_allocate_client_finish ()
void | qmi_device_release_client ()
gboolean | qmi_device_release_client_finish ()
void | qmi_device_set_instance_id ()
gboolean | qmi_device_set_instance_id_finish ()
void | qmi_device_command ()
QmiMessage * | qmi_device_command_finish ()
void | qmi_device_get_service_version_info ()
GArray * | qmi_device_get_service_version_info_finish ()
gchar * | qmi_device_open_flags_build_string_from_mask ()
gchar * | qmi_device_release_client_flags_build_string_from_mask ()
const gchar * | qmi_device_expected_data_format_get_string ()

## Properties

GFile * | device-file | Read / Write / Construct Only
gboolean | device-no-file-check | Write / Construct Only
gchar * | device-proxy-path | Write / Construct Only
gchar * | device-wwan-iface | Read

## Signals

void | indication | Run Last

## Types and Values

#define | QMI_DEVICE_FILE
#define | QMI_DEVICE_NO_FILE_CHECK
#define | QMI_DEVICE_PROXY_PATH
#define | QMI_DEVICE_WWAN_IFACE
#define | QMI_DEVICE_SIGNAL_INDICATION
struct | QmiDevice
enum | QmiDeviceOpenFlags
enum | QmiDeviceReleaseClientFlags
| QmiDeviceServiceVersionInfo
enum | QmiDeviceExpectedDataFormat

## Object Hierarchy

        GEnum
        ╰── QmiDeviceExpectedDataFormat
        GFlags
        ├── QmiDeviceOpenFlags
        ╰── QmiDeviceReleaseClientFlags
        GObject
        ╰── QmiDevice

## Implemented Interfaces

QmiDevice implements GAsyncInitable.

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

## Functions

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

#### Parameters

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

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

self | a QmiDevice. |

#### Returns

UTF-8 encoded system path of the device.

### qmi_device_get_wwan_iface ()

    const gchar *
    qmi_device_get_wwan_iface (QmiDevice *self);

Get the WWAN interface name associated with this /dev/cdc-wdm control port. This value will be loaded every time it's asked for it.

#### Parameters

self | a QmiDevice. |

#### Returns

UTF-8 encoded network interface name, or `NULL` if not available.

Since: 1.14

### qmi_device_get_expected_data_format ()

    QmiDeviceExpectedDataFormat
    qmi_device_get_expected_data_format (QmiDevice *self,
                                         GError **error);

Retrieves the data format currently expected by the kernel in the network interface.

If `QMI_DEVICE_EXPECTED_DATA_FORMAT_UNKNOWN` is returned, the user should assume that 802.3 is the expected format.

#### Parameters

self | a QmiDevice. |
error | Return location for error or `NULL`. |

#### Returns

a valid QmiDeviceExpectedDataFormat, or `QMI_DEVICE_EXPECTED_DATA_FORMAT_UNKNOWN` if `error` is set.

Since: 1.14

### qmi_device_set_expected_data_format ()

    gboolean
    qmi_device_set_expected_data_format (QmiDevice *self,
                                         QmiDeviceExpectedDataFormat format,
                                         GError **error);

Configures the data format currently expected by the kernel in the network interface.

#### Parameters

self | a QmiDevice. |
format | a known QmiDeviceExpectedDataFormat. |
error | Return location for error or `NULL`. |

#### Returns

`TRUE` if successful, or NULL if `error` is set.

Since: 1.14

### qmi_device_is_open ()

    gboolean
    qmi_device_is_open (QmiDevice *self);

Checks whether the QmiDevice is open for I/O.

#### Parameters

self | a QmiDevice. |

#### Returns

`TRUE` if `self` is open, `FALSE` otherwise.

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

#### Parameters

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

#### Parameters

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.

#### Parameters

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

#### Parameters

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

#### Parameters

self | a QmiDevice. |
res | a GAsyncResult. |
error | Return location for error or `NULL`. |

#### Returns

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

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

#### Parameters

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.

#### Parameters

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.

#### Parameters

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

#### Parameters

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.

#### Parameters

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

#### Parameters

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

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

#### Parameters

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

#### Parameters

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

### qmi_device_open_flags_build_string_from_mask ()

    gchar *
    qmi_device_open_flags_build_string_from_mask
                                   (QmiDeviceOpenFlags mask);

Builds a string containing a comma-separated list of nicknames for each QmiDeviceOpenFlags in `mask` .

#### Parameters

mask | bitmask of QmiDeviceOpenFlags values. |

#### Returns

a string with the list of nicknames, or `NULL` if none given. The returned value should be freed with `g_free()`.

[transfer full]

### qmi_device_release_client_flags_build_string_from_mask ()

    gchar *
    qmi_device_release_client_flags_build_string_from_mask
                                   (QmiDeviceReleaseClientFlags mask);

Builds a string containing a comma-separated list of nicknames for each QmiDeviceReleaseClientFlags in `mask` .

#### Parameters

mask | bitmask of QmiDeviceReleaseClientFlags values. |

#### Returns

a string with the list of nicknames, or `NULL` if none given. The returned value should be freed with `g_free()`.

[transfer full]

### qmi_device_expected_data_format_get_string ()

    const gchar *
    qmi_device_expected_data_format_get_string
                                   (QmiDeviceExpectedDataFormat val);

Gets the nickname string for the QmiDeviceExpectedDataFormat specified at `val` .

#### Parameters

val | a QmiDeviceExpectedDataFormat. |

#### Returns

a string with the nickname, or `NULL` if not found. Do not free the returned value.

[transfer none]

## Types and Values

### QMI_DEVICE_FILE

    #define QMI_DEVICE_FILE          "device-file"

### QMI_DEVICE_NO_FILE_CHECK

    #define QMI_DEVICE_NO_FILE_CHECK "device-no-file-check"

### QMI_DEVICE_PROXY_PATH

    #define QMI_DEVICE_PROXY_PATH    "device-proxy-path"

### QMI_DEVICE_WWAN_IFACE

    #define QMI_DEVICE_WWAN_IFACE    "device-wwan-iface"

### QMI_DEVICE_SIGNAL_INDICATION

    #define QMI_DEVICE_SIGNAL_INDICATION "indication"

### struct QmiDevice

    struct QmiDevice;

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

### enum QmiDeviceOpenFlags

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

#### Members

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_FLAGS_PROXY | Try to open the port through the 'qmi-proxy'. |
QMI_DEVICE_OPEN_FLAGS_MBIM | open an MBIM port with QMUX tunneling service |

### enum QmiDeviceReleaseClientFlags

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

#### Members

QMI_DEVICE_RELEASE_CLIENT_FLAGS_NONE | No flags. |
QMI_DEVICE_RELEASE_CLIENT_FLAGS_RELEASE_CID | Release the CID when releasing the client. |

### QmiDeviceServiceVersionInfo

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

Version information for a service.

#### Members

QmiService `service`; | a QmiService. |
guint16 `major_version`; | major version of the service. |
guint16 `minor_version`; | minor version of the service. |

### enum QmiDeviceExpectedDataFormat

Data format expected by the kernel.

#### Members

QMI_DEVICE_EXPECTED_DATA_FORMAT_UNKNOWN | Unknown. |
QMI_DEVICE_EXPECTED_DATA_FORMAT_802_3 | 802.3. |
QMI_DEVICE_EXPECTED_DATA_FORMAT_RAW_IP | Raw IP. |

## Property Details

### The `“device-file”` property

      “device-file”              GFile *

File to the underlying QMI device.

Flags: Read / Write / Construct Only

### The `“device-no-file-check”` property

      “device-no-file-check”     gboolean

Don't check for file existence when creating the Qmi device.

Flags: Write / Construct Only

Default value: FALSE

### The `“device-proxy-path”` property

      “device-proxy-path”        gchar *

Path of the abstract socket where the proxy is available.

Flags: Write / Construct Only

Default value: "qmi-proxy"

### The `“device-wwan-iface”` property

      “device-wwan-iface”        gchar *

Name of the WWAN network interface associated with the control port.

Flags: Read

Default value: NULL

## Signal Details

### The `“indication”` signal

    void
    user_function (QmiDevice  *qmidevice,
                   GByteArray *arg1,
                   gpointer    user_data)

Flags: Run Last