libqmi-glib Reference Manual: QmiMessage

QmiMessage

QmiMessage — Generic QMI message handling routines

Functions

#define	QMI_MESSAGE_QMUX_MARKER
QmiMessage *	qmi_message_new ()
QmiMessage *	qmi_message_new_from_raw ()
QmiMessage *	qmi_message_response_new ()
QmiMessage *	qmi_message_ref ()
void	qmi_message_unref ()
gboolean	qmi_message_is_request ()
gboolean	qmi_message_is_response ()
gboolean	qmi_message_is_indication ()
QmiService	qmi_message_get_service ()
guint8	qmi_message_get_client_id ()
guint16	qmi_message_get_transaction_id ()
guint16	qmi_message_get_message_id ()
gsize	qmi_message_get_length ()
const guint8 *	qmi_message_get_raw ()
gboolean	qmi_message_get_version_introduced ()
void	(*QmiMessageForeachRawTlvFn) ()
void	qmi_message_foreach_raw_tlv ()
const guint8 *	qmi_message_get_raw_tlv ()
gboolean	qmi_message_add_raw_tlv ()
void	qmi_message_set_transaction_id ()
gchar *	qmi_message_get_printable ()
gchar *	qmi_message_get_tlv_printable ()

Types and Values

typedef

QmiMessage

Object Hierarchy

Description

QmiMessage is a generic type representing a QMI message of any kind (request, response, indication) or service (including QMI_SERVICE_CTL).

This set of generic routines help in handling these message types, and allow creating any kind of message with any kind of TLV.

Functions

QMI_MESSAGE_QMUX_MARKER

#define QMI_MESSAGE_QMUX_MARKER (guint8)0x01

qmi_message_new ()

QmiMessage *
qmi_message_new (QmiService service,
                 guint8 client_id,
                 guint16 transaction_id,
                 guint16 message_id);

Create a new QmiMessage with the specified parameters.

Note that transaction_id must be less than G_MAXUINT8 if service is QMI_SERVICE_CTL.

Parameters

service	a QmiService
client_id	client ID of the originating control point.
transaction_id	transaction ID.
message_id	message ID.

Returns

a newly created QmiMessage. The returned value should be freed with qmi_message_unref().

[transfer full]

qmi_message_new_from_raw ()

QmiMessage *
qmi_message_new_from_raw (GByteArray *raw,
                          GError **error);

Create a new QmiMessage from the given raw data buffer.

Whenever a complete QMI message is read, its raw data gets removed from the raw buffer.

Parameters

raw	raw data buffer.	[inout]
error	return location for error or `NULL`.

Returns

a newly created QmiMessage, which should be freed with qmi_message_unref(). If raw doesn't contain a complete QMI message NULL is returned. If there is a complete QMI message but it appears not to be valid, NULL is returned and error is set.

[transfer full]

qmi_message_response_new ()

QmiMessage *
qmi_message_response_new (QmiMessage *request,
                          QmiProtocolError error);

Create a new response QmiMessage for the specified request .

Parameters

request	a request QmiMessage.
error	a QmiProtocolError to set in the result TLV.

Returns

a newly created QmiMessage. The returned value should be freed with qmi_message_unref().

[transfer full]

qmi_message_ref ()

QmiMessage *
qmi_message_ref (QmiMessage *self);

Atomically increments the reference count of self by one.

Parameters

self

a QmiMessage.

Returns

(transfer full) the new reference to self .

qmi_message_unref ()

void
qmi_message_unref (QmiMessage *self);

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

Parameters

self

a QmiMessage.

qmi_message_is_request ()

gboolean
qmi_message_is_request (QmiMessage *self);

Checks whether the given QmiMessage is a request.

Parameters

self

a QmiMessage.

Returns

TRUE if self is a request message, FALSE otherwise.

qmi_message_is_response ()

gboolean
qmi_message_is_response (QmiMessage *self);

Checks whether the given QmiMessage is a response.

Parameters

self

a QmiMessage.

Returns

TRUE if self is a response message, FALSE otherwise.

qmi_message_is_indication ()

gboolean
qmi_message_is_indication (QmiMessage *self);

Checks whether the given QmiMessage is an indication.

Parameters

self

a QmiMessage.

Returns

TRUE if self is an indication message, FALSE otherwise.

qmi_message_get_service ()

QmiService
qmi_message_get_service (QmiMessage *self);

Gets the service corresponding to the given QmiMessage.

