QmiMessage

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

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

### qmi_message_set_transaction_id ()

    void                qmi_message_set_transaction_id      (QmiMessage *self,
                                                             guint16 transaction_id);

Overwrites the transaction ID of the message.

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