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]
Generated by GTK-Doc V1.19