MbimMessage: libmbim-glib Reference Manual

## MbimMessage MbimMessage — Generic MBIM message handling routines |

## Functions

MbimMessage * | mbim_message_new ()
MbimMessage * | mbim_message_dup ()
MbimMessage * | mbim_message_ref ()
void | mbim_message_unref ()
gboolean | mbim_message_validate ()
gchar * | mbim_message_get_printable ()
gchar * | mbim_message_get_printable_full ()
const guint8 * | mbim_message_get_raw ()
MbimMessageType | mbim_message_get_message_type ()
guint32 | mbim_message_get_message_length ()
guint32 | mbim_message_get_transaction_id ()
void | mbim_message_set_transaction_id ()
const gchar * | mbim_message_type_get_string ()
MbimMessage * | mbim_message_open_new ()
guint32 | mbim_message_open_get_max_control_transfer ()
MbimStatusError | mbim_message_open_done_get_status_code ()
gboolean | mbim_message_open_done_get_result ()
MbimMessage * | mbim_message_close_new ()
MbimStatusError | mbim_message_close_done_get_status_code ()
gboolean | mbim_message_close_done_get_result ()
MbimMessage * | mbim_message_error_new ()
MbimMessage * | mbim_message_function_error_new ()
MbimProtocolError | mbim_message_error_get_error_status_code ()
GError * | mbim_message_error_get_error ()
MbimMessage * | mbim_message_command_new ()
void | mbim_message_command_append ()
MbimService | mbim_message_command_get_service ()
const MbimUuid * | mbim_message_command_get_service_id ()
guint32 | mbim_message_command_get_cid ()
MbimMessageCommandType | mbim_message_command_get_command_type ()
const guint8 * | mbim_message_command_get_raw_information_buffer ()
const gchar * | mbim_message_command_type_get_string ()
MbimService | mbim_message_command_done_get_service ()
const MbimUuid * | mbim_message_command_done_get_service_id ()
guint32 | mbim_message_command_done_get_cid ()
MbimStatusError | mbim_message_command_done_get_status_code ()
gboolean | mbim_message_command_done_get_result ()
const guint8 * | mbim_message_command_done_get_raw_information_buffer ()
MbimService | mbim_message_indicate_status_get_service ()
const MbimUuid * | mbim_message_indicate_status_get_service_id ()
guint32 | mbim_message_indicate_status_get_cid ()
const guint8 * | mbim_message_indicate_status_get_raw_information_buffer ()
gboolean | mbim_message_response_get_result ()

## Types and Values

| MbimMessage
enum | MbimMessageType
struct | MbimIPv4
struct | MbimIPv6
enum | MbimMessageCommandType

## Object Hierarchy

        GBoxed
        ╰── MbimMessage
        GEnum
        ├── MbimMessageCommandType
        ╰── MbimMessageType

## Description

MbimMessage is a generic type representing a MBIM message of any kind (request, response, indication).

## Functions

### mbim_message_new ()

    MbimMessage *
    mbim_message_new (const guint8 *data,
                      guint32 data_length);

Create a MbimMessage with the given contents.

#### Parameters

data | contents of the message. |
data_length | length of the message. |

#### Returns

a newly created MbimMessage, which should be freed with `mbim_message_unref()`.

[transfer full]

Since: 1.0

### mbim_message_dup ()

    MbimMessage *
    mbim_message_dup (const MbimMessage *self);

Create a MbimMessage with the same contents as `self` .

#### Parameters

self | a MbimMessage to duplicate. |

#### Returns

a newly created MbimMessage, which should be freed with `mbim_message_unref()`.

[transfer full]

Since: 1.0

### mbim_message_ref ()

    MbimMessage *
    mbim_message_ref (MbimMessage *self);

Atomically increments the reference count of `self` by one.

#### Parameters

self | a MbimMessage. |

#### Returns

the new reference to `self` .

[transfer full]

Since: 1.0

### mbim_message_unref ()

    void
    mbim_message_unref (MbimMessage *self);

Atomically decrements the reference count of `self` by one. If the reference count drops to 0, `self` is completely disposed.

#### Parameters

self | a MbimMessage. |

Since: 1.0

### mbim_message_validate ()

    gboolean
    mbim_message_validate (const MbimMessage *self,
                           GError **error);

Validates the contents of the headers in the MBIM message.

This operation may be used to ensure that the message is full and of a valid type.

This operation does not validate that the specific contents of a given message type are available, that is done by the methods retrieving those specific contents.

