QmiMessage

QmiMessage — Generic QMI message handling routines

Functions

QmiMessage * qmi_message_new ()
QmiMessage * qmi_message_new_from_raw ()
QmiMessage * qmi_message_new_from_data ()
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 ()
const guint8 * qmi_message_get_data ()
gsize qmi_message_tlv_write_init ()
void qmi_message_tlv_write_reset ()
gboolean qmi_message_tlv_write_complete ()
gboolean qmi_message_tlv_write_guint8 ()
gboolean qmi_message_tlv_write_gint8 ()
gboolean qmi_message_tlv_write_guint16 ()
gboolean qmi_message_tlv_write_gint16 ()
gboolean qmi_message_tlv_write_guint32 ()
gboolean qmi_message_tlv_write_gint32 ()
gboolean qmi_message_tlv_write_guint64 ()
gboolean qmi_message_tlv_write_gint64 ()
gboolean qmi_message_tlv_write_sized_guint ()
gboolean qmi_message_tlv_write_string ()
gsize qmi_message_tlv_read_init ()
gboolean qmi_message_tlv_read_guint8 ()
gboolean qmi_message_tlv_read_gint8 ()
gboolean qmi_message_tlv_read_guint16 ()
gboolean qmi_message_tlv_read_gint16 ()
gboolean qmi_message_tlv_read_guint32 ()
gboolean qmi_message_tlv_read_gint32 ()
gboolean qmi_message_tlv_read_guint64 ()
gboolean qmi_message_tlv_read_gint64 ()
gboolean qmi_message_tlv_read_sized_guint ()
gboolean qmi_message_tlv_read_gfloat_endian ()
gboolean qmi_message_tlv_read_gdouble ()
gboolean qmi_message_tlv_read_string ()
gboolean qmi_message_tlv_read_fixed_size_string ()
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_full ()
gchar * qmi_message_get_tlv_printable ()

Types and Values

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

Since: 1.0


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]

Since: 1.0


qmi_message_new_from_data ()

QmiMessage *
qmi_message_new_from_data (QmiService service,
                           guint8 client_id,
                           GByteArray *qmi_data,
                           GError **error);

Create a new QmiMessage for the given service and client_id and including the given QMI data buffer.

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

This method should be used instead of qmi_message_new_from_raw() if the input data doesn't have QMUX headers.

Parameters

service

a QmiService

 

client_id

client ID of the originating control point.

 

qmi_data

data buffer containing only the QMI part of the message.

[inout]

error

return location for error or NULL.

 

Returns

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

[transfer full]

Since: 1.24


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]

Since: 1.8


qmi_message_ref ()

QmiMessage *
qmi_message_ref (QmiMessage *self);

Atomically increments the reference count of self by one.

Parameters

self

a QmiMessage.

 

Returns

the new reference to self .

[transfer full]

Since: 1.0


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.

 

Since: 1.0


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.

Since: 1.8


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.

Since: 1.0


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.

Since: 1.0


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.

Since: 1.0


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.

Since: 1.0


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.

Since: 1.0


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.

Since: 1.0


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.

Since: 1.0


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]

Since: 1.0


qmi_message_get_data ()

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

Gets the data buffer of the QmiMessage without the QMUX header.

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 QMI buffer, or NULL if error is set.

[transfer none]

Since: 1.24


qmi_message_tlv_write_init ()

gsize
qmi_message_tlv_write_init (QmiMessage *self,
                            guint8 type,
                            GError **error);

Starts building a new TLV in the QmiMessage.

In order to finish adding the TLV, qmi_message_tlv_write_complete() needs to be called.

If any error happens adding fields on the TLV, the previous state can be recovered using qmi_message_tlv_write_reset().

Parameters

self

a QmiMessage.

 

type

specific ID of the TLV to add.

 

error

return location for error or NULL.

 

Returns

the offset where the TLV was started to be added, or 0 if an error happens.

Since: 1.12


qmi_message_tlv_write_reset ()

void
qmi_message_tlv_write_reset (QmiMessage *self,
                             gsize tlv_offset);

Removes the TLV being currently added.

