MbimMessage

## MbimMessage MbimMessage — Generic MBIM message handling routines |

## Synopsis

                        MbimMessage;
    enum                MbimMessageType;
    struct              MbimIPv4;
    struct              MbimIPv6;
    enum                MbimMessageCommandType;

    MbimMessage *       mbim_message_new                    (const guint8 *data,
                                                             guint32 data_length);
    MbimMessage *       mbim_message_dup                    (const MbimMessage *self);
    MbimMessage *       mbim_message_ref                    (MbimMessage *self);
    void                mbim_message_unref                  (MbimMessage *self);
    gchar *             mbim_message_get_printable          (const MbimMessage *self,
                                                             const gchar *line_prefix,
                                                             gboolean headers_only);
    const guint8 *      mbim_message_get_raw                (const MbimMessage *self,
                                                             guint32 *length,
                                                             GError **error);
    MbimMessageType     mbim_message_get_message_type       (const MbimMessage *self);
    guint32             mbim_message_get_message_length     (const MbimMessage *self);
    guint32             mbim_message_get_transaction_id     (const MbimMessage *self);
    void                mbim_message_set_transaction_id     (MbimMessage *self,
                                                             guint32 transaction_id);
    const gchar *       mbim_message_type_get_string        (MbimMessageType val);

    MbimMessage *       mbim_message_open_new               (guint32 transaction_id,
                                                             guint32 max_control_transfer);
    guint32             mbim_message_open_get_max_control_transfer
                                                            (const MbimMessage *self);

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

    MbimMessage *       mbim_message_close_new              (guint32 transaction_id);

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

    MbimMessage *       mbim_message_error_new              (guint32 transaction_id,
                                                             MbimProtocolError error_status_code);
    MbimProtocolError   mbim_message_error_get_error_status_code
                                                            (const MbimMessage *self);
    GError *            mbim_message_error_get_error        (const MbimMessage *self);

    MbimMessage *       mbim_message_command_new            (guint32 transaction_id,
                                                             MbimService service,
                                                             guint32 cid,
                                                             MbimMessageCommandType command_type);
    void                mbim_message_command_append         (MbimMessage *self,
                                                             const guint8 *buffer,
                                                             guint32 buffer_size);
    MbimService         mbim_message_command_get_service    (const MbimMessage *self);
    const MbimUuid *    mbim_message_command_get_service_id (const MbimMessage *self);
    guint32             mbim_message_command_get_cid        (const MbimMessage *self);
    MbimMessageCommandType mbim_message_command_get_command_type
                                                            (const MbimMessage *self);
    const guint8 *      mbim_message_command_get_raw_information_buffer
                                                            (const MbimMessage *self,
                                                             guint32 *length);
    const gchar *       mbim_message_command_type_get_string
                                                            (MbimMessageCommandType val);

    MbimService         mbim_message_command_done_get_service
                                                            (const MbimMessage *self);
    const MbimUuid *    mbim_message_command_done_get_service_id
                                                            (const MbimMessage *self);
    guint32             mbim_message_command_done_get_cid   (const MbimMessage *self);
    MbimStatusError     mbim_message_command_done_get_status_code
                                                            (const MbimMessage *self);
    gboolean            mbim_message_command_done_get_result
                                                            (const MbimMessage *self,
                                                             GError **error);
    const guint8 *      mbim_message_command_done_get_raw_information_buffer
                                                            (const MbimMessage *self,
                                                             guint32 *length);

    MbimService         mbim_message_indicate_status_get_service
                                                            (const MbimMessage *self);
    const MbimUuid *    mbim_message_indicate_status_get_service_id
                                                            (const MbimMessage *self);
    guint32             mbim_message_indicate_status_get_cid
                                                            (const MbimMessage *self);
    const guint8 *      mbim_message_indicate_status_get_raw_information_buffer
                                                            (const MbimMessage *self,
                                                             guint32 *length);

## Object Hierarchy

      GBoxed
       +----MbimMessage

      GEnum
       +----MbimMessageType

      GEnum
       +----MbimMessageCommandType

## Description

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

## Details

### MbimMessage

    typedef struct _MbimMessage MbimMessage;

An opaque type representing a MBIM message.

### enum MbimMessageType

    typedef enum {
        MBIM_MESSAGE_TYPE_INVALID         = 0x00000000,
        /* From Host to Function */
        MBIM_MESSAGE_TYPE_OPEN            = 0x00000001,
        MBIM_MESSAGE_TYPE_CLOSE           = 0x00000002,
        MBIM_MESSAGE_TYPE_COMMAND         = 0x00000003,
        MBIM_MESSAGE_TYPE_HOST_ERROR      = 0x00000004,
        /* From Function to Host */
        MBIM_MESSAGE_TYPE_OPEN_DONE       = 0x80000001,
        MBIM_MESSAGE_TYPE_CLOSE_DONE      = 0x80000002,
        MBIM_MESSAGE_TYPE_COMMAND_DONE    = 0x80000003,
        MBIM_MESSAGE_TYPE_FUNCTION_ERROR  = 0x80000004,
        MBIM_MESSAGE_TYPE_INDICATE_STATUS = 0x80000007
    } MbimMessageType;

Type of MBIM messages.