#### Parameters

self | a MbimMessage. |
error | return location for error or `NULL`. |

#### Returns

`TRUE` if the message is valid, `FALSE` if `error` is set.

Since: 1.28

### mbim_message_get_printable ()

    gchar *
    mbim_message_get_printable (const MbimMessage *self,
                                const gchar *line_prefix,
                                gboolean headers_only);

Gets a printable string with the contents of the whole MBIM message.

This method will not fail if the parsing of the message contents fails, a fallback text with the error will be included in the generated printable information instead.

#### Parameters

self | a MbimMessage. |
line_prefix | prefix string to use in each new generated line. |
headers_only | `TRUE` if only basic headers should be printed. |

#### Returns

a newly allocated string, which should be freed with `g_free()`.

Since: 1.0

### mbim_message_get_printable_full ()

    gchar *
    mbim_message_get_printable_full (const MbimMessage *self,
                                     guint8 mbimex_version_major,
                                     guint8 mbimex_version_minor,
                                     const gchar *line_prefix,
                                     gboolean headers_only,
                                     GError **error);

Gets a printable string with the contents of the whole MBIM message.

Unlike `mbim_message_get_printable()`, this method allows specifying the MBIMEx version agreed between host and device, so that the correct processing and parsing is done on messages in the newer MBIMEx versions.

If `mbimex_version_major` < 2, this method behaves exactly as `mbim_message_get_printable()`.

If the specified `mbimex_version_major` is unsupported, an error will be returned.

This method will not fail if the parsing of the message contents fails, a fallback text with the error will be included in the generated printable information instead.

#### Parameters

self | a MbimMessage. |
mbimex_version_major | major version of the agreed MBIMEx support. |
mbimex_version_minor | minor version of the agreed MBIMEx support. |
line_prefix | prefix string to use in each new generated line. |
headers_only | `TRUE` if only basic headers should be printed. |
error | return location for error or `NULL`. |

#### Returns

a newly allocated string which should be freed with `g_free()`, or NULL if `error` is set.

Since: 1.28

### mbim_message_get_raw ()

    const guint8 *
    mbim_message_get_raw (const MbimMessage *self,
                          guint32 *length,
                          GError **error);

Gets the whole raw data buffer of the MbimMessage.

#### Parameters

self | a MbimMessage. |
length | return location for the size of the output buffer. | [out]
error | return location for error or `NULL`. |

#### Returns

The raw data buffer, or NULL if `error` is set.

Since: 1.0

### mbim_message_get_message_type ()

    MbimMessageType
    mbim_message_get_message_type (const MbimMessage *self);

Gets the message type.

#### Parameters

self | a MbimMessage. |

#### Returns

a MbimMessageType.

Since: 1.0

### mbim_message_get_message_length ()

    guint32
    mbim_message_get_message_length (const MbimMessage *self);

Gets the whole message length.

#### Parameters

self | a MbimMessage. |

#### Returns

the length of the message.

Since: 1.0

### mbim_message_get_transaction_id ()

    guint32
    mbim_message_get_transaction_id (const MbimMessage *self);

Gets the transaction ID of the message.

#### Parameters

self | a MbimMessage. |

#### Returns

the transaction ID.

Since: 1.0

### mbim_message_set_transaction_id ()

    void
    mbim_message_set_transaction_id (MbimMessage *self,
                                     guint32 transaction_id);

Sets the transaction ID of the message.

#### Parameters

self | a MbimMessage. |
transaction_id | the transaction id. |

Since: 1.0

### mbim_message_type_get_string ()

    const gchar *
    mbim_message_type_get_string (MbimMessageType val);

Gets the nickname string for the MbimMessageType specified at `val` .

#### Parameters

val | a MbimMessageType. |

#### Returns

a string with the nickname, or `NULL` if not found. Do not free the returned value.

[transfer none]

Since: 1.0

### mbim_message_open_new ()

    MbimMessage *
    mbim_message_open_new (guint32 transaction_id,
                           guint32 max_control_transfer);

Create a new MbimMessage of type `MBIM_MESSAGE_TYPE_OPEN` with the specified parameters.

#### Parameters

transaction_id | transaction ID. |
max_control_transfer | maximum control transfer. |

#### Returns

a newly created MbimMessage. The returned value should be freed with `mbim_message_unref()`.

[transfer full]

Since: 1.0

### mbim_message_open_get_max_control_transfer ()

    guint32
    mbim_message_open_get_max_control_transfer
                                   (const MbimMessage *self);