Parameters

self

a QmiMessage.

 

tlv_offset

offset that was returned by qmi_message_tlv_write_init().

 

Since: 1.12


qmi_message_tlv_write_complete ()

gboolean
qmi_message_tlv_write_complete (QmiMessage *self,
                                gsize tlv_offset,
                                GError **error);

Completes building a TLV in the QmiMessage.

In case of error the TLV will be reseted; i.e. there is no need to explicitly call qmi_message_tlv_write_reset().

Parameters

self

a QmiMessage.

 

tlv_offset

offset that was returned by qmi_message_tlv_write_init().

 

error

return location for error or NULL.

 

Returns

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

Since: 1.12


qmi_message_tlv_write_guint8 ()

gboolean
qmi_message_tlv_write_guint8 (QmiMessage *self,
                              guint8 in,
                              GError **error);

Appends an unsigned byte to the TLV being built.

Parameters

self

a QmiMessage.

 

in

a guint8.

 

error

return location for error or NULL.

 

Returns

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

Since: 1.12


qmi_message_tlv_write_gint8 ()

gboolean
qmi_message_tlv_write_gint8 (QmiMessage *self,
                             gint8 in,
                             GError **error);

Appends a signed byte variable to the TLV being built.

Parameters

self

a QmiMessage.

 

in

a gint8.

 

error

return location for error or NULL.

 

Returns

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

Since: 1.12


qmi_message_tlv_write_guint16 ()

gboolean
qmi_message_tlv_write_guint16 (QmiMessage *self,
                               QmiEndian endian,
                               guint16 in,
                               GError **error);

Appends an unsigned 16-bit integer to the TLV being built. The number to be written is expected to be given in host endianness, and this method takes care of converting the value written to the byte order specified by endian .

Parameters

self

a QmiMessage.

 

endian

target endianness, swapped from host byte order if necessary.

 

in

a guint16 in host byte order.

 

error

return location for error or NULL.

 

Returns

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

Since: 1.12


qmi_message_tlv_write_gint16 ()

gboolean
qmi_message_tlv_write_gint16 (QmiMessage *self,
                              QmiEndian endian,
                              gint16 in,
                              GError **error);

Appends a signed 16-bit integer to the TLV being built. The number to be written is expected to be given in host endianness, and this method takes care of converting the value written to the byte order specified by endian .

Parameters

self

a QmiMessage.

 

endian

target endianness, swapped from host byte order if necessary.

 

in

a gint16 in host byte order.

 

error

return location for error or NULL.

 

Returns

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

Since: 1.12


qmi_message_tlv_write_guint32 ()

gboolean
qmi_message_tlv_write_guint32 (QmiMessage *self,
                               QmiEndian endian,
                               guint32 in,
                               GError **error);

Appends an unsigned 32-bit integer to the TLV being built. The number to be written is expected to be given in host endianness, and this method takes care of converting the value written to the byte order specified by endian .

Parameters

self

a QmiMessage.

 

endian

target endianness, swapped from host byte order if necessary.

 

in

a guint32 in host byte order.

 

error

return location for error or NULL.

 

Returns

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

Since: 1.12


qmi_message_tlv_write_gint32 ()

gboolean
qmi_message_tlv_write_gint32 (QmiMessage *self,
                              QmiEndian endian,
                              gint32 in,
                              GError **error);

Appends a signed 32-bit integer to the TLV being built. The number to be written is expected to be given in host endianness, and this method takes care of converting the value written to the byte order specified by endian .

Parameters

self

a QmiMessage.

 

endian

target endianness, swapped from host byte order if necessary.

 

in

a gint32 in host byte order.

 

error

return location for error or NULL.

 

Returns

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

Since: 1.12


qmi_message_tlv_write_guint64 ()

gboolean
qmi_message_tlv_write_guint64 (QmiMessage *self,
                               QmiEndian endian,
                               guint64 in,
                               GError **error);

Appends an unsigned 64-bit integer to the TLV being built. The number to be written is expected to be given in host endianness, and this method takes care of converting the value written to the byte order specified by endian .

Parameters