Parameters

self

a QmiMessage.

Returns

a QmiService.

qmi_message_get_client_id ()

guint8
qmi_message_get_client_id (QmiMessage *self);

Gets the client ID of the message.

Parameters

self

a QmiMessage.

Returns

the client ID.

qmi_message_get_transaction_id ()

guint16
qmi_message_get_transaction_id (QmiMessage *self);

Gets the transaction ID of the message.

Parameters

self

a QmiMessage.

Returns

the transaction ID.

qmi_message_get_message_id ()

guint16
qmi_message_get_message_id (QmiMessage *self);

Gets the ID of the message.

Parameters

self

a QmiMessage.

Returns

the ID.

qmi_message_get_length ()

gsize
qmi_message_get_length (QmiMessage *self);

Gets the length of the raw data corresponding to the given QmiMessage.

Parameters

self

a QmiMessage.

Returns

the length of the raw data.

qmi_message_get_raw ()

const guint8 *
qmi_message_get_raw (QmiMessage *self,
                     gsize *length,
                     GError **error);

Gets the raw data buffer of the QmiMessage.

Parameters

self	a QmiMessage.
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]

qmi_message_get_version_introduced ()

gboolean
qmi_message_get_version_introduced (QmiMessage *self,
                                    guint *major,
                                    guint *minor);

Gets, if known, the service version in which the given message was first introduced.

Parameters

self	a QmiMessage.
major	(out) return location for the major version.
minor	(out) return location for the minor version.

Returns

TRUE if major and minor are set, FALSE otherwise.

QmiMessageForeachRawTlvFn ()

void
(*QmiMessageForeachRawTlvFn) (guint8 type,
                              const guint8 *value,
                              gsize length,
                              gpointer user_data);

qmi_message_foreach_raw_tlv ()

void
qmi_message_foreach_raw_tlv (QmiMessage *self,
                             QmiMessageForeachRawTlvFn func,
                             gpointer user_data);

Calls the given function for each TLV found within the QmiMessage.

Parameters

self	a QmiMessage.
func	the function to call for each TLV.
user_data	user data to pass to the function.

qmi_message_get_raw_tlv ()

const guint8 *
qmi_message_get_raw_tlv (QmiMessage *self,
                         guint8 type,
                         guint16 *length);

Get the raw data buffer of a specific TLV within the QmiMessage.

Parameters

self	a QmiMessage.
type	specific ID of the TLV to get.
length	return location for the length of the TLV.	[out]

Returns

The raw data buffer of the TLV, or NULL if not found.

[transfer none]

qmi_message_add_raw_tlv ()

gboolean
qmi_message_add_raw_tlv (QmiMessage *self,
                         guint8 type,
                         const guint8 *raw,
                         gsize length,
                         GError **error);

Creates a new type TLV with the value given in raw , and adds it to the QmiMessage.

Parameters

self	a QmiMessage.
type	specific ID of the TLV to add.
raw	raw data buffer with the value of the TLV.
length	length of the raw data buffer.
error	return location for error or `NULL`.

Returns

TRUE if the TLV as successfully added, otherwise FALSE is returned and error is set.

qmi_message_set_transaction_id ()

void
qmi_message_set_transaction_id (QmiMessage *self,
                                guint16 transaction_id);

Overwrites the transaction ID of the message.

Parameters

self	a QmiMessage.
transaction_id	transaction id.

qmi_message_get_printable ()

gchar *
qmi_message_get_printable (QmiMessage *self,
                           const gchar *line_prefix);

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

If known, the printable string will contain translated TLV values as well as the raw data buffer contents.

Parameters

self	a QmiMessage.
line_prefix	prefix string to use in each new generated line.

Returns

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

[transfer full]

qmi_message_get_tlv_printable ()

gchar *
qmi_message_get_tlv_printable (QmiMessage *self,
                               const gchar *line_prefix,
                               guint8 type,
                               const guint8 *raw,
                               gsize raw_length);

Gets a printable string with the contents of the TLV.

This method is the most generic one and doesn't try to translate the TLV contents.

Parameters

self	a QmiMessage.
line_prefix	prefix string to use in each new generated line.
type	type of the TLV.
raw	raw data buffer with the value of the TLV.
raw_length	length of the raw data buffer.

Returns

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

[transfer full]

Types and Values

QmiMessage

typedef GByteArray QmiMessage;

An opaque type representing a QMI message.