Get the maximum control transfer set to be used in the MbimMessage of type `MBIM_MESSAGE_TYPE_OPEN`.

#### Parameters

self | a MbimMessage. |

#### Returns

the maximum control transfer.

Since: 1.0

### mbim_message_open_done_get_status_code ()

    MbimStatusError
    mbim_message_open_done_get_status_code
                                   (const MbimMessage *self);

Get status code from the `MBIM_MESSAGE_TYPE_OPEN_DONE` message.

#### Parameters

self | a MbimMessage. |

#### Returns

a MbimStatusError.

Since: 1.0

### mbim_message_open_done_get_result ()

    gboolean
    mbim_message_open_done_get_result (const MbimMessage *self,
                                       GError **error);

Gets the result of the 'Open' operation in the `MBIM_MESSAGE_TYPE_OPEN_DONE` message.

#### Parameters

self | a MbimMessage. |
error | return location for error or `NULL`. |

#### Returns

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

Since: 1.0

### mbim_message_close_new ()

    MbimMessage *
    mbim_message_close_new (guint32 transaction_id);

Create a new MbimMessage of type `MBIM_MESSAGE_TYPE_CLOSE` with the specified parameters.

#### Parameters

transaction_id | transaction ID. |

#### Returns

a newly created MbimMessage. The returned value should be freed with `mbim_message_unref()`.

[transfer full]

Since: 1.0

### mbim_message_close_done_get_status_code ()

    MbimStatusError
    mbim_message_close_done_get_status_code
                                   (const MbimMessage *self);

Get status code from the `MBIM_MESSAGE_TYPE_CLOSE_DONE` message.

#### Parameters

self | a MbimMessage. |

#### Returns

a MbimStatusError.

Since: 1.0

### mbim_message_close_done_get_result ()

    gboolean
    mbim_message_close_done_get_result (const MbimMessage *self,
                                        GError **error);

Gets the result of the 'Close' operation in the `MBIM_MESSAGE_TYPE_CLOSE_DONE` message.

#### Parameters

self | a MbimMessage. |
error | return location for error or `NULL`. |

#### Returns

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

Since: 1.0

### mbim_message_error_new ()

    MbimMessage *
    mbim_message_error_new (guint32 transaction_id,
                            MbimProtocolError error_status_code);

Create a new MbimMessage of type `MBIM_MESSAGE_TYPE_HOST_ERROR` with the specified parameters.

#### Parameters

transaction_id | transaction ID. |
error_status_code | a MbimProtocolError. |

#### Returns

a newly created MbimMessage. The returned value should be freed with `mbim_message_unref()`.

[transfer full]

Since: 1.0

### mbim_message_function_error_new ()

    MbimMessage *
    mbim_message_function_error_new (guint32 transaction_id,
                                     MbimProtocolError error_status_code);

Create a new MbimMessage of type `MBIM_MESSAGE_TYPE_FUNCTION_ERROR` with the specified parameters.

#### Parameters

transaction_id | transaction ID. |
error_status_code | a MbimProtocolError. |

#### Returns

a newly created MbimMessage. The returned value should be freed with `mbim_message_unref()`.

[transfer full]

Since: 1.12

### mbim_message_error_get_error_status_code ()

    MbimProtocolError
    mbim_message_error_get_error_status_code
                                   (const MbimMessage *self);

Get the error code in a `MBIM_MESSAGE_TYPE_HOST_ERROR` or `MBIM_MESSAGE_TYPE_FUNCTION_ERROR` message.

#### Parameters

self | a MbimMessage. |

#### Returns

a MbimProtocolError.

Since: 1.0

### mbim_message_error_get_error ()

    GError *
    mbim_message_error_get_error (const MbimMessage *self);

Get the error in a `MBIM_MESSAGE_TYPE_HOST_ERROR` or `MBIM_MESSAGE_TYPE_FUNCTION_ERROR` message.

#### Parameters

self | a MbimMessage. |

#### Returns

a newly allocated GError, which should be freed with `g_error_free()`.

Since: 1.0

### mbim_message_command_new ()

    MbimMessage *
    mbim_message_command_new (guint32 transaction_id,
                              MbimService service,
                              guint32 cid,
                              MbimMessageCommandType command_type);

Create a new MbimMessage of type `MBIM_MESSAGE_TYPE_COMMAND` with the specified parameters and an empty information buffer.

#### Parameters

transaction_id | transaction ID. |
service | a MbimService. |
cid | the command ID. |
command_type | the command type. |

