QmiDevice

QmiDevice — Generic QMI device handling routines

Functions

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

Types and Values

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.

 

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.

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

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 .

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

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.

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_command ()

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

qmi_device_command has been deprecated since version 1.18 and should not be used in newly-written code.

Use qmi_device_command_full() instead.

Asynchronously sends a generic QmiMessage to the device with no context.

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.

 

Since: 1.0


qmi_device_command_finish ()

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

qmi_device_command_finish has been deprecated since version 1.18. and should not be used in newly-written code.

Use qmi_device_command_full_finish() instead.

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

Since: 1.0


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.

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.

If no context given, the behavior is the same as qmi_device_command().

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

Since: 1.18


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

Since: 1.6


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_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_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

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_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"

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.

 

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


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.

 

Since: 1.14

Property Details

The “device-file” property

  “device-file”              GFile *

File to the underlying QMI device.

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.

Flags: Write / Construct Only

Default value: FALSE

Since: 1.12


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"

Since: 1.12


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

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