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 ()
gboolean | qmi_device_is_open ()
guint | qmi_device_get_consecutive_timeouts ()
gchar * | qmi_device_open_flags_build_string_from_mask ()
void | qmi_device_open ()
gboolean | qmi_device_open_finish ()
void | qmi_device_close_async ()
gboolean | qmi_device_close_finish ()
void | qmi_device_allocate_client ()
QmiClient * | qmi_device_allocate_client_finish ()
gchar * | qmi_device_release_client_flags_build_string_from_mask ()
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_get_service_version_info ()
GArray * | qmi_device_get_service_version_info_finish ()
void | qmi_device_command_full ()
QmiMessage * | qmi_device_command_full_finish ()
QmiMessage * | (*QmiDeviceCommandAbortableBuildRequestFn) ()
gboolean | (*QmiDeviceCommandAbortableParseResponseFn) ()
void | qmi_device_command_abortable ()
QmiMessage * | qmi_device_command_abortable_finish ()
gboolean | qmi_device_list_links ()
void | qmi_device_add_link ()
gchar * | qmi_device_add_link_finish ()
gchar * | qmi_device_add_link_flags_build_string_from_mask ()
void | qmi_device_add_link_with_flags ()
gchar * | qmi_device_add_link_with_flags_finish ()
void | qmi_device_delete_link ()
gboolean | qmi_device_delete_link_finish ()
void | qmi_device_delete_all_links ()
gboolean | qmi_device_delete_all_links_finish ()
gboolean | qmi_device_check_link_supported ()
const gchar * | qmi_device_get_wwan_iface ()
const gchar * | qmi_device_expected_data_format_get_string ()
QmiDeviceExpectedDataFormat | qmi_device_get_expected_data_format ()
gboolean | qmi_device_set_expected_data_format ()
gboolean | qmi_device_check_expected_data_format_supported ()
void | qmi_device_new_from_node ()
QmiDevice * | qmi_device_new_from_node_finish ()
QrtrNode * | qmi_device_get_node ()
QrtrNode * | qmi_device_peek_node ()

## Properties

guint | device-consecutive-timeouts | Read
GFile * | device-file | Read / Write / Construct Only
gboolean | device-no-file-check | Write / Construct Only
QrtrNode * | device-node | Read / Write / Construct Only
char * | device-proxy-path | Write / Construct Only
char * | device-wwan-iface | Read

## Signals

void | device-removed | Run Last
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_CONSECUTIVE_TIMEOUTS
#define | QMI_DEVICE_SIGNAL_INDICATION
#define | QMI_DEVICE_SIGNAL_REMOVED
struct | QmiDevice
enum | QmiDeviceOpenFlags
enum | QmiDeviceReleaseClientFlags
| QmiDeviceServiceVersionInfo
#define | QMI_DEVICE_MUX_ID_AUTOMATIC
#define | QMI_DEVICE_MUX_ID_UNBOUND
#define | QMI_DEVICE_MUX_ID_MIN
#define | QMI_DEVICE_MUX_ID_MAX
enum | QmiDeviceAddLinkFlags
enum | QmiDeviceExpectedDataFormat
#define | QMI_DEVICE_NODE

## Object Hierarchy

        GEnum
        ╰── QmiDeviceExpectedDataFormat
        GFlags
        ├── QmiDeviceAddLinkFlags
        ├── 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. |

Since: 1.0

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

[transfer full]

Since: 1.0

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

[transfer full]

Since: 1.0

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

[transfer none]

Since: 1.0

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

Since: 1.0

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

Since: 1.0

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

Since: 1.0

### qmi_device_get_consecutive_timeouts ()

    guint
    qmi_device_get_consecutive_timeouts (QmiDevice *self);

Gets the number of consecutive transaction timeouts in the device.

#### Parameters

self | a QmiDevice. |

#### Returns

a guint.

Since: 1.32

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

Since: 1.0

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

Since: 1.0

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

Since: 1.0

### qmi_device_close_async ()

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

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

If this device was opened with `QMI_DEVICE_OPEN_FLAGS_MBIM` , this operation will wait for the response of the underlying MBIM close sequence.

Closing a QmiDevice multiple times will not return an error.

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

#### Parameters

self | a QmiDevice. |
timeout | maximum time, in seconds, to wait for the device to be closed. |
cancellable | a GCancellable, or `NULL`. |
callback | a GAsyncReadyCallback to call when the operation is finished. |
user_data | the data to pass to callback function. |

