QmiMessage

QmiMessage — Generic QMI message handling routines

Synopsis

#define             QMI_MESSAGE_QMUX_MARKER
typedef             QmiMessage;
QmiMessage *        qmi_message_new                     (QmiService service,
                                                         guint8 client_id,
                                                         guint16 transaction_id,
                                                         guint16 message_id);
QmiMessage *        qmi_message_new_from_raw            (GByteArray *raw,
                                                         GError **error);
QmiMessage *        qmi_message_response_new            (QmiMessage *request,
                                                         QmiProtocolError error);
QmiMessage *        qmi_message_ref                     (QmiMessage *self);
void                qmi_message_unref                   (QmiMessage *self);

gboolean            qmi_message_is_request              (QmiMessage *self);
gboolean            qmi_message_is_response             (QmiMessage *self);
gboolean            qmi_message_is_indication           (QmiMessage *self);
QmiService          qmi_message_get_service             (QmiMessage *self);
guint8              qmi_message_get_client_id           (QmiMessage *self);
guint16             qmi_message_get_transaction_id      (QmiMessage *self);
guint16             qmi_message_get_message_id          (QmiMessage *self);
gsize               qmi_message_get_length              (QmiMessage *self);
const guint8 *      qmi_message_get_raw                 (QmiMessage *self,
                                                         gsize *length,
                                                         GError **error);
gboolean            qmi_message_get_version_introduced  (QmiMessage *self,
                                                         guint *major,
                                                         guint *minor);

gsize               qmi_message_tlv_write_init          (QmiMessage *self,
                                                         guint8 type,
                                                         GError **error);
void                qmi_message_tlv_write_reset         (QmiMessage *self,
                                                         gsize tlv_offset);
gboolean            qmi_message_tlv_write_complete      (QmiMessage *self,
                                                         gsize tlv_offset,
                                                         GError **error);
gboolean            qmi_message_tlv_write_guint8        (QmiMessage *self,
                                                         guint8 in,
                                                         GError **error);
gboolean            qmi_message_tlv_write_gint8         (QmiMessage *self,
                                                         gint8 in,
                                                         GError **error);
gboolean            qmi_message_tlv_write_guint16       (QmiMessage *self,
                                                         QmiEndian endian,
                                                         guint16 in,
                                                         GError **error);
gboolean            qmi_message_tlv_write_gint16        (QmiMessage *self,
                                                         QmiEndian endian,
                                                         gint16 in,
                                                         GError **error);
gboolean            qmi_message_tlv_write_guint32       (QmiMessage *self,
                                                         QmiEndian endian,
                                                         guint32 in,
                                                         GError **error);
gboolean            qmi_message_tlv_write_gint32        (QmiMessage *self,
                                                         QmiEndian endian,
                                                         gint32 in,
                                                         GError **error);
gboolean            qmi_message_tlv_write_guint64       (QmiMessage *self,
                                                         QmiEndian endian,
                                                         guint64 in,
                                                         GError **error);
gboolean            qmi_message_tlv_write_gint64        (QmiMessage *self,
                                                         QmiEndian endian,
                                                         gint64 in,
                                                         GError **error);
gboolean            qmi_message_tlv_write_sized_guint   (QmiMessage *self,
                                                         guint n_bytes,
                                                         QmiEndian endian,
                                                         guint64 in,
                                                         GError **error);
gboolean            qmi_message_tlv_write_string        (QmiMessage *self,
                                                         guint8 n_size_prefix_bytes,
                                                         const gchar *in,
                                                         gssize in_length,
                                                         GError **error);

gsize               qmi_message_tlv_read_init           (QmiMessage *self,
                                                         guint8 type,
                                                         guint16 *out_tlv_length,
                                                         GError **error);
gboolean            qmi_message_tlv_read_guint8         (QmiMessage *self,
                                                         gsize tlv_offset,
                                                         gsize *offset,
                                                         guint8 *out,
                                                         GError **error);
gboolean            qmi_message_tlv_read_gint8          (QmiMessage *self,
                                                         gsize tlv_offset,
                                                         gsize *offset,
                                                         gint8 *out,
                                                         GError **error);
gboolean            qmi_message_tlv_read_guint16        (QmiMessage *self,
                                                         gsize tlv_offset,
                                                         gsize *offset,
                                                         QmiEndian endian,
                                                         guint16 *out,
                                                         GError **error);
