MbimDevice: libmbim-glib Reference Manual

## MbimDevice MbimDevice — Generic MBIM device handling routines |

## Functions

void | mbim_device_new ()
MbimDevice * | mbim_device_new_finish ()
GFile * | mbim_device_get_file ()
GFile * | mbim_device_peek_file ()
const gchar * | mbim_device_get_path ()
const gchar * | mbim_device_get_path_display ()
gboolean | mbim_device_is_open ()
void | mbim_device_open ()
gboolean | mbim_device_open_finish ()
void | mbim_device_open_full ()
gboolean | mbim_device_open_full_finish ()
void | mbim_device_close ()
gboolean | mbim_device_close_finish ()
gboolean | mbim_device_close_force ()
guint32 | mbim_device_get_transaction_id ()
guint32 | mbim_device_get_next_transaction_id ()
void | mbim_device_command ()
MbimMessage * | mbim_device_command_finish ()
gboolean | mbim_device_check_link_supported ()
gboolean | mbim_device_list_links ()
void | mbim_device_add_link ()
gchar * | mbim_device_add_link_finish ()
void | mbim_device_delete_link ()
gboolean | mbim_device_delete_link_finish ()
void | mbim_device_delete_all_links ()
gboolean | mbim_device_delete_all_links_finish ()

## Properties

GFile * | device-file | Read / Write / Construct Only
gboolean | device-in-session | Read / Write
guint | device-transaction-id | Read / Write

## Signals

void | device-error | Run Last
void | device-indicate-status | Run Last
void | device-removed | Run Last

## Types and Values

#define | MBIM_DEVICE_FILE
#define | MBIM_DEVICE_IN_SESSION
#define | MBIM_DEVICE_TRANSACTION_ID
#define | MBIM_DEVICE_SIGNAL_REMOVED
#define | MBIM_DEVICE_SIGNAL_INDICATE_STATUS
#define | MBIM_DEVICE_SIGNAL_ERROR
struct | MbimDevice
enum | MbimDeviceOpenFlags
#define | MBIM_DEVICE_SESSION_ID_AUTOMATIC
#define | MBIM_DEVICE_SESSION_ID_MIN
#define | MBIM_DEVICE_SESSION_ID_MAX

## Object Hierarchy

        GObject
        ╰── MbimDevice

## Implemented Interfaces

MbimDevice implements GAsyncInitable.

## Description

MbimDevice is a generic type in charge of controlling the access to the managed MBIM port.

A MbimDevice can only handle one single MBIM port.

## Functions

### mbim_device_new ()

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

