Common utilities

Common utilities

Synopsis

enum                QmiEndian;

gboolean            qmi_utils_get_traces_enabled        (void);
void                qmi_utils_set_traces_enabled        (gboolean enabled);

void                qmi_utils_read_guint8_from_buffer   (const guint8 **buffer,
                                                         guint16 *buffer_size,
                                                         guint8 *out);
void                qmi_utils_read_gint8_from_buffer    (const guint8 **buffer,
                                                         guint16 *buffer_size,
                                                         gint8 *out);
void                qmi_utils_read_guint16_from_buffer  (const guint8 **buffer,
                                                         guint16 *buffer_size,
                                                         QmiEndian endian,
                                                         guint16 *out);
void                qmi_utils_read_gint16_from_buffer   (const guint8 **buffer,
                                                         guint16 *buffer_size,
                                                         QmiEndian endian,
                                                         gint16 *out);
void                qmi_utils_read_guint32_from_buffer  (const guint8 **buffer,
                                                         guint16 *buffer_size,
                                                         QmiEndian endian,
                                                         guint32 *out);
void                qmi_utils_read_gint32_from_buffer   (const guint8 **buffer,
                                                         guint16 *buffer_size,
                                                         QmiEndian endian,
                                                         gint32 *out);
void                qmi_utils_read_guint64_from_buffer  (const guint8 **buffer,
                                                         guint16 *buffer_size,
                                                         QmiEndian endian,
                                                         guint64 *out);
void                qmi_utils_read_gint64_from_buffer   (const guint8 **buffer,
                                                         guint16 *buffer_size,
                                                         QmiEndian endian,
                                                         gint64 *out);
void                qmi_utils_read_sized_guint_from_buffer
                                                        (const guint8 **buffer,
                                                         guint16 *buffer_size,
                                                         guint n_bytes,
                                                         QmiEndian endian,
                                                         guint64 *out);
void                qmi_utils_read_string_from_buffer   (const guint8 **buffer,
                                                         guint16 *buffer_size,
                                                         guint8 length_prefix_size,
                                                         guint16 max_size,
                                                         gchar **out);
void                qmi_utils_read_fixed_size_string_from_buffer
                                                        (const guint8 **buffer,
                                                         guint16 *buffer_size,
                                                         guint16 fixed_size,
                                                         gchar *out);

void                qmi_utils_write_guint8_to_buffer    (guint8 **buffer,
                                                         guint16 *buffer_size,
                                                         guint8 *in);
void                qmi_utils_write_gint8_to_buffer     (guint8 **buffer,
                                                         guint16 *buffer_size,
                                                         gint8 *in);
void                qmi_utils_write_guint16_to_buffer   (guint8 **buffer,
                                                         guint16 *buffer_size,
                                                         QmiEndian endian,
                                                         guint16 *in);
void                qmi_utils_write_gint16_to_buffer    (guint8 **buffer,
                                                         guint16 *buffer_size,
                                                         QmiEndian endian,
                                                         gint16 *in);
void                qmi_utils_write_guint32_to_buffer   (guint8 **buffer,
                                                         guint16 *buffer_size,
                                                         QmiEndian endian,
                                                         guint32 *in);
void                qmi_utils_write_gint32_to_buffer    (guint8 **buffer,
                                                         guint16 *buffer_size,
                                                         QmiEndian endian,
                                                         gint32 *in);
void                qmi_utils_write_guint64_to_buffer   (guint8 **buffer,
                                                         guint16 *buffer_size,
                                                         QmiEndian endian,
                                                         guint64 *in);
void                qmi_utils_write_gint64_to_buffer    (guint8 **buffer,
                                                         guint16 *buffer_size,
                                                         QmiEndian endian,
                                                         gint64 *in);
void                qmi_utils_write_sized_guint_to_buffer
                                                        (guint8 **buffer,
                                                         guint16 *buffer_size,
                                                         guint n_bytes,
                                                         QmiEndian endian,
                                                         guint64 *in);
void                qmi_utils_write_string_to_buffer    (guint8 **buffer,
                                                         guint16 *buffer_size,
                                                         guint8 length_prefix_size,
                                                         const gchar *in);
void                qmi_utils_write_fixed_size_string_to_buffer
                                                        (guint8 **buffer,
                                                         guint16 *buffer_size,
                                                         guint16 fixed_size,
                                                         const gchar *in);

Description

This section exposes a set of common utilities that may be used to work with the QMI library.

Details

enum QmiEndian

typedef enum {
    QMI_ENDIAN_LITTLE = 0,
    QMI_ENDIAN_BIG    = 1
} QmiEndian;

Type of endianness

QMI_ENDIAN_LITTLE

Little endian.

QMI_ENDIAN_BIG

