QmiMessage: libqmi-glib Reference Manual

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

#define | QMI_MESSAGE_QMUX_MARKER
typedef | QmiMessage

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