## QmiMessage QmiMessage — Generic QMI message handling routines |

## Functions

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

## Types and Values

typedef | QmiMessage

## Description

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

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

## Functions

### QMI_MESSAGE_QMUX_MARKER

    #define QMI_MESSAGE_QMUX_MARKER (guint8)0x01

### qmi_message_new ()

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

Create a new QmiMessage with the specified parameters.

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

#### Parameters

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

#### Returns

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

[transfer full]

### qmi_message_new_from_raw ()

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

Create a new QmiMessage from the given raw data buffer.

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

#### Parameters

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

#### Returns

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

[transfer full]

### qmi_message_response_new ()

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

Create a new response QmiMessage for the specified `request` .

#### Parameters

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

#### Returns

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

[transfer full]

### qmi_message_ref ()

    QmiMessage *
    qmi_message_ref (QmiMessage *self);

Atomically increments the reference count of `self` by one.

#### Parameters

self | a QmiMessage. |

#### Returns

(transfer full) the new reference to `self` .

### qmi_message_unref ()

    void
    qmi_message_unref (QmiMessage *self);

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

#### Parameters

self | a QmiMessage. |

### qmi_message_is_request ()

    gboolean
    qmi_message_is_request (QmiMessage *self);

Checks whether the given QmiMessage is a request.

#### Parameters

self | a QmiMessage. |

#### Returns

`TRUE` if `self` is a request message, `FALSE` otherwise.

### qmi_message_is_response ()

    gboolean
    qmi_message_is_response (QmiMessage *self);

Checks whether the given QmiMessage is a response.

#### Parameters

self | a QmiMessage. |

#### Returns

`TRUE` if `self` is a response message, `FALSE` otherwise.

### qmi_message_is_indication ()

    gboolean
    qmi_message_is_indication (QmiMessage *self);

Checks whether the given QmiMessage is an indication.

#### Parameters

self | a QmiMessage. |

#### Returns

`TRUE` if `self` is an indication message, `FALSE` otherwise.

### qmi_message_get_service ()

    QmiService
    qmi_message_get_service (QmiMessage *self);

Gets the service corresponding to the given QmiMessage.

#### Parameters

self | a QmiMessage. |

#### Returns

a QmiService.

### qmi_message_get_client_id ()

    guint8
    qmi_message_get_client_id (QmiMessage *self);

Gets the client ID of the message.

#### Parameters

self | a QmiMessage. |

#### Returns

the client ID.

### qmi_message_get_transaction_id ()

    guint16
    qmi_message_get_transaction_id (QmiMessage *self);

Gets the transaction ID of the message.

#### Parameters

self | a QmiMessage. |

#### Returns

the transaction ID.

### qmi_message_get_message_id ()

    guint16
    qmi_message_get_message_id (QmiMessage *self);

Gets the ID of the message.

#### Parameters

self | a QmiMessage. |

#### Returns

the ID.

### qmi_message_get_length ()

    gsize
    qmi_message_get_length (QmiMessage *self);

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

#### Parameters

self | a QmiMessage. |

#### Returns

the length of the raw data.

### qmi_message_get_raw ()

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

Gets the raw data buffer of the QmiMessage.

#### Parameters

self | a QmiMessage. |
length | return location for the size of the output buffer. | [out]
error | return location for error or `NULL`. |

#### Returns

The raw data buffer, or NULL if `error` is set.

[transfer none]

### qmi_message_get_version_introduced ()

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

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

#### Parameters

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

#### Returns

`TRUE` if `major` and `minor` are set, `FALSE` otherwise.

### QmiMessageForeachRawTlvFn ()

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

### qmi_message_foreach_raw_tlv ()

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

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

#### Parameters

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

### qmi_message_get_raw_tlv ()

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

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

#### Parameters

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

#### Returns

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

[transfer none]

### qmi_message_add_raw_tlv ()

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

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

#### Parameters

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

#### Returns

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

### qmi_message_set_transaction_id ()

    void
    qmi_message_set_transaction_id (QmiMessage *self,
                                    guint16 transaction_id);

Overwrites the transaction ID of the message.

#### Parameters

self | a QmiMessage. |
transaction_id | transaction id. |

### qmi_message_get_printable ()

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

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

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

#### Parameters

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

#### Returns

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

[transfer full]

### qmi_message_get_tlv_printable ()

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

Gets a printable string with the contents of the TLV.

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

#### Parameters

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

#### Returns

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

[transfer full]

## Types and Values

### QmiMessage

    typedef GByteArray QmiMessage;

An opaque type representing a QMI message.