Since: 1.18

### qmi_device_close_finish ()

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

Finishes an operation started with `qmi_device_close_async()`.

#### Parameters

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

#### Returns

`TRUE` if successful, `FALSE` if `error` is set.

Since: 1.18

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

Since: 1.0

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

[transfer full]

Since: 1.0

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

Since: 1.0

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

Since: 1.0

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

Since: 1.0

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

Since: 1.0

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

Since: 1.0

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

Since: 1.6

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

[transfer full][element-type QmiDeviceServiceVersionInfo]

Since: 1.6

### qmi_device_command_full ()

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

Asynchronously sends a QmiMessage to the device.

The message will be processed according to the specific `message_context` given. If no `context` given, the behavior is the same as `qmi_device_command()`.

If the operation is cancelled via `cancellable` , a `QMI_PROTOCOL_ERROR_ABORTED` error will be returned always. If the QMI method may be aborted, there is no guarantee that the operation is truly aborted before the error is returned so it may really happen that the operation really succeeded and the method would still return `QMI_PROTOCOL_ERROR_ABORTED`. In order to use abortable methods and make sure the response is the correct one, use `qmi_device_command_abortable()`.

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

#### Parameters

self | a QmiDevice. |
message | the message to send. |
message_context | the context of the message. |
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. |

Since: 1.18

### qmi_device_command_full_finish ()

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

Finishes an operation started with `qmi_device_command_full()`.

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

[transfer full]

Since: 1.18

### QmiDeviceCommandAbortableBuildRequestFn ()

    QmiMessage *
    (*QmiDeviceCommandAbortableBuildRequestFn)
                                   (QmiDevice *self,
                                    QmiMessage *message,
                                    gpointer user_data,
                                    GError **error);

Callback to run when processing the command abortion. This callback should create a service-specific and client-specific abort request to be passed to the device.

#### Parameters

self | a QmiDevice. |
message | the QmiMessage to abort. |
user_data | the data provided when calling `qmi_device_command_abortable()`. |
error | Return location for error or `NULL`. |

#### Returns

the abort request as a QmiMessage or `NULL` if `error` is set.

Since: 1.24

### QmiDeviceCommandAbortableParseResponseFn ()

    gboolean
    (*QmiDeviceCommandAbortableParseResponseFn)
                                   (QmiDevice *self,
                                    QmiMessage *abort_response,
                                    gpointer user_data,
                                    GError **error);

Callback to run when processing the command abortion. This callback should parse the abort response provided by the device, and build an appropriate output.

#### Parameters

self | a QmiDevice. |
abort_response | the abort response QmiMessage. |
user_data | the data provided when calling `qmi_device_command_abortable()`. |
error | Return location for error or `NULL`. |

#### Returns

`TRUE` if the abort succeeded, `FALSE` if error is set.

Since: 1.24

### qmi_device_command_abortable ()

    void
    qmi_device_command_abortable (QmiDevice *self,
                                  QmiMessage *message,
                                  QmiMessageContext *message_context,
                                  guint timeout,
                                  QmiDeviceCommandAbortableBuildRequestFn abort_build_request_fn,
                                  QmiDeviceCommandAbortableParseResponseFn abort_parse_response_fn,
                                  gpointer abort_user_data,
                                  GDestroyNotify abort_user_data_free,
                                  GCancellable *cancellable,
                                  GAsyncReadyCallback callback,
                                  gpointer user_data);

Asynchronously sends a QmiMessage to the device.

The message will be processed according to the specific `message_context` given.

If the operation is cancelled via `cancellable` , an abort message will be sent to the device in order to really abort the ongoing operation. The `qmi_device_command_abortable()` method will not finish until either a successful reply is received from the device or otherwise the command abortion is confirmed.

If a successful command response arrives before the abort is processed by the device, the operation will succeed even if `cancellable` has been set, so that upper layers can do whatever they need to do to properly tear down the operation.

If an error command reponse arrives before the abort is processed by the device, the operation will fail with the error returned by the device.

The `QMI_PROTOCOL_ERROR_ABORTED` error will only be returned as a result of this operation if the command request was truly aborted by the device, and so, the user of the method should not assume that cancelling the `cancellable` will always make the method return a `QMI_PROTOCOL_ERROR_ABORTED` error.

The `build_request_fn` and `parse_response_fn` callbacks are required in order to build the abort requests and parse the abort responses, because these are both service and client specific.

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