`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.

### struct MbimIPv4

    struct MbimIPv4 {
        guint8 addr[4];
    };

An IPv4 address.

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

### struct MbimIPv6

    struct MbimIPv6 {
        guint8 addr[16];
    };

An IPv6 address.

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

### enum MbimMessageCommandType

    typedef enum {
        MBIM_MESSAGE_COMMAND_TYPE_UNKNOWN = -1,
        MBIM_MESSAGE_COMMAND_TYPE_QUERY   = 0,
        MBIM_MESSAGE_COMMAND_TYPE_SET     = 1
    } MbimMessageCommandType;

Type of command message.

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

### mbim_message_new ()

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

Create a MbimMessage with the given contents.

`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]

### mbim_message_dup ()

    MbimMessage *       mbim_message_dup                    (const MbimMessage *self);

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

`self` : | a MbimMessage to duplicate.
Returns : | a newly created MbimMessage, which should be freed with `mbim_message_unref()`. [transfer full]

### mbim_message_ref ()

    MbimMessage *       mbim_message_ref                    (MbimMessage *self);

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

`self` : | a MbimMessage.
Returns : | (transfer full) the new reference to `self`.

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

`self` : | a MbimMessage.

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

`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()`. [transfer full]

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

`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. [transfer none]

### mbim_message_get_message_type ()

    MbimMessageType     mbim_message_get_message_type       (const MbimMessage *self);

Gets the message type.

`self` : | a MbimMessage.
Returns : | a MbimMessageType.

### mbim_message_get_message_length ()

    guint32             mbim_message_get_message_length     (const MbimMessage *self);

Gets the whole message length.

`self` : | a MbimMessage.
Returns : | the length of the message.

### mbim_message_get_transaction_id ()

    guint32             mbim_message_get_transaction_id     (const MbimMessage *self);

Gets the transaction ID of the message.

`self` : | a MbimMessage.
Returns : | the transaction ID.

### mbim_message_set_transaction_id ()

    void                mbim_message_set_transaction_id     (MbimMessage *self,
                                                             guint32 transaction_id);

Sets the transaction ID of the message.

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

### mbim_message_type_get_string ()

    const gchar *       mbim_message_type_get_string        (MbimMessageType val);

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

`val` : | a MbimMessageType.
Returns : | a string with the nickname, or `NULL` if not found. Do not free the returned value. [transfer none]

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

`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]

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

`self` : | a MbimMessage.
Returns : | the maximum control transfer.

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

`self` : | a MbimMessage.
Returns : | a MbimStatusError.

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

`self` : | a MbimMessage.
`error` : | return location for error or `NULL`.
Returns : | `TRUE` if the operation succeeded, `FALSE` if `error` is set.

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

`transaction_id` : | transaction ID.
Returns : | a newly created MbimMessage. The returned value should be freed with `mbim_message_unref()`. [transfer full]

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

`self` : | a MbimMessage.
Returns : | a MbimStatusError.

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

`self` : | a MbimMessage.
`error` : | return location for error or `NULL`.
Returns : | `TRUE` if the operation succeeded, `FALSE` if `error` is set.

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

`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]

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

`self` : | a MbimMessage.
Returns : | a MbimProtocolError.

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

`self` : | a MbimMessage.
Returns : | a newly allocated GError, which should be freed with `g_error_free()`.

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

`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]

### mbim_message_command_append ()

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

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

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

### mbim_message_command_get_service ()

    MbimService         mbim_message_command_get_service    (const MbimMessage *self);

Get the service of a `MBIM_MESSAGE_TYPE_COMMAND` message.

`self` : | a MbimMessage.
Returns : | a MbimService.

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

`self` : | a MbimMessage.
Returns : | a MbimUuid.

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

`self` : | a MbimMessage.
Returns : | a CID.

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

`self` : | a MbimMessage.
Returns : | a MbimMessageCommandType.

### mbim_message_command_get_raw_information_buffer ()

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

Gets the information buffer of the `MBIM_MESSAGE_TYPE_COMMAND` message.

`self` : | a MbimMessage.
`length` : | return location for the size of the output buffer. [out]
Returns : | The raw data buffer, or NULL if empty. [transfer none]

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

`val` : | a MbimMessageCommandType.
Returns : | a string with the nickname, or `NULL` if not found. Do not free the returned value. [transfer none]

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

`self` : | a MbimMessage.
Returns : | a MbimService.

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

`self` : | a MbimMessage.
Returns : | a MbimUuid.

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

`self` : | a MbimMessage.
Returns : | a CID.

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

`self` : | a MbimMessage.
Returns : | a MbimStatusError.

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

`self` : | a MbimMessage.
`error` : | return location for error or `NULL`.
Returns : | `TRUE` if the operation succeeded, `FALSE` if `error` is set.

### mbim_message_command_done_get_raw_information_buffer ()

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

Gets the information buffer of the `MBIM_MESSAGE_TYPE_COMMAND_DONE` message.

`self` : | a MbimMessage.
`length` : | return location for the size of the output buffer. [out]
Returns : | The raw data buffer, or NULL if empty. [transfer none]

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

`self` : | a MbimMessage.
Returns : | a MbimService.

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

`self` : | a MbimMessage.
Returns : | a MbimUuid.

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

`self` : | a MbimMessage.
Returns : | a CID.

### mbim_message_indicate_status_get_raw_information_buffer ()

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

Gets the information buffer of the `MBIM_MESSAGE_TYPE_INDICATE_STATUS` message.

`self` : | a MbimMessage.
`length` : | return location for the size of the output buffer. [out]
Returns : | The raw data buffer, or NULL if empty. [transfer none]