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

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.

 

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