#### Parameters

self | a QmiDevice. |
message | the message to send. |
message_context | the context of the message. |
timeout | maximum time, in seconds, to wait for the response. |
abort_build_request_fn | callback to build an abort request. | [scope async][closure abort_user_data]
abort_parse_response_fn | callback to parse an abort response. | [scope async][closure abort_user_data]
abort_user_data | user data to pass to `abort_build_request_fn` and `abort_parse_response_fn` . |
abort_user_data_free | a GDestroyNotify to free `abort_user_data` . | [destroy abort_user_data]
cancellable | a GCancellable, or `NULL`. |
callback | a GAsyncReadyCallback to call when the operation is finished. |
user_data | the data to pass to callback function. |

Since: 1.24

### qmi_device_command_abortable_finish ()

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

Finishes an operation started with `qmi_device_command_abortable()`.

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

[transfer full]

Since: 1.24

### qmi_device_list_links ()

    gboolean
    qmi_device_list_links (QmiDevice *self,
                           const gchar *base_ifname,
                           GPtrArray **out_links,
                           GError **error);

Synchronously lists all virtual network interfaces that have been previously created with `qmi_device_add_link()` in `base_ifname` .

#### Parameters

self | a QmiDevice. |
base_ifname | the base interface. |
out_links | a placeholder for the output GPtrArray of link names. | [out][transfer full][element-type utf8]
error | Return location for error or `NULL`. |

#### Returns

`TRUE` if successful, `FALSE` if `error` is set.

Since: 1.28

### qmi_device_add_link ()

    void
    qmi_device_add_link (QmiDevice *self,
                         guint mux_id,
                         const gchar *base_ifname,
                         const gchar *ifname_prefix,
                         GCancellable *cancellable,
                         GAsyncReadyCallback callback,
                         gpointer user_data);

Asynchronously creates a new virtual network device node with a custom prefix on top of `base_ifname` . This allows having multiple net interfaces running on top of another using multiplexing.

If the kernel driver doesn't allow this functionality, a `QMI_CORE_ERROR_UNSUPPORTED` error will be returned.

The operation may fail if the given interface name is not associated to the QMI control port managed by the QmiDevice.

Depending on the kernel driver in use and the multiplexing method, the given `ifname_prefix` may be ignored. The user should not assume that the returned link interface name is prefixed with `ifname_prefix` as it may not be the case.

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

When using the qmi_wwan kernel driver, the configured expected kernel data format will be used to select the type of multiplexing method. If the format is `QMI_DEVICE_EXPECTED_DATA_FORMAT_RAW_IP` the qmi_wwan specific add_mux/del_mux operations will be used. If the format is `QMI_DEVICE_EXPECTED_DATA_FORMAT_QMAP_PASS_THROUGH`, the generic rmnet netlink operations will be used. No multiplexing support exists when the format is `QMI_DEVICE_EXPECTED_DATA_FORMAT_802_3`.

For every other kernel driver (e.g. ipa), rmnet netlink operations are assumed to be supported.

When using the qmi_wwan driver from a kernel older than v5.12, some of the multiplexing features like using `QMI_DEVICE_MUX_ID_AUTOMATIC` may not be fully available for programs that use ephimeral QmiDevice objects for single operations.

#### Parameters

self | a QmiDevice. |
mux_id | the mux id for the link, in the [`QMI_DEVICE_MUX_ID_MIN`,`QMI_DEVICE_MUX_ID_MAX`] range, or `QMI_DEVICE_MUX_ID_AUTOMATIC` to find the first available mux id. |
base_ifname | the interface which the new link will be created on. |
ifname_prefix | the prefix suggested to be used for the name of the new link created. |
cancellable | a GCancellable, or `NULL`. |
callback | a GAsyncReadyCallback to call when the operation is finished. |
user_data | the data to pass to callback function. |

Since: 1.28

### qmi_device_add_link_finish ()

    gchar *
    qmi_device_add_link_finish (QmiDevice *self,
                                GAsyncResult *res,
                                guint *mux_id,
                                GError **error);

Finishes an operation started with `qmi_device_add_link()`.

#### Parameters

self | a QmiDevice. |
res | a GAsyncResult. |
mux_id | the mux ID for the link created. |
error | Return location for error or `NULL`. |

#### Returns

The name of the net interface created, `NULL` if `error` is set.

Since: 1.28