self

a QmiMessage.

 

endian

target endianness, swapped from host byte order if necessary.

 

in

a guint64 in host byte order.

 

error

return location for error or NULL.

 

Returns

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

Since: 1.12


qmi_message_tlv_write_gint64 ()

gboolean
qmi_message_tlv_write_gint64 (QmiMessage *self,
                              QmiEndian endian,
                              gint64 in,
                              GError **error);

Appends a signed 32-bit integer to the TLV being built. The number to be written is expected to be given in host endianness, and this method takes care of converting the value written to the byte order specified by endian .

Parameters

self

a QmiMessage.

 

endian

target endianness, swapped from host byte order if necessary.

 

in

a gint64 in host byte order.

 

error

return location for error or NULL.

 

Returns

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

Since: 1.12


qmi_message_tlv_write_sized_guint ()

gboolean
qmi_message_tlv_write_sized_guint (QmiMessage *self,
                                   guint n_bytes,
                                   QmiEndian endian,
                                   guint64 in,
                                   GError **error);

Appends a n_bytes -sized unsigned integer to the TLV being built. The number to be written is expected to be given in host endianness, and this method takes care of converting the value written to the byte order specified by endian .

The value of n_bytes can be any between 1 and 8.

Parameters

self

a QmiMessage.

 

n_bytes

number of bytes to write.

 

endian

target endianness, swapped from host byte order if necessary.

 

in

a guint64 in host byte order.

 

error

return location for error or NULL.

 

Returns

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

Since: 1.12


qmi_message_tlv_write_string ()

gboolean
qmi_message_tlv_write_string (QmiMessage *self,
                              guint8 n_size_prefix_bytes,
                              const gchar *in,
                              gssize in_length,
                              GError **error);

Appends a string to the TLV being built.

Fixed-sized strings should give n_size_prefix_bytes equal to 0.

Parameters

self

a QmiMessage.

 

n_size_prefix_bytes

number of bytes to use in the size prefix.

 

in

string to write.

 

in_length

length of in , or -1 if in is NUL-terminated.

 

error

return location for error or NULL.

 

Returns

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

Since: 1.12


qmi_message_tlv_read_init ()

gsize
qmi_message_tlv_read_init (QmiMessage *self,
                           guint8 type,
                           guint16 *out_tlv_length,
                           GError **error);

Starts reading a given TLV from the QmiMessage.

Parameters

self

a QmiMessage.

 

type

specific ID of the TLV to read.

 

out_tlv_length

optional return location for the TLV size.

[out]

error

return location for error or NULL.

 

Returns

the offset where the TLV starts, or 0 if an error happens.

Since: 1.12


qmi_message_tlv_read_guint8 ()

gboolean
qmi_message_tlv_read_guint8 (QmiMessage *self,
                             gsize tlv_offset,
                             gsize *offset,
                             guint8 *out,
                             GError **error);

Reads an unsigned byte from the TLV.

offset needs to point to a valid gsize specifying the index to start reading from within the TLV value (0 for the first item). If the variable is successfully read, offset will be updated to point past the read item.

Parameters

self

a QmiMessage.

 

tlv_offset

offset that was returned by qmi_message_tlv_read_init().

 

offset

address of the offset within the TLV value.

[inout]

out

return location for the read guint8.

[out]

error

return location for error or NULL.

 

Returns

TRUE if the variable is successfully read, otherwise FALSE is returned and error is set.

Since: 1.12


qmi_message_tlv_read_gint8 ()

gboolean
qmi_message_tlv_read_gint8 (QmiMessage *self,
                            gsize tlv_offset,
                            gsize *offset,
                            gint8 *out,
                            GError **error);

Reads a signed byte from the TLV.

offset needs to point to a valid gsize specifying the index to start reading from within the TLV value (0 for the first item). If the variable is successfully read, offset will be updated to point past the read item.

Parameters

self

a QmiMessage.

 

tlv_offset

offset that was returned by qmi_message_tlv_read_init().

 

offset

address of a the offset within the TLV value.

[inout]

out

return location for the read gint8.

[out]

error

