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

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

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

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

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