gboolean            qmi_message_tlv_read_gint16         (QmiMessage *self,
                                                         gsize tlv_offset,
                                                         gsize *offset,
                                                         QmiEndian endian,
                                                         gint16 *out,
                                                         GError **error);
gboolean            qmi_message_tlv_read_guint32        (QmiMessage *self,
                                                         gsize tlv_offset,
                                                         gsize *offset,
                                                         QmiEndian endian,
                                                         guint32 *out,
                                                         GError **error);
gboolean            qmi_message_tlv_read_gint32         (QmiMessage *self,
                                                         gsize tlv_offset,
                                                         gsize *offset,
                                                         QmiEndian endian,
                                                         gint32 *out,
                                                         GError **error);
gboolean            qmi_message_tlv_read_guint64        (QmiMessage *self,
                                                         gsize tlv_offset,
                                                         gsize *offset,
                                                         QmiEndian endian,
                                                         guint64 *out,
                                                         GError **error);
gboolean            qmi_message_tlv_read_gint64         (QmiMessage *self,
                                                         gsize tlv_offset,
                                                         gsize *offset,
                                                         QmiEndian endian,
                                                         gint64 *out,
                                                         GError **error);
gboolean            qmi_message_tlv_read_sized_guint    (QmiMessage *self,
                                                         gsize tlv_offset,
                                                         gsize *offset,
                                                         guint n_bytes,
                                                         QmiEndian endian,
                                                         guint64 *out,
                                                         GError **error);
gboolean            qmi_message_tlv_read_gfloat         (QmiMessage *self,
                                                         gsize tlv_offset,
                                                         gsize *offset,
                                                         gfloat *out,
                                                         GError **error);
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);
gboolean            qmi_message_tlv_read_fixed_size_string
                                                        (QmiMessage *self,
                                                         gsize tlv_offset,
                                                         gsize *offset,
                                                         guint16 string_length,
                                                         gchar *out,
                                                         GError **error);

void                (*QmiMessageForeachRawTlvFn)        (guint8 type,
                                                         const guint8 *value,
                                                         gsize length,
                                                         gpointer user_data);
void                qmi_message_foreach_raw_tlv         (QmiMessage *self,
                                                         QmiMessageForeachRawTlvFn func,
                                                         gpointer user_data);
const guint8 *      qmi_message_get_raw_tlv             (QmiMessage *self,
                                                         guint8 type,
                                                         guint16 *length);
gboolean            qmi_message_add_raw_tlv             (QmiMessage *self,
                                                         guint8 type,
                                                         const guint8 *raw,
                                                         gsize length,
                                                         GError **error);

void                qmi_message_set_transaction_id      (QmiMessage *self,
                                                         guint16 transaction_id);

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

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.

Details

QMI_MESSAGE_QMUX_MARKER

#define QMI_MESSAGE_QMUX_MARKER (guint8)0x01


QmiMessage

typedef GByteArray QmiMessage;

An opaque type representing a QMI message.


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.

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.

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.

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.

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.

self :

a QmiMessage.

qmi_message_is_request ()

gboolean            qmi_message_is_request              (QmiMessage *self);

Checks whether the given QmiMessage is a request.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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().

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.

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().

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

self :

a QmiMessage.

type :

specific ID of the TLV to read.

out_tlv_length :

optional return location for the TLV size.

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.

self :

a QmiMessage.

tlv_offset :

offset that was returned by qmi_message_tlv_read_init().

offset :

address of the offset within the TLV value.

out :

return location for the read guint8.

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.

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.

out :

return location for the read gint8.

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.

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.

endian :

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

out :

return location for the read guint16.

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.

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.

endian :

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

out :

return location for the read gint16.

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.

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.

endian :

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

out :

return location for the read guint32.

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.

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.

endian :

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

out :

return location for the read gint32.

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.

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.

endian :

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

out :

return location for the read guint64.

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.

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.

endian :

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

out :

return location for the read gint64.

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.

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.

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.

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 ()

gboolean            qmi_message_tlv_read_gfloat         (QmiMessage *self,
                                                         gsize tlv_offset,
                                                         gsize *offset,
                                                         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.

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.

out :

return location for the read gfloat.

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

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.

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().

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.

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.

string_length :

amount of bytes to read.

out :

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

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);


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.

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.

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.

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.

qmi_message_set_transaction_id ()

void                qmi_message_set_transaction_id      (QmiMessage *self,
                                                         guint16 transaction_id);

Overwrites the transaction ID of the message.

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.

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.

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]