return location for error or NULL.

 

Returns

TRUE if the variable is successfully read, otherwise FALSE is returned and error is set.

Since: 1.12


qmi_message_tlv_read_guint16 ()

gboolean
qmi_message_tlv_read_guint16 (QmiMessage *self,
                              gsize tlv_offset,
                              gsize *offset,
                              QmiEndian endian,
                              guint16 *out,
                              GError **error);

Reads an unsigned 16-bit integer from the TLV, in host byte order.

offset needs to point to a valid gsize specifying the index to start reading from within the TLV value (0 for the first item). If the variable is successfully read, offset will be updated to point past the read item.

Parameters

self

a QmiMessage.

 

tlv_offset

offset that was returned by qmi_message_tlv_read_init().

 

offset

address of a the offset within the TLV value.

[inout]

endian

source endianness, which will be swapped to host byte order if necessary.

 

out

return location for the read guint16.

[out]

error

return location for error or NULL.

 

Returns

TRUE if the variable is successfully read, otherwise FALSE is returned and error is set.

Since: 1.12


qmi_message_tlv_read_gint16 ()

gboolean
qmi_message_tlv_read_gint16 (QmiMessage *self,
                             gsize tlv_offset,
                             gsize *offset,
                             QmiEndian endian,
                             gint16 *out,
                             GError **error);

Reads a signed 16-bit integer from the TLV, in host byte order.

offset needs to point to a valid gsize specifying the index to start reading from within the TLV value (0 for the first item). If the variable is successfully read, offset will be updated to point past the read item.

Parameters

self

a QmiMessage.

 

tlv_offset

offset that was returned by qmi_message_tlv_read_init().

 

offset

address of a the offset within the TLV value.

[inout]

endian

source endianness, which will be swapped to host byte order if necessary.

 

out

return location for the read gint16.

[out]

error

return location for error or NULL.

 

Returns

TRUE if the variable is successfully read, otherwise FALSE is returned and error is set.

Since: 1.12


qmi_message_tlv_read_guint32 ()

gboolean
qmi_message_tlv_read_guint32 (QmiMessage *self,
                              gsize tlv_offset,
                              gsize *offset,
                              QmiEndian endian,
                              guint32 *out,
                              GError **error);

Reads an unsigned 32-bit integer from the TLV, in host byte order.

offset needs to point to a valid gsize specifying the index to start reading from within the TLV value (0 for the first item). If the variable is successfully read, offset will be updated to point past the read item.

Parameters

self

a QmiMessage.

 

tlv_offset

offset that was returned by qmi_message_tlv_read_init().

 

offset

address of a the offset within the TLV value.

[inout]

endian

source endianness, which will be swapped to host byte order if necessary.

 

out

return location for the read guint32.

[out]

error

return location for error or NULL.

 

Returns

TRUE if the variable is successfully read, otherwise FALSE is returned and error is set.

Since: 1.12


qmi_message_tlv_read_gint32 ()

gboolean
qmi_message_tlv_read_gint32 (QmiMessage *self,
                             gsize tlv_offset,
                             gsize *offset,
                             QmiEndian endian,
                             gint32 *out,
                             GError **error);

Reads a signed 32-bit integer from the TLV, in host byte order.

offset needs to point to a valid gsize specifying the index to start reading from within the TLV value (0 for the first item). If the variable is successfully read, offset will be updated to point past the read item.

Parameters

self

a QmiMessage.

 

tlv_offset

offset that was returned by qmi_message_tlv_read_init().

 

offset

address of a the offset within the TLV value.

[inout]

endian

source endianness, which will be swapped to host byte order if necessary.

 

out

return location for the read gint32.

[out]

error

return location for error or NULL.

 

Returns

TRUE if the variable is successfully read, otherwise FALSE is returned and error is set.

Since: 1.12


qmi_message_tlv_read_guint64 ()

gboolean
qmi_message_tlv_read_guint64 (QmiMessage *self,
                              gsize tlv_offset,
                              gsize *offset,
                              QmiEndian endian,
                              guint64 *out,
                              GError **error);