Big endian.

qmi_utils_get_traces_enabled ()

gboolean            qmi_utils_get_traces_enabled        (void);

Checks whether QMI message traces are currently enabled.

Returns :

TRUE if traces are enabled, FALSE otherwise.

qmi_utils_set_traces_enabled ()

void                qmi_utils_set_traces_enabled        (gboolean enabled);

Sets whether QMI message traces are enabled or disabled.

enabled :

TRUE to enable traces, FALSE to disable them.

qmi_utils_read_guint8_from_buffer ()

void                qmi_utils_read_guint8_from_buffer   (const guint8 **buffer,
                                                         guint16 *buffer_size,
                                                         guint8 *out);

Reads an unsigned byte from the buffer.

The user needs to make sure that at least 1 byte is available in the buffer.

Also note that both buffer and buffer_size get updated after the 1 byte read.

buffer :

a buffer with raw binary data.

buffer_size :

size of buffer.

out :

return location for the read variable.

qmi_utils_read_gint8_from_buffer ()

void                qmi_utils_read_gint8_from_buffer    (const guint8 **buffer,
                                                         guint16 *buffer_size,
                                                         gint8 *out);

Reads a signed byte from the buffer.

The user needs to make sure that at least 1 byte is available in the buffer.

Also note that both buffer and buffer_size get updated after the 1 byte read.

buffer :

a buffer with raw binary data.

buffer_size :

size of buffer.

out :

return location for the read variable.

qmi_utils_read_guint16_from_buffer ()

void                qmi_utils_read_guint16_from_buffer  (const guint8 **buffer,
                                                         guint16 *buffer_size,
                                                         QmiEndian endian,
                                                         guint16 *out);

Reads an unsigned 16-bit integer from the buffer. The number in the buffer is expected to be given in the byte order specificed by endian, and this method takes care of converting the read value to the proper host endianness.

The user needs to make sure that at least 2 bytes are available in the buffer.

Also note that both buffer and buffer_size get updated after the 2 bytes read.

buffer :

a buffer with raw binary data.

buffer_size :

size of buffer.

endian :

endianness of firmware value; swapped to host byte order if necessary

out :

return location for the read variable.

qmi_utils_read_gint16_from_buffer ()

void                qmi_utils_read_gint16_from_buffer   (const guint8 **buffer,
                                                         guint16 *buffer_size,
                                                         QmiEndian endian,
                                                         gint16 *out);

Reads a signed 16-bit integer from the buffer. The number in the buffer is expected to be given in the byte order specified by endian, and this method takes care of converting the read value to the proper host endianness.

The user needs to make sure that at least 2 bytes are available in the buffer.

Also note that both buffer and buffer_size get updated after the 2 bytes read.

buffer :

a buffer with raw binary data.

buffer_size :

size of buffer.

endian :

endianness of firmware value; swapped to host byte order if necessary

out :

return location for the read variable.

qmi_utils_read_guint32_from_buffer ()

void                qmi_utils_read_guint32_from_buffer  (const guint8 **buffer,
                                                         guint16 *buffer_size,
                                                         QmiEndian endian,
                                                         guint32 *out);

Reads an unsigned 32-bit integer from the buffer. The number in the buffer is expected to be given in the byte order specified by endian, and this method takes care of converting the read value to the proper host endianness.

The user needs to make sure that at least 4 bytes are available in the buffer.

Also note that both buffer and buffer_size get updated after the 4 bytes read.

buffer :

a buffer with raw binary data.

buffer_size :

size of buffer.

endian :

endianness of firmware value; swapped to host byte order if necessary

out :

return location for the read variable.

qmi_utils_read_gint32_from_buffer ()

void                qmi_utils_read_gint32_from_buffer   (const guint8 **buffer,
                                                         guint16 *buffer_size,
                                                         QmiEndian endian,
                                                         gint32 *out);

Reads a signed 32-bit integer from the buffer. The number in the buffer is expected to be given in the byte order specified by endian, and this method takes care of converting the read value to the proper host endianness.

The user needs to make sure that at least 4 bytes are available in the buffer.

Also note that both buffer and buffer_size get updated after the 4 bytes read.

buffer :

a buffer with raw binary data.

buffer_size :

size of buffer.

endian :

endianness of firmware value; swapped to host byte order if necessary

out :

return location for the read variable.

qmi_utils_read_guint64_from_buffer ()

void                qmi_utils_read_guint64_from_buffer  (const guint8 **buffer,
                                                         guint16 *buffer_size,
                                                         QmiEndian endian,
                                                         guint64 *out);

Reads an unsigned 64-bit integer from the buffer. The number in the buffer is expected to be given in the byte order specified by endian, and this method takes care of converting the read value to the proper host endianness.