Asynchronously creates a MbimDevice object to manage `file` . When the operation is finished, `callback` will be invoked. You can then call `mbim_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

### mbim_device_new_finish ()

    MbimDevice *
    mbim_device_new_finish (GAsyncResult *res,
                            GError **error);

Finishes an operation started with `mbim_device_new()`.

#### Parameters

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

#### Returns

a newly created MbimDevice, or NULL if `error` is set.

[transfer full]

Since: 1.0

### mbim_device_get_file ()

    GFile *
    mbim_device_get_file (MbimDevice *self);

Get the GFile associated with this MbimDevice.

[skip]

#### Parameters

self | a MbimDevice. |

#### Returns

a GFile that must be freed with `g_object_unref()`.

[transfer full]

Since: 1.0

### mbim_device_peek_file ()

    GFile *
    mbim_device_peek_file (MbimDevice *self);

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

[skip]

#### Parameters

self | a MbimDevice. |

#### Returns

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

[transfer none]

Since: 1.0

### mbim_device_get_path ()

    const gchar *
    mbim_device_get_path (MbimDevice *self);

Get the system path of the underlying MBIM device.

#### Parameters

self | a MbimDevice. |

#### Returns

the system path of the device.

Since: 1.0

### mbim_device_get_path_display ()

    const gchar *
    mbim_device_get_path_display (MbimDevice *self);

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

#### Parameters

self | a MbimDevice. |

#### Returns

UTF-8 encoded system path of the device.

Since: 1.0

### mbim_device_is_open ()

    gboolean
    mbim_device_is_open (MbimDevice *self);

Checks whether the MbimDevice is open for I/O.

#### Parameters

self | a MbimDevice. |

#### Returns

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

Since: 1.0

### mbim_device_open ()

    void
    mbim_device_open (MbimDevice *self,
                      guint timeout,
                      GCancellable *cancellable,
                      GAsyncReadyCallback callback,
                      gpointer user_data);

Asynchronously opens a MbimDevice for I/O.

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

#### Parameters

self | a MbimDevice. |
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

### mbim_device_open_finish ()

    gboolean
    mbim_device_open_finish (MbimDevice *self,
                             GAsyncResult *res,
                             GError **error);

Finishes an asynchronous open operation started with `mbim_device_open()`.

#### Parameters

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

#### Returns

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

Since: 1.0

### mbim_device_open_full ()

    void
    mbim_device_open_full (MbimDevice *self,
                           MbimDeviceOpenFlags flags,
                           guint timeout,
                           GCancellable *cancellable,
                           GAsyncReadyCallback callback,
                           gpointer user_data);

Asynchronously opens a MbimDevice for I/O.

This method is an extension of the generic `mbim_device_open()`, which allows launching the MbimDevice with proxy support.

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

#### Parameters

self | a MbimDevice. |
flags | a set of MbimDeviceOpenFlags. |
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.10

### mbim_device_open_full_finish ()

    gboolean
    mbim_device_open_full_finish (MbimDevice *self,
                                  GAsyncResult *res,
                                  GError **error);

Finishes an asynchronous open operation started with `mbim_device_open_full()`.

#### Parameters

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

#### Returns

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

Since: 1.10

### mbim_device_close ()

    void
    mbim_device_close (MbimDevice *self,
                       guint timeout,
                       GCancellable *cancellable,
                       GAsyncReadyCallback callback,
                       gpointer user_data);

Asynchronously closes a MbimDevice for I/O.

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

#### Parameters

self | a MbimDevice. |
timeout | maximum time, in seconds, to wait for the device to be closed. |
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

### mbim_device_close_finish ()

    gboolean
    mbim_device_close_finish (MbimDevice *self,
                              GAsyncResult *res,
                              GError **error);

Finishes an asynchronous close operation started with `mbim_device_close()`.

#### Parameters

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

#### Returns

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

Since: 1.0

### mbim_device_close_force ()

    gboolean
    mbim_device_close_force (MbimDevice *self,
                             GError **error);

Forces the MbimDevice to be closed.

#### Parameters

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

#### Returns

`TRUE` if `self` if no error happens, otherwise `FALSE` and `error` is set.

Since: 1.0

### mbim_device_get_transaction_id ()

    guint32
    mbim_device_get_transaction_id (MbimDevice *self);

Acquire the transaction ID of this MbimDevice without incrementing the internal transaction ID.

#### Parameters

self | A MbimDevice. |

#### Returns

the current transaction ID.

Since: 1.24.4

### mbim_device_get_next_transaction_id ()

    guint32
    mbim_device_get_next_transaction_id (MbimDevice *self);

Acquire the next transaction ID of this MbimDevice. The internal transaction ID gets incremented.

#### Parameters

self | A MbimDevice. |

#### Returns

the next transaction ID.

Since: 1.0

### mbim_device_command ()

    void
    mbim_device_command (MbimDevice *self,
                         MbimMessage *message,
                         guint timeout,
                         GCancellable *cancellable,
                         GAsyncReadyCallback callback,
                         gpointer user_data);

Asynchronously sends a MbimMessage to the device.

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

#### Parameters

self | a MbimDevice. |
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

### mbim_device_command_finish ()

    MbimMessage *
    mbim_device_command_finish (MbimDevice *self,
                                GAsyncResult *res,
                                GError **error);

Finishes an operation started with `mbim_device_command()`.

#### Parameters

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

#### Returns

a MbimMessage response, or NULL if `error` is set. The returned value should be freed with `mbim_message_unref()`.

Since: 1.0

### mbim_device_check_link_supported ()

    gboolean
    mbim_device_check_link_supported (MbimDevice *self,
                                      GError **error);

Checks whether link management is supported by the kernel.

#### Parameters

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

#### Returns

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

Since: 1.26

### mbim_device_list_links ()

    gboolean
    mbim_device_list_links (MbimDevice *self,
                            const gchar *base_ifname,
                            GPtrArray **out_links,
                            GError **error);

#### Parameters

self | a MbimDevice. |
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.26

### mbim_device_add_link ()

    void
    mbim_device_add_link (MbimDevice *self,
                          guint session_id,
                          const gchar *base_ifname,
                          const gchar *ifname_prefix,
                          GCancellable *cancellable,
                          GAsyncReadyCallback callback,
                          gpointer user_data);

Asynchronously creates a new virtual network device node 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 `MBIM_CORE_ERROR_UNSUPPORTED` error will be returned.

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

Depending on the kernel driver in use, 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 `mbim_device_add_link_finish()` to get the result of the operation.

#### Parameters

self | a MbimDevice. |
session_id | the session id for the link, in the [MBIM_DEVICE_SESSION_ID_MIN,MBIM_DEVICE_SESSION_ID_MAX] range, or MBIM_DEVICE_SESSION_ID_AUTOMATIC to find the first available session 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.26

### mbim_device_add_link_finish ()

    gchar *
    mbim_device_add_link_finish (MbimDevice *self,
                                 GAsyncResult *res,
                                 guint *session_id,
                                 GError **error);

Finishes an operation started with `mbim_device_add_link()`.

#### Parameters

self | a QmiDevice. |
res | a GAsyncResult. |
session_id | the session 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.26

### mbim_device_delete_link ()

    void
    mbim_device_delete_link (MbimDevice *self,
                             const gchar *ifname,
                             GCancellable *cancellable,
                             GAsyncReadyCallback callback,
                             gpointer user_data);

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

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

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

#### Parameters

self | a MbimDevice. |
ifname | the name 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.26

### mbim_device_delete_link_finish ()

    gboolean
    mbim_device_delete_link_finish (MbimDevice *self,
                                    GAsyncResult *res,
                                    GError **error);

Finishes an operation started with `mbim_device_delete_link()`.

#### Parameters

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

#### Returns

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

Since: 1.26

### mbim_device_delete_all_links ()

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

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

When the operation is finished `callback` will be called. You can then call `mbim_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 MBIM network interface link management.

