MbimDevice

MbimDevice — Generic MBIM device handling routines

Synopsis

#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;
void                mbim_device_new                     (GFile *file,
                                                         GCancellable *cancellable,
                                                         GAsyncReadyCallback callback,
                                                         gpointer user_data);
MbimDevice *        mbim_device_new_finish              (GAsyncResult *res,
                                                         GError **error);
GFile *             mbim_device_get_file                (MbimDevice *self);
GFile *             mbim_device_peek_file               (MbimDevice *self);
const gchar *       mbim_device_get_path                (MbimDevice *self);
const gchar *       mbim_device_get_path_display        (MbimDevice *self);
gboolean            mbim_device_is_open                 (MbimDevice *self);
void                mbim_device_open                    (MbimDevice *self,
                                                         guint timeout,
                                                         GCancellable *cancellable,
                                                         GAsyncReadyCallback callback,
                                                         gpointer user_data);
gboolean            mbim_device_open_finish             (MbimDevice *self,
                                                         GAsyncResult *res,
                                                         GError **error);
enum                MbimDeviceOpenFlags;
void                mbim_device_open_full               (MbimDevice *self,
                                                         MbimDeviceOpenFlags flags,
                                                         guint timeout,
                                                         GCancellable *cancellable,
                                                         GAsyncReadyCallback callback,
                                                         gpointer user_data);
gboolean            mbim_device_open_full_finish        (MbimDevice *self,
                                                         GAsyncResult *res,
                                                         GError **error);
void                mbim_device_close                   (MbimDevice *self,
                                                         guint timeout,
                                                         GCancellable *cancellable,
                                                         GAsyncReadyCallback callback,
                                                         gpointer user_data);
gboolean            mbim_device_close_finish            (MbimDevice *self,
                                                         GAsyncResult *res,
                                                         GError **error);
gboolean            mbim_device_close_force             (MbimDevice *self,
                                                         GError **error);
guint32             mbim_device_get_next_transaction_id (MbimDevice *self);
void                mbim_device_command                 (MbimDevice *self,
                                                         MbimMessage *message,
                                                         guint timeout,
                                                         GCancellable *cancellable,
                                                         GAsyncReadyCallback callback,
                                                         gpointer user_data);
MbimMessage *       mbim_device_command_finish          (MbimDevice *self,
                                                         GAsyncResult *res,
                                                         GError **error);

Object Hierarchy

  GObject
   +----MbimDevice

Implemented Interfaces

MbimDevice implements GAsyncInitable.

Properties

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

Signals

  "device-error"                                   : Run Last
  "device-indicate-status"                         : Run Last
  "device-removed"                                 : Run Last

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.

Details

MBIM_DEVICE_FILE

#define MBIM_DEVICE_FILE           "device-file"


MBIM_DEVICE_IN_SESSION

#define MBIM_DEVICE_IN_SESSION     "device-in-session"


MBIM_DEVICE_TRANSACTION_ID

#define MBIM_DEVICE_TRANSACTION_ID "device-transaction-id"


MBIM_DEVICE_SIGNAL_REMOVED

#define MBIM_DEVICE_SIGNAL_REMOVED         "device-removed"


MBIM_DEVICE_SIGNAL_INDICATE_STATUS

#define MBIM_DEVICE_SIGNAL_INDICATE_STATUS "device-indicate-status"


MBIM_DEVICE_SIGNAL_ERROR

#define MBIM_DEVICE_SIGNAL_ERROR           "device-error"


struct MbimDevice

struct MbimDevice;

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


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.

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.

mbim_device_new_finish ()

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

Finishes an operation started with mbim_device_new().

res :

a GAsyncResult.

error :

Return location for error or NULL.

Returns :

A newly created MbimDevice, or NULL if error is set.

mbim_device_get_file ()

GFile *             mbim_device_get_file                (MbimDevice *self);

Get the GFile associated with this MbimDevice.

self :

a MbimDevice.

Returns :

a GFile that must be freed with g_object_unref().

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.

self :

a MbimDevice.

Returns :

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

mbim_device_get_path ()

const gchar *       mbim_device_get_path                (MbimDevice *self);

Get the system path of the underlying MBIM device.

self :

a MbimDevice.

Returns :

the system path of the device.

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.

self :

a MbimDevice.

Returns :

UTF-8 encoded system path of the device.

mbim_device_is_open ()

gboolean            mbim_device_is_open                 (MbimDevice *self);

Checks whether the MbimDevice is open for I/O.

self :

a MbimDevice.

Returns :

TRUE if self is open, FALSE otherwise.

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.

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.

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

self :

a MbimDevice.

res :

a GAsyncResult.

error :

Return location for error or NULL.

Returns :

TRUE if successful, FALSE if error is set.

enum MbimDeviceOpenFlags

typedef enum {
    MBIM_DEVICE_OPEN_FLAGS_NONE  = 0,
    MBIM_DEVICE_OPEN_FLAGS_PROXY = 1 << 0
} MbimDeviceOpenFlags;

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

MBIM_DEVICE_OPEN_FLAGS_NONE

None.

MBIM_DEVICE_OPEN_FLAGS_PROXY

Try to open the port through the 'mbim-proxy'.

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.

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.

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

self :

a MbimDevice.

res :

a GAsyncResult.

error :

Return location for error or NULL.

Returns :

TRUE if successful, FALSE if error is set.

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.

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.

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

self :

a MbimDevice.

res :

a GAsyncResult.

error :

Return location for error or NULL.

Returns :

TRUE if successful, FALSE if error is set.

mbim_device_close_force ()

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

Forces the MbimDevice to be closed.

self :

a MbimDevice.

error :

Return location for error or NULL.

Returns :

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

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.

self :

A MbimDevice.

Returns :

the next transaction ID.

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.

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.

mbim_device_command_finish ()

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

Finishes an operation started with mbim_device_command().

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

Property Details

The "device-file" property

  "device-file"              GFile*                : Read / Write / Construct Only

File to the underlying MBIM device.


The "device-in-session" property

  "device-in-session"        gboolean              : Read / Write

Flag to specify if the device is within a session.

Default value: FALSE


The "device-transaction-id" property

  "device-transaction-id"    guint                 : Read / Write

Current transaction ID.

Allowed values: >= 1

Default value: 1

Signal Details

The "device-error" signal

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

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

self :

the MbimDevice

message :

the MbimMessage error

user_data :

user data set when the signal handler was connected.

The "device-indicate-status" signal

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

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

self :

the MbimDevice

message :

the MbimMessage indication

user_data :

user data set when the signal handler was connected.

The "device-removed" signal

void                user_function                      (MbimDevice *self,
                                                        gpointer    user_data)      : Run Last

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

self :

the MbimDevice

message :

None

user_data :

user data set when the signal handler was connected.