### qmi_device_add_link_flags_build_string_from_mask ()

    gchar *
    qmi_device_add_link_flags_build_string_from_mask
                                   (QmiDeviceAddLinkFlags mask);

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

#### Parameters

mask | bitmask of QmiDeviceAddLinkFlags 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]

Since: 1.30

### qmi_device_add_link_with_flags ()

    void
    qmi_device_add_link_with_flags (QmiDevice *self,
                                    guint mux_id,
                                    const gchar *base_ifname,
                                    const gchar *ifname_prefix,
                                    QmiDeviceAddLinkFlags flags,
                                    GCancellable *cancellable,
                                    GAsyncReadyCallback callback,
                                    gpointer user_data);

Asynchronously creates a new virtual network device in the same way as `qmi_device_add_link()` does, but passing the additional `flags` to the kernel during the operation.

Using `QMI_DEVICE_ADD_LINK_FLAGS_NONE` as `flags` is equivalent to calling `qmi_device_add_link()` directly.

If the link creation with the given set of `flags` is unsupported by the backend, the operation may fail.

None of the `flags` supported are applicable when using the multiplexing support provided by the qmi_wwan kernel driver, they are only used if using the rmnet backend for link management support.

#### Parameters

self | a QmiDevice. |
mux_id | the mux id for the link, in the [`QMI_DEVICE_MUX_ID_MIN`,`QMI_DEVICE_MUX_ID_MAX`] range, or `QMI_DEVICE_MUX_ID_AUTOMATIC` to find the first available mux id. |
base_ifname | the interface which the new link will be created on. |
ifname_prefix | the prefix suggested to be used for the name of the new link created. |
flags | bitmask of `QmiDeviceAddLinkFlags` values to pass to the kernel when creating the new link. |
cancellable | a GCancellable, or `NULL`. |
callback | a GAsyncReadyCallback to call when the operation is finished. |
user_data | the data to pass to callback function. |

Since: 1.30

### qmi_device_add_link_with_flags_finish ()

    gchar *
    qmi_device_add_link_with_flags_finish (QmiDevice *self,
                                           GAsyncResult *res,
                                           guint *mux_id,
                                           GError **error);

Finishes an operation started with `qmi_device_add_link_finish()`.

#### Parameters

self | a QmiDevice. |
res | a GAsyncResult. |
mux_id | the mux ID for the link created. |
error | Return location for error or `NULL`. |

#### Returns

The name of the net interface created, `NULL` if `error` is set.

Since: 1.30

### qmi_device_delete_link ()

    void
    qmi_device_delete_link (QmiDevice *self,
                            const gchar *ifname,
                            guint mux_id,
                            GCancellable *cancellable,
                            GAsyncReadyCallback callback,
                            gpointer user_data);

Asynchronously deletes a virtual network interface that has been previously created with `qmi_device_add_link()`.

If the kernel driver doesn't allow this functionality, a `QMI_CORE_ERROR_UNSUPPORTED` error will be returned.

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

The `QMI_DEVICE_MUX_ID_UNBOUND` value may be given as `mux_id` if the user can guarantee that the underlying kernel support doesn't require the mux id info to delete the link. When using the qmi_wwan driver from a kernel older than v5.12, a valid `mux_id` is required.

#### Parameters

self | a QmiDevice. |
ifname | the name of the link to remove. |
mux_id | the mux ID of the link to remove. |
cancellable | a GCancellable, or `NULL`. |
callback | a GAsyncReadyCallback to call when the operation is finished. |
user_data | the data to pass to callback function. |

Since: 1.28

### qmi_device_delete_link_finish ()

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

Finishes an operation started with `qmi_device_delete_link()`.

#### Parameters

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

#### Returns

`TRUE` if successful, `FALSE` if `error` is set.

Since: 1.28

### qmi_device_delete_all_links ()

    void
    qmi_device_delete_all_links (QmiDevice *self,
                                 const gchar *base_ifname,
                                 GCancellable *cancellable,
                                 GAsyncReadyCallback callback,
                                 gpointer user_data);

Asynchronously deletes all virtual network interfaces that have been previously created with `qmi_device_add_link()` in `base_ifname` .

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

There is no guarantee that other processes haven't created new links by the time this method returns. This method should be used with caution, or in setups where only one single process is expected to do QMI network interface link management.

#### Parameters

self | a QmiDevice. |
base_ifname | the interface where all links are available. |
cancellable | a GCancellable, or `NULL`. |
callback | a GAsyncReadyCallback to call when the operation is finished. |
user_data | the data to pass to callback function. |