The user needs to make sure that at least 8 bytes are available in the buffer.

Also note that both buffer and buffer_size get updated after the 8 bytes read.

buffer :

a buffer with raw binary data.

buffer_size :

size of buffer.

endian :

endianness of firmware value; swapped to host byte order if necessary

out :

return location for the read variable.

qmi_utils_read_gint64_from_buffer ()

void                qmi_utils_read_gint64_from_buffer   (const guint8 **buffer,
                                                         guint16 *buffer_size,
                                                         QmiEndian endian,
                                                         gint64 *out);

Reads a signed 64-bit integer from the buffer. The number in the buffer is expected to be given in the byte order specified by endian, and this method takes care of converting the read value to the proper host endianness.

The user needs to make sure that at least 8 bytes are available in the buffer.

Also note that both buffer and buffer_size get updated after the 8 bytes read.

buffer :

a buffer with raw binary data.

buffer_size :

size of buffer.

endian :

endianness of firmware value; swapped to host byte order if necessary

out :

return location for the read variable.

qmi_utils_read_sized_guint_from_buffer ()

void                qmi_utils_read_sized_guint_from_buffer
                                                        (const guint8 **buffer,
                                                         guint16 *buffer_size,
                                                         guint n_bytes,
                                                         QmiEndian endian,
                                                         guint64 *out);

Reads a n_bytes-sized unsigned integer from the buffer. The number in the buffer is expected to be given in the byte order specified by endian, and this method takes care of converting the read value to the proper host endianness.

The user needs to make sure that at least n_bytes bytes are available in the buffer.

Also note that both buffer and buffer_size get updated after the n_bytes bytes read.

buffer :

a buffer with raw binary data.

buffer_size :

size of buffer.

n_bytes :

number of bytes to read.

endian :

endianness of firmware value; swapped to host byte order if necessary

out :

return location for the read variable.

qmi_utils_read_string_from_buffer ()

void                qmi_utils_read_string_from_buffer   (const guint8 **buffer,
                                                         guint16 *buffer_size,
                                                         guint8 length_prefix_size,
                                                         guint16 max_size,
                                                         gchar **out);

Reads a string from the buffer.

If length_prefix_size is greater than 0, only the amount of bytes given there will be read. Otherwise, up to buffer_size bytes will be read.

Also note that both buffer and buffer_size get updated after the write.

buffer :

a buffer with raw binary data.

buffer_size :

size of buffer.

length_prefix_size :

size of the length prefix integer in bits.

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

qmi_utils_read_fixed_size_string_from_buffer ()

void                qmi_utils_read_fixed_size_string_from_buffer
                                                        (const guint8 **buffer,
                                                         guint16 *buffer_size,
                                                         guint16 fixed_size,
                                                         gchar *out);

Reads a fixed_size-sized string from the buffer.

Also note that both buffer and buffer_size get updated after the fixed_size bytes read.

buffer :

a buffer with raw binary data.

buffer_size :

size of buffer.

fixed_size :

number of bytes to read.

out :

return location for the read string. The returned value should be freed with g_free().

qmi_utils_write_guint8_to_buffer ()

void                qmi_utils_write_guint8_to_buffer    (guint8 **buffer,
                                                         guint16 *buffer_size,
                                                         guint8 *in);

Writes an unsigned byte into the buffer.

The user needs to make sure that the buffer is at least 1 byte long.

Also note that both buffer and buffer_size get updated after the 1 byte write.

buffer :

a buffer.

buffer_size :

size of buffer.

in :

location of the variable to be written.

qmi_utils_write_gint8_to_buffer ()

void                qmi_utils_write_gint8_to_buffer     (guint8 **buffer,
                                                         guint16 *buffer_size,
                                                         gint8 *in);

Writes a signed byte into the buffer.

The user needs to make sure that the buffer is at least 1 byte long.

Also note that both buffer and buffer_size get updated after the 1 byte write.

buffer :

a buffer.

buffer_size :

size of buffer.

in :

location of the variable to be written.

qmi_utils_write_guint16_to_buffer ()

void                qmi_utils_write_guint16_to_buffer   (guint8 **buffer,
                                                         guint16 *buffer_size,
                                                         QmiEndian endian,
                                                         guint16 *in);

Writes an unsigned 16-bit integer into the buffer. 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 user needs to make sure that the buffer is at least 2 bytes long.

Also note that both buffer and buffer_size get updated after the 2 bytes write.

buffer :

a buffer.

buffer_size :

size of buffer.

endian :

endianness of firmware value; swapped from host byte order if necessary

in :

location of the variable to be written.

qmi_utils_write_gint16_to_buffer ()