Reads an unsigned 64-bit integer from the TLV, in host byte order.

offset needs to point to a valid gsize specifying the index to start reading from within the TLV value (0 for the first item). If the variable is successfully read, offset will be updated to point past the read item.

Parameters

self

a QmiMessage.

 

tlv_offset

offset that was returned by qmi_message_tlv_read_init().

 

offset

address of a the offset within the TLV value.

[inout]

endian

source endianness, which will be swapped to host byte order if necessary.

 

out

return location for the read guint64.

[out]

error

return location for error or NULL.

 

Returns

TRUE if the variable is successfully read, otherwise FALSE is returned and error is set.

Since: 1.12


qmi_message_tlv_read_gint64 ()

gboolean
qmi_message_tlv_read_gint64 (QmiMessage *self,
                             gsize tlv_offset,
                             gsize *offset,
                             QmiEndian endian,
                             gint64 *out,
                             GError **error);

Reads a signed 64-bit integer from the TLV, in host byte order.

offset needs to point to a valid gsize specifying the index to start reading from within the TLV value (0 for the first item). If the variable is successfully read, offset will be updated to point past the read item.

Parameters

self

a QmiMessage.

 

tlv_offset

offset that was returned by qmi_message_tlv_read_init().

 

offset

address of a the offset within the TLV value.

[inout]

endian

source endianness, which will be swapped to host byte order if necessary.

 

out

return location for the read gint64.

[out]

error

return location for error or NULL.

 

Returns

TRUE if the variable is successfully read, otherwise FALSE is returned and error is set.

Since: 1.12


qmi_message_tlv_read_sized_guint ()

gboolean
qmi_message_tlv_read_sized_guint (QmiMessage *self,
                                  gsize tlv_offset,
                                  gsize *offset,
                                  guint n_bytes,
                                  QmiEndian endian,
                                  guint64 *out,
                                  GError **error);

Reads a b_bytes -sized integer from the TLV, in host byte order.

offset needs to point to a valid gsize specifying the index to start reading from within the TLV value (0 for the first item). If the variable is successfully read, offset will be updated to point past the read item.

Parameters

self

a QmiMessage.

 

tlv_offset

offset that was returned by qmi_message_tlv_read_init().

 

offset

address of a the offset within the TLV value.

[inout]

n_bytes

number of bytes to read.

 

endian

source endianness, which will be swapped to host byte order if necessary.

 

out

return location for the read guint64.

[out]

error

return location for error or NULL.

 

Returns

TRUE if the variable is successfully read, otherwise FALSE is returned and error is set.

Since: 1.12


qmi_message_tlv_read_gfloat_endian ()

gboolean
qmi_message_tlv_read_gfloat_endian (QmiMessage *self,
                                    gsize tlv_offset,
                                    gsize *offset,
                                    QmiEndian endian,
                                    gfloat *out,
                                    GError **error);

Reads a 32-bit floating-point number from the TLV.

offset needs to point to a valid gsize specifying the index to start reading from within the TLV value (0 for the first item). If the variable is successfully read, offset will be updated to point past the read item.

Parameters

self

a QmiMessage.

 

tlv_offset

offset that was returned by qmi_message_tlv_read_init().

 

offset

address of a the offset within the TLV value.

[inout]

endian

source endianness, which will be swapped to host byte order if necessary.

 

out

return location for the read gfloat.

[out]

error

return location for error or NULL.

 

Returns

TRUE if the variable is successfully read, otherwise FALSE is returned and error is set.

Since: 1.12


qmi_message_tlv_read_gdouble ()

gboolean
qmi_message_tlv_read_gdouble (QmiMessage *self,
                              gsize tlv_offset,
                              gsize *offset,
                              QmiEndian endian,
                              gdouble *out,
                              GError **error);

Reads a 64-bit floating-point number from the TLV.

offset needs to point to a valid gsize specifying the index to start reading from within the TLV value (0 for the first item). If the variable is successfully read, offset will be updated to point past the read item.

Parameters

self

a QmiMessage.

 

tlv_offset

offset that was returned by qmi_message_tlv_read_init().

 

offset