Since: 1.28

### qmi_device_delete_all_links_finish ()

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

Finishes an operation started with `qmi_device_delete_all_links()`.

#### Parameters

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

#### Returns

`TRUE` if successful, `FALSE` if `error` is set.

Since: 1.28

### qmi_device_check_link_supported ()

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

Checks whether link management is supported by the kernel.

#### Parameters

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

#### Returns

`TRUE` if link management is supported, or `FALSE` if `error` is set.

Since: 1.28

### qmi_device_get_wwan_iface ()

    const gchar *
    qmi_device_get_wwan_iface (QmiDevice *self);

Get the WWAN interface name associated with the QMI control port. This value will be loaded every time it's asked for it.

This method is only applicable when using the qmi_wwan kernel driver.

#### Parameters

self | a QmiDevice. |

#### Returns

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

Since: 1.14

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

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, as that is what the qmi_wwan driver expected by default before kernel 4.5.

This method is only applicable when using the qmi_wwan kernel driver.

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

This method is only applicable when using the qmi_wwan kernel driver.

#### Parameters

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

#### Returns

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

Since: 1.14

### qmi_device_check_expected_data_format_supported ()

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

Checks whether the given data format is supported by the kernel. interface.

This method is only applicable when using the qmi_wwan kernel driver.

#### Parameters

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

#### Returns

`TRUE` if the data format is supported, or `FALSE` if `error` is set.

Since: 1.28

### qmi_device_new_from_node ()

    void
    qmi_device_new_from_node (QrtrNode *node,
                              GCancellable *cancellable,
                              GAsyncReadyCallback callback,
                              gpointer user_data);

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

This method is only available when the library is built with QRTR support.

#### Parameters

node | a QrtrNode. |
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. |

Since: 1.28

### qmi_device_new_from_node_finish ()

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

Finishes an operation started with `qmi_device_new_from_node()`.

This method is only available when the library is built with QRTR support.

#### Parameters

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

#### Returns

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

[transfer full]

Since: 1.28

### qmi_device_get_node ()

    QrtrNode *
    qmi_device_get_node (QmiDevice *self);

Get the QrtrNode associated with this QmiDevice.

This method is only available when the library is built with QRTR support.

#### Parameters

self | a QmiDevice. |

#### Returns

a QrtrNode that must be freed with `g_object_unref()` or `NULL` if none available.

[transfer full]

Since: 1.28

### qmi_device_peek_node ()

    QrtrNode *
    qmi_device_peek_node (QmiDevice *self);

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

This method is only available when the library is built with QRTR support.

#### Parameters

self | a QmiDevice. |

#### Returns

a QrtrNode or `NULL` if none available. Do not free the returned object, it is owned by `self` .

[transfer none]

Since: 1.28

## Types and Values

### QMI_DEVICE_FILE

    #define QMI_DEVICE_FILE "device-file"

Symbol defining the “device-file” property.

Since: 1.0

### QMI_DEVICE_NO_FILE_CHECK

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

Symbol defining the “device-no-file-check” property.

Since: 1.12

### QMI_DEVICE_PROXY_PATH

    #define QMI_DEVICE_PROXY_PATH "device-proxy-path"

Symbol defining the “device-proxy-path” property.

Since: 1.12

### QMI_DEVICE_WWAN_IFACE

    #define QMI_DEVICE_WWAN_IFACE "device-wwan-iface"

Symbol defining the “device-wwan-iface” property.

Since: 1.14

### QMI_DEVICE_CONSECUTIVE_TIMEOUTS

    #define QMI_DEVICE_CONSECUTIVE_TIMEOUTS "device-consecutive-timeouts"

Symbol defining the “device-consecutive-timeouts” property.

Since: 1.32

### QMI_DEVICE_SIGNAL_INDICATION

    #define QMI_DEVICE_SIGNAL_INDICATION "indication"

Symbol defining the “indication” signal.

Since: 1.8

### QMI_DEVICE_SIGNAL_REMOVED

    #define QMI_DEVICE_SIGNAL_REMOVED "device-removed"

Symbol defining the “device-removed” signal.

Since: 1.20

### struct QmiDevice

    struct QmiDevice;

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

Since: 1.0

