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 contains all bytes it is expected to contain and that it is of a valid type.

This operation also ensures the message is complete and not a partial MBIM fragment.

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