address of a the offset within the TLV value.

[inout]

endian

source endianness, which will be swapped to host byte order if necessary.

 

out

return location for the read gdouble.

[out]

error

return location for error or NULL.

 

Returns

TRUE if the variable is successfully read, otherwise FALSE is returned and error is set.

Since: 1.22


qmi_message_tlv_read_string ()

gboolean
qmi_message_tlv_read_string (QmiMessage *self,
                             gsize tlv_offset,
                             gsize *offset,
                             guint8 n_size_prefix_bytes,
                             guint16 max_size,
                             gchar **out,
                             GError **error);

Reads a string from the TLV.

offset needs to point to a valid gsize specifying the index to start reading from within the TLV value (0 for the first item). If the variable is successfully read, offset will be updated to point past the read item.

Since 1.24.6 the read string is guaranteed to be valid UTF-8. Also, in order to overcome known firmware errors on string fields, this method will also attempt to parse the string as GSM-7 or UCS-2 if the initial UTF-8 validation fails.

Parameters

self

a QmiMessage.

 

tlv_offset

offset that was returned by qmi_message_tlv_read_init().

 

offset

address of a the offset within the TLV value.

[inout]

n_size_prefix_bytes

number of bytes used in the size prefix.

 

max_size

maximum number of bytes to read, or 0 to read all available bytes.

 

out

return location for the read string. The returned value should be freed with g_free().

[out]

error

return location for error or NULL.

 

Returns

TRUE if the variable is successfully read, otherwise FALSE is returned and error is set.

Since: 1.12


qmi_message_tlv_read_fixed_size_string ()

gboolean
qmi_message_tlv_read_fixed_size_string
                               (QmiMessage *self,
                                gsize tlv_offset,
                                gsize *offset,
                                guint16 string_length,
                                gchar *out,
                                GError **error);

Reads a string from the TLV.

The string written in out will need to be NUL-terminated by the caller.

offset needs to point to a valid gsize specifying the index to start reading from within the TLV value (0 for the first item). If the variable is successfully read, offset will be updated to point past the read item.

Since 1.24.6 the read string is guaranteed to be valid UTF-8.

The fixed sized field may be suffixed with e.g. 0xFF if the contents are shorter than string_length . Since 1.26, this method will return the valid UTF-8 characters in the start of the string, instead of returning an error when doing the full UTF-8 string validation.

Parameters

self

a QmiMessage.

 

tlv_offset

offset that was returned by qmi_message_tlv_read_init().

 

offset

address of a the offset within the TLV value.

[inout]

string_length

amount of bytes to read.

 

out

buffer preallocated by the client, with at least string_length bytes.

[out]

error

return location for error or NULL.

 

Returns

TRUE if the variable is successfully read, otherwise FALSE is returned and error is set.

Since: 1.12


QmiMessageForeachRawTlvFn ()

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

Callback type to use when iterating raw TLVs with qmi_message_foreach_raw_tlv().

Parameters

type

specific ID of the TLV.

 

value

value of the TLV.

 

length

length of the TLV, in bytes.

 

user_data

user data.

 

Since: 1.0


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.

[scope call]

user_data

user data to pass to the function.

[closure func]

Since: 1.0


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]

Since: 1.0


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 is successfully added, otherwise FALSE is returned and error is set.

Since: 1.0


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.

 

Since: 1.8


qmi_message_get_printable_full ()

gchar *
qmi_message_get_printable_full (QmiMessage *self,
                                QmiMessageContext *context,
                                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.

The translation of the contents may be specific to the context provided, e.g. for vendor-specific messages.

If no context given, the behavior is the same as qmi_message_get_printable().

Parameters

self

a QmiMessage.

 

context

a QmiMessageContext.

 

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]

Since: 1.18


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]

Since: 1.0

Types and Values

QMI_MESSAGE_QMUX_MARKER

#define QMI_MESSAGE_QMUX_MARKER (guint8) 0x01

First byte of every QMI message.

Since: 1.0


QmiMessage

typedef GByteArray QmiMessage;

An opaque type representing a QMI message.

Since: 1.0