#### Returns

a newly created MbimMessage. The returned value should be freed with `mbim_message_unref()`.

[transfer full]

Since: 1.0

### mbim_message_command_append ()

    void
    mbim_message_command_append (MbimMessage *self,
                                 const guint8 *buffer,
                                 guint32 buffer_size);

Appends the contents of `buffer` to `self` .

#### Parameters

self | a MbimMessage. |
buffer | raw buffer to append to the message. |
buffer_size | length of the data in `buffer` . |

Since: 1.0

### mbim_message_command_get_service ()

    MbimService
    mbim_message_command_get_service (const MbimMessage *self);

Get the service of a `MBIM_MESSAGE_TYPE_COMMAND` message.

#### Parameters

self | a MbimMessage. |

#### Returns

a MbimService.

Since: 1.0

### mbim_message_command_get_service_id ()

    const MbimUuid *
    mbim_message_command_get_service_id (const MbimMessage *self);

Get the service UUID of a `MBIM_MESSAGE_TYPE_COMMAND` message.

#### Parameters

self | a MbimMessage. |

#### Returns

a MbimUuid.

Since: 1.0

### mbim_message_command_get_cid ()

    guint32
    mbim_message_command_get_cid (const MbimMessage *self);

Get the command id of a `MBIM_MESSAGE_TYPE_COMMAND` message.

#### Parameters

self | a MbimMessage. |

#### Returns

a CID.

Since: 1.0

### mbim_message_command_get_command_type ()

    MbimMessageCommandType
    mbim_message_command_get_command_type (const MbimMessage *self);

Get the command type of a `MBIM_MESSAGE_TYPE_COMMAND` message.

#### Parameters

self | a MbimMessage. |

#### Returns

a MbimMessageCommandType.

Since: 1.0

### mbim_message_command_get_raw_information_buffer ()

    const guint8 *
    mbim_message_command_get_raw_information_buffer
                                   (const MbimMessage *self,
                                    guint32 *out_length);

Gets the information buffer of the `MBIM_MESSAGE_TYPE_COMMAND` message.

#### Parameters

self | a MbimMessage. |
out_length | return location for the size of the output buffer. | [out]

#### Returns

The raw data buffer, or NULL if empty.

[transfer none]

Since: 1.0

### mbim_message_command_type_get_string ()

    const gchar *
    mbim_message_command_type_get_string (MbimMessageCommandType val);

Gets the nickname string for the MbimMessageCommandType specified at `val` .

#### Parameters

val | a MbimMessageCommandType. |

#### Returns

a string with the nickname, or `NULL` if not found. Do not free the returned value.

[transfer none]

Since: 1.0

### mbim_message_command_done_get_service ()

    MbimService
    mbim_message_command_done_get_service (const MbimMessage *self);

Get the service of a `MBIM_MESSAGE_TYPE_COMMAND_DONE` message.

#### Parameters

self | a MbimMessage. |

#### Returns

a MbimService.

Since: 1.0

### mbim_message_command_done_get_service_id ()

    const MbimUuid *
    mbim_message_command_done_get_service_id
                                   (const MbimMessage *self);

Get the service UUID of a `MBIM_MESSAGE_TYPE_COMMAND_DONE` message.

#### Parameters

self | a MbimMessage. |

#### Returns

a MbimUuid.

Since: 1.0

### mbim_message_command_done_get_cid ()

    guint32
    mbim_message_command_done_get_cid (const MbimMessage *self);

Get the command id of a `MBIM_MESSAGE_TYPE_COMMAND_DONE` message.

#### Parameters

self | a MbimMessage. |

#### Returns

a CID.

Since: 1.0

### mbim_message_command_done_get_status_code ()

    MbimStatusError
    mbim_message_command_done_get_status_code
                                   (const MbimMessage *self);

Get status code from the `MBIM_MESSAGE_TYPE_COMMAND_DONE` message.

#### Parameters

self | a MbimMessage. |

#### Returns

a MbimStatusError.

Since: 1.0

### mbim_message_command_done_get_result ()

    gboolean
    mbim_message_command_done_get_result (const MbimMessage *self,
                                          GError **error);

Gets the result of the 'Command' operation in the `MBIM_MESSAGE_TYPE_COMMAND_DONE` message.

#### Parameters

self | a MbimMessage. |
error | return location for error or `NULL`. |

#### Returns

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

Since: 1.0