### 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. Since 1.24.4 this flag no longer prevents requests from being sent to the modem if they're assumed not supported based on the version info of each message. |
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'. Since 1.8. |
QMI_DEVICE_OPEN_FLAGS_MBIM | Open an MBIM port with QMUX tunneling service. Since 1.16. |
QMI_DEVICE_OPEN_FLAGS_AUTO | Open a port either in QMI or MBIM mode, depending on device driver. Since 1.18. |
QMI_DEVICE_OPEN_FLAGS_EXPECT_INDICATIONS | Explicitly state that indications are wanted (implicit in QMI mode, optional when in MBIM mode). |

Since: 1.0

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

Since: 1.0

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

Since: 1.6

### QMI_DEVICE_MUX_ID_AUTOMATIC

    #define QMI_DEVICE_MUX_ID_AUTOMATIC G_MAXUINT

Symbol defining a mux id that will be automatically allocated during runtime when creating net links.

Since: 1.28

### QMI_DEVICE_MUX_ID_UNBOUND

    #define QMI_DEVICE_MUX_ID_UNBOUND 0

Symbol defining the mux id for an unbound interface. This value is also used to indicate an invalid mux id.

Since: 1.28

### QMI_DEVICE_MUX_ID_MIN

    #define QMI_DEVICE_MUX_ID_MIN 1

Symbol defining the minimum supported mux id.

Since: 1.28

### QMI_DEVICE_MUX_ID_MAX

    #define QMI_DEVICE_MUX_ID_MAX 0xFE

Symbol defining the maximum supported mux id.

Since: 1.28

### enum QmiDeviceAddLinkFlags

Flags specifying the behavior of the new link.

#### Members

QMI_DEVICE_ADD_LINK_FLAGS_NONE | none. |
QMI_DEVICE_ADD_LINK_FLAGS_INGRESS_MAP_CKSUMV4 | checksum offload (v4) is enabled in ingress path. |
QMI_DEVICE_ADD_LINK_FLAGS_EGRESS_MAP_CKSUMV4 | checksum offload (v4) is enabled in egress path. |
QMI_DEVICE_ADD_LINK_FLAGS_INGRESS_MAP_CKSUMV5 | checksum offload (v5) is enabled in ingress path. Since 1.32. |
QMI_DEVICE_ADD_LINK_FLAGS_EGRESS_MAP_CKSUMV5 | checksum offload (v5) is enabled in egress path. Since 1.32. |

Since: 1.30

### enum QmiDeviceExpectedDataFormat

Data format expected by the kernel.

This type is only applicable when using the qmi_wwan kernel driver.

#### 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. |
QMI_DEVICE_EXPECTED_DATA_FORMAT_QMAP_PASS_THROUGH | QMAP pass-through. Since 1.28. |

Since: 1.14

### QMI_DEVICE_NODE

    #define QMI_DEVICE_NODE "device-node"

Symbol defining the “device-node” property.

This property is only available when the library is built with QRTR support.

Since: 1.28

## Property Details

### The `“device-consecutive-timeouts”` property

      “device-consecutive-timeouts” guint

Number of consecutive timeouts detected in requests sent to the device.

Owner: QmiDevice

Flags: Read

Default value: 0

Since: 1.32

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

      “device-file”              GFile *

File to the underlying QMI device.

Owner: QmiDevice

Flags: Read / Write / Construct Only

Since: 1.0

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

      “device-no-file-check”     gboolean

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

Owner: QmiDevice

Flags: Write / Construct Only

Default value: FALSE

Since: 1.12

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

      “device-node”              QrtrNode *

Remote node on the QRTR bus.

Owner: QmiDevice

Flags: Read / Write / Construct Only

Since: 1.24

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

      “device-proxy-path”        char *

Path of the abstract socket where the proxy is available.

Owner: QmiDevice

Flags: Write / Construct Only

Default value: "qmi-proxy"

Since: 1.12

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

      “device-wwan-iface”        char *

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

Owner: QmiDevice

Flags: Read

Default value: NULL

Since: 1.14

## Signal Details

### The `“device-removed”` signal

    void
    user_function (QmiDevice *object,
                   gpointer   user_data)

The ::device-removed signal is emitted when an unexpected port hang-up is received.

#### Parameters

object | A QmiDevice. |
output | none |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

Since: 1.20

### The `“indication”` signal

    void
    user_function (QmiDevice  *object,
                   GByteArray *output,
                   gpointer    user_data)

The ::indication signal gets emitted when a QMI indication is received.

#### Parameters

object | A QmiDevice. |
output | A QmiMessage. |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

Since: 1.8