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 ()
gchar *	mbim_message_get_printable ()
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_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.

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_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