### mbim_message_command_done_get_raw_information_buffer ()

    const guint8 *
    mbim_message_command_done_get_raw_information_buffer
                                   (const MbimMessage *self,
                                    guint32 *out_length);

Gets the information buffer of the `MBIM_MESSAGE_TYPE_COMMAND_DONE` message.

#### Parameters

self | a MbimMessage. |
out_length | return location for the size of the output buffer. | [out]

#### Returns

The raw data buffer, or NULL if empty.

[transfer none]

Since: 1.0

### mbim_message_indicate_status_get_service ()

    MbimService
    mbim_message_indicate_status_get_service
                                   (const MbimMessage *self);

Get the service of a `MBIM_MESSAGE_TYPE_INDICATE_STATUS` message.

#### Parameters

self | a MbimMessage. |

#### Returns

a MbimService.

Since: 1.0

### mbim_message_indicate_status_get_service_id ()

    const MbimUuid *
    mbim_message_indicate_status_get_service_id
                                   (const MbimMessage *self);

Get the service UUID of a `MBIM_MESSAGE_TYPE_INDICATE_STATUS` message.

#### Parameters

self | a MbimMessage. |

#### Returns

a MbimUuid.

Since: 1.0

### mbim_message_indicate_status_get_cid ()

    guint32
    mbim_message_indicate_status_get_cid (const MbimMessage *self);

Get the command id of a `MBIM_MESSAGE_TYPE_INDICATE_STATUS` message.

#### Parameters

self | a MbimMessage. |

#### Returns

a CID.

Since: 1.0

### mbim_message_indicate_status_get_raw_information_buffer ()

    const guint8 *
    mbim_message_indicate_status_get_raw_information_buffer
                                   (const MbimMessage *self,
                                    guint32 *out_length);

Gets the information buffer of the `MBIM_MESSAGE_TYPE_INDICATE_STATUS` message.

#### Parameters

self | a MbimMessage. |
out_length | return location for the size of the output buffer. | [out]

#### Returns

The raw data buffer, or NULL if empty.

[transfer none]

Since: 1.0

### mbim_message_response_get_result ()

    gboolean
    mbim_message_response_get_result (const MbimMessage *self,
                                      MbimMessageType expected,
                                      GError **error);

Gets the result of the operation from the response message, which can be either a `MBIM_MESSAGE_TYPE_FUNCTION_ERROR` message or a message of the specified `expected` type.

#### Parameters

self | a MbimMessage response message. |
expected | expected MbimMessageType if there isn't any error in the operation. |
error | return location for error or `NULL`. |

#### Returns

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

Since: 1.12

## Types and Values

### MbimMessage

    typedef struct _MbimMessage MbimMessage;

An opaque type representing a MBIM message.

Since: 1.0

### enum MbimMessageType

Type of MBIM messages.

#### Members

MBIM_MESSAGE_TYPE_INVALID | Invalid MBIM message. |
MBIM_MESSAGE_TYPE_OPEN | Initialization request. |
MBIM_MESSAGE_TYPE_CLOSE | Close request. |
MBIM_MESSAGE_TYPE_COMMAND | Command request. |
MBIM_MESSAGE_TYPE_HOST_ERROR | Host-reported error in the communication. |
MBIM_MESSAGE_TYPE_OPEN_DONE | Response to initialization request. |
MBIM_MESSAGE_TYPE_CLOSE_DONE | Response to close request. |
MBIM_MESSAGE_TYPE_COMMAND_DONE | Response to command request. |
MBIM_MESSAGE_TYPE_FUNCTION_ERROR | Function-reported error in the communication. |
MBIM_MESSAGE_TYPE_INDICATE_STATUS | Unsolicited message from the function. |

Since: 1.0

### struct MbimIPv4

    struct MbimIPv4 {
        guint8 addr[4];
    };

An IPv4 address.

#### Members

guint8 `addr`[4]; | 4 bytes specifying the IPv4 address. |

Since: 1.0

### struct MbimIPv6

    struct MbimIPv6 {
        guint8 addr[16];
    };

An IPv6 address.

#### Members

guint8 `addr`[16]; | 16 bytes specifying the IPv6 address. |

Since: 1.0

### enum MbimMessageCommandType

Type of command message.

#### Members

MBIM_MESSAGE_COMMAND_TYPE_UNKNOWN | Unknown type. |
MBIM_MESSAGE_COMMAND_TYPE_QUERY | Query command. |
MBIM_MESSAGE_COMMAND_TYPE_SET | Set command. |

Since: 1.0