#### Parameters

self | a MbimDevice. |
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.26

### mbim_device_delete_all_links_finish ()

    gboolean
    mbim_device_delete_all_links_finish (MbimDevice *self,
                                         GAsyncResult *res,
                                         GError **error);

Finishes an operation started with `mbim_device_delete_all_links()`.

#### Parameters

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

#### Returns

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

Since: 1.26

## Types and Values

### MBIM_DEVICE_FILE

    #define MBIM_DEVICE_FILE "device-file"

Symbol defining the “device-file” property.

Since: 1.0

### MBIM_DEVICE_IN_SESSION

    #define MBIM_DEVICE_IN_SESSION "device-in-session"

Symbol defining the “device-in-session” property.

Since: 1.4

### MBIM_DEVICE_TRANSACTION_ID

    #define MBIM_DEVICE_TRANSACTION_ID "device-transaction-id"

Symbol defining the “device-transaction-id” property.

Since: 1.2

### MBIM_DEVICE_SIGNAL_REMOVED

    #define MBIM_DEVICE_SIGNAL_REMOVED "device-removed"

Symbol defining the “device-removed” signal.

Since: 1.10

### MBIM_DEVICE_SIGNAL_INDICATE_STATUS

    #define MBIM_DEVICE_SIGNAL_INDICATE_STATUS "device-indicate-status"

Symbol defining the “device-indicate-status” signal.

Since: 1.0

### MBIM_DEVICE_SIGNAL_ERROR

    #define MBIM_DEVICE_SIGNAL_ERROR "device-error"

Symbol defining the “device-error” signal.

Since: 1.0

### struct MbimDevice

    struct MbimDevice;

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

Since: 1.0

### enum MbimDeviceOpenFlags

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

#### Members

MBIM_DEVICE_OPEN_FLAGS_NONE | None. |
MBIM_DEVICE_OPEN_FLAGS_PROXY | Try to open the port through the 'mbim-proxy'. |

Since: 1.10

### MBIM_DEVICE_SESSION_ID_AUTOMATIC

    #define MBIM_DEVICE_SESSION_ID_AUTOMATIC G_MAXUINT

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

Since: 1.26

### MBIM_DEVICE_SESSION_ID_MIN

    #define MBIM_DEVICE_SESSION_ID_MIN 0

Symbol defining the minimum supported session id..

Since: 1.26

### MBIM_DEVICE_SESSION_ID_MAX

    #define MBIM_DEVICE_SESSION_ID_MAX 0xFF

Symbol defining the maximum supported session id.

Since: 1.26

## Property Details

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

      “device-file”              GFile *

File to the underlying MBIM device.

Owner: MbimDevice

Flags: Read / Write / Construct Only

Since: 1.0

### The `“device-in-session”` property

      “device-in-session”        gboolean

Flag to specify if the device is within a session.

Owner: MbimDevice

Flags: Read / Write

Default value: FALSE

### The `“device-transaction-id”` property

      “device-transaction-id”    guint

Current transaction ID.

Owner: MbimDevice

Flags: Read / Write

Allowed values: >= 1

Default value: 1

Since: 1.2

## Signal Details

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

    void
    user_function (MbimDevice *self,
                   GError     *message,
                   gpointer    user_data)

The ::device-error signal is emitted when a MBIM error is received.

#### Parameters

self | the MbimDevice |
message | the MbimMessage error |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

Since: 1.0

### The `“device-indicate-status”` signal

    void
    user_function (MbimDevice  *self,
                   MbimMessage *message,
                   gpointer     user_data)

The ::device-indication-status signal is emitted when a MBIM indication is received.

#### Parameters

self | the MbimDevice |
message | the MbimMessage indication |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

Since: 1.0

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

    void
    user_function (MbimDevice *self,
                   gpointer    user_data)

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

#### Parameters

self | the MbimDevice |
message | None |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

Since: 1.10