void                qmi_utils_write_gint16_to_buffer    (guint8 **buffer,
                                                         guint16 *buffer_size,
                                                         QmiEndian endian,
                                                         gint16 *in);

Writes a signed 16-bit integer into the buffer. 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 user needs to make sure that the buffer is at least 2 bytes long.

Also note that both buffer and buffer_size get updated after the 2 bytes write.

buffer :

a buffer.

buffer_size :

size of buffer.

endian :

endianness of firmware value; swapped from host byte order if necessary

in :

location of the variable to be written.

qmi_utils_write_guint32_to_buffer ()

void                qmi_utils_write_guint32_to_buffer   (guint8 **buffer,
                                                         guint16 *buffer_size,
                                                         QmiEndian endian,
                                                         guint32 *in);

Writes an unsigned 32-bit integer into the buffer. 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 user needs to make sure that the buffer is at least 4 bytes long.

Also note that both buffer and buffer_size get updated after the 4 bytes write.

buffer :

a buffer.

buffer_size :

size of buffer.

endian :

endianness of firmware value; swapped from host byte order if necessary

in :

location of the variable to be written.

qmi_utils_write_gint32_to_buffer ()

void                qmi_utils_write_gint32_to_buffer    (guint8 **buffer,
                                                         guint16 *buffer_size,
                                                         QmiEndian endian,
                                                         gint32 *in);

Writes a signed 32-bit integer into the buffer. 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 user needs to make sure that the buffer is at least 4 bytes long.

Also note that both buffer and buffer_size get updated after the 4 bytes write.

buffer :

a buffer.

buffer_size :

size of buffer.

endian :

endianness of firmware value; swapped from host byte order if necessary

in :

location of the variable to be written.

qmi_utils_write_guint64_to_buffer ()

void                qmi_utils_write_guint64_to_buffer   (guint8 **buffer,
                                                         guint16 *buffer_size,
                                                         QmiEndian endian,
                                                         guint64 *in);

Writes an unsigned 64-bit integer into the buffer. 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 user needs to make sure that the buffer is at least 8 bytes long.

Also note that both buffer and buffer_size get updated after the 8 bytes write.

buffer :

a buffer.

buffer_size :

size of buffer.

endian :

endianness of firmware value; swapped from host byte order if necessary

in :

location of the variable to be written.

qmi_utils_write_gint64_to_buffer ()

void                qmi_utils_write_gint64_to_buffer    (guint8 **buffer,
                                                         guint16 *buffer_size,
                                                         QmiEndian endian,
                                                         gint64 *in);

Writes a signed 64-bit integer into the buffer. 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 user needs to make sure that the buffer is at least 8 bytes long.

Also note that both buffer and buffer_size get updated after the 8 bytes write.

buffer :

a buffer.

buffer_size :

size of buffer.

endian :

endianness of firmware value; swapped from host byte order if necessary

in :

location of the variable to be written.

qmi_utils_write_sized_guint_to_buffer ()

void                qmi_utils_write_sized_guint_to_buffer
                                                        (guint8 **buffer,
                                                         guint16 *buffer_size,
                                                         guint n_bytes,
                                                         QmiEndian endian,
                                                         guint64 *in);

Writes a n_bytes-sized unsigned integer into the buffer. 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 user needs to make sure that the buffer is at least n_bytes bytes long.

Also note that both buffer and buffer_size get updated after the n_bytes bytes write.

buffer :

a buffer.

buffer_size :

size of buffer.

n_bytes :

number of bytes to write.

endian :

endianness of firmware value; swapped from host byte order if necessary

in :

location of the variable to be written.

qmi_utils_write_string_to_buffer ()

void                qmi_utils_write_string_to_buffer    (guint8 **buffer,
                                                         guint16 *buffer_size,
                                                         guint8 length_prefix_size,
                                                         const gchar *in);

Writes a string to the buffer.

If length_prefix_size is greater than 0, a length prefix integer will be included in the write operation.

The user needs to make sure that the buffer has enough space for both the whole string and the length prefix.

Also note that both buffer and buffer_size get updated after the write.

buffer :

a buffer.

buffer_size :

size of buffer.

length_prefix_size :

size of the length prefix integer in bits.

in :

string to write.

qmi_utils_write_fixed_size_string_to_buffer ()

void                qmi_utils_write_fixed_size_string_to_buffer
                                                        (guint8 **buffer,
                                                         guint16 *buffer_size,
                                                         guint16 fixed_size,
                                                         const gchar *in);

Writes a fixed_size-sized string to the buffer, without any length prefix.

The user needs to make sure that the buffer is at least fixed_size bytes long.

Also note that both buffer and buffer_size get updated after the fixed_size bytes write.

buffer :

a buffer.

buffer_size :

size of buffer.

fixed_size :

number of bytes to write.

in :

string to write.