diff options
Diffstat (limited to 'src/libqmi-glib/qmi-utils.h')
| -rw-r--r-- | src/libqmi-glib/qmi-utils.h | 506 |
1 files changed, 478 insertions, 28 deletions
diff --git a/src/libqmi-glib/qmi-utils.h b/src/libqmi-glib/qmi-utils.h index c03bd89..4fd5199 100644 --- a/src/libqmi-glib/qmi-utils.h +++ b/src/libqmi-glib/qmi-utils.h @@ -39,6 +39,8 @@ G_BEGIN_DECLS * @QMI_ENDIAN_BIG: Big endian. * * Type of endianness + * + * Since: 1.0 */ typedef enum { QMI_ENDIAN_LITTLE = 0, @@ -47,111 +49,470 @@ typedef enum { /* Reading/Writing integer variables */ -G_DEPRECATED +/** + * qmi_utils_read_guint8_from_buffer: + * @buffer: a buffer with raw binary data. + * @buffer_size: size of @buffer. + * @out: return location for the read variable. + * + * 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. + * + * Since: 1.0 + * Deprecated: 1.12: Use qmi_message_tlv_read_guint8() instead. + */ +G_DEPRECATED_FOR (qmi_message_tlv_read_guint8) void qmi_utils_read_guint8_from_buffer (const guint8 **buffer, guint16 *buffer_size, guint8 *out); -G_DEPRECATED +/** + * qmi_utils_read_gint8_from_buffer: + * @buffer: a buffer with raw binary data. + * @buffer_size: size of @buffer. + * @out: return location for the read variable. + * + * 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. + * + * Since: 1.0 + * Deprecated: 1.12: Use qmi_message_tlv_read_gint8() instead. + */ +G_DEPRECATED_FOR (qmi_message_tlv_read_gint8) void qmi_utils_read_gint8_from_buffer (const guint8 **buffer, guint16 *buffer_size, gint8 *out); -G_DEPRECATED +/** + * qmi_utils_read_guint16_from_buffer: + * @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. + * + * 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. + * + * Since: 1.0 + * Deprecated: 1.12: Use qmi_message_tlv_read_guint16() instead. + */ +G_DEPRECATED_FOR (qmi_message_tlv_read_guint16) void qmi_utils_read_guint16_from_buffer (const guint8 **buffer, guint16 *buffer_size, QmiEndian endian, guint16 *out); -G_DEPRECATED +/** + * qmi_utils_read_gint16_from_buffer: + * @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. + * + * 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. + * + * Since: 1.0 + * Deprecated: 1.12: Use qmi_message_tlv_read_gint16() instead. + */ +G_DEPRECATED_FOR (qmi_message_tlv_read_gint16) void qmi_utils_read_gint16_from_buffer (const guint8 **buffer, guint16 *buffer_size, QmiEndian endian, gint16 *out); -G_DEPRECATED +/** + * qmi_utils_read_guint32_from_buffer: + * @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. + * + * 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. + * + * Since: 1.0 + * Deprecated: 1.12: Use qmi_message_tlv_read_guint32() instead. + */ +G_DEPRECATED_FOR (qmi_message_tlv_read_guint32) void qmi_utils_read_guint32_from_buffer (const guint8 **buffer, guint16 *buffer_size, QmiEndian endian, guint32 *out); -G_DEPRECATED +/** + * qmi_utils_read_gint32_from_buffer: + * @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. + * + * 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. + * + * Since: 1.0 + * Deprecated: 1.12: Use qmi_message_tlv_read_gint32() instead. + */ +G_DEPRECATED_FOR (qmi_message_tlv_read_gint32) void qmi_utils_read_gint32_from_buffer (const guint8 **buffer, guint16 *buffer_size, QmiEndian endian, gint32 *out); -G_DEPRECATED +/** + * qmi_utils_read_guint64_from_buffer: + * @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. + * + * 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. + * + * Since: 1.0 + * Deprecated: 1.12: Use qmi_message_tlv_read_guint64() instead. + */ +G_DEPRECATED_FOR (qmi_message_tlv_read_guint64) void qmi_utils_read_guint64_from_buffer (const guint8 **buffer, guint16 *buffer_size, QmiEndian endian, guint64 *out); -G_DEPRECATED +/** + * qmi_utils_read_gint64_from_buffer: + * @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. + * + * 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. + * + * Since: 1.0 + * Deprecated: 1.12: Use qmi_message_tlv_read_gint64() instead. + */ +G_DEPRECATED_FOR (qmi_message_tlv_read_gint64) void qmi_utils_read_gint64_from_buffer (const guint8 **buffer, guint16 *buffer_size, QmiEndian endian, gint64 *out); -G_DEPRECATED +/** + * qmi_utils_read_sized_guint_from_buffer: + * @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. + * + * 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. + * + * Since: 1.0 + * Deprecated: 1.12: Use qmi_message_tlv_read_sized_guint() instead. + */ +G_DEPRECATED_FOR (qmi_message_tlv_read_sized_guint) void qmi_utils_read_sized_guint_from_buffer (const guint8 **buffer, guint16 *buffer_size, guint n_bytes, QmiEndian endian, guint64 *out); -G_DEPRECATED +/** + * qmi_utils_read_gfloat_from_buffer: + * @buffer: a buffer with raw binary data. + * @buffer_size: size of @buffer. + * @out: return location for the read variable. + * + * Reads a 32-bit floating-point number from the buffer. + * + * 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. + * + * Since: 1.10 + * Deprecated: 1.12: Use qmi_message_tlv_read_gfloat() instead. + */ +G_DEPRECATED_FOR (qmi_message_tlv_read_gfloat) void qmi_utils_read_gfloat_from_buffer (const guint8 **buffer, guint16 *buffer_size, gfloat *out); -G_DEPRECATED +/** + * qmi_utils_write_guint8_to_buffer: + * @buffer: a buffer. + * @buffer_size: size of @buffer. + * @in: location of the variable to be written. + * + * 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. + * + * Since: 1.0 + * Deprecated: 1.12: Use qmi_message_tlv_write_guint8() instead. + */ +G_DEPRECATED_FOR (qmi_message_tlv_write_guint8) void qmi_utils_write_guint8_to_buffer (guint8 **buffer, guint16 *buffer_size, guint8 *in); -G_DEPRECATED +/** + * qmi_utils_write_gint8_to_buffer: + * @buffer: a buffer. + * @buffer_size: size of @buffer. + * @in: location of the variable to be written. + * + * 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. + * + * Since: 1.0 + * Deprecated: 1.12: Use qmi_message_tlv_write_gint8() instead. + */ +G_DEPRECATED_FOR (qmi_message_tlv_write_gint8) void qmi_utils_write_gint8_to_buffer (guint8 **buffer, guint16 *buffer_size, gint8 *in); -G_DEPRECATED +/** + * qmi_utils_write_guint16_to_buffer: + * @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. + * + * 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. + * + * Since: 1.0 + * Deprecated: 1.12: Use qmi_message_tlv_write_guint16() instead. + */ +G_DEPRECATED_FOR (qmi_message_tlv_write_guint16) void qmi_utils_write_guint16_to_buffer (guint8 **buffer, guint16 *buffer_size, QmiEndian endian, guint16 *in); -G_DEPRECATED -void qmi_utils_write_gint16_to_buffer (guint8 **buffer, - guint16 *buffer_size, - QmiEndian endian, - gint16 *in); +/** + * qmi_utils_write_gint16_to_buffer: + * @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. + * + * 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. + * + * Since: 1.0 + * Deprecated: 1.12: Use qmi_message_tlv_write_gint16() instead. + */ +G_DEPRECATED_FOR (qmi_message_tlv_write_gint16) +void qmi_utils_write_gint16_to_buffer (guint8 **buffer, + guint16 *buffer_size, + QmiEndian endian, + gint16 *in); -G_DEPRECATED +/** + * qmi_utils_write_guint32_to_buffer: + * @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. + * + * 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. + * + * Since: 1.0 + * Deprecated: 1.12: Use qmi_message_tlv_write_guint32() instead. + */ +G_DEPRECATED_FOR (qmi_message_tlv_write_guint32) void qmi_utils_write_guint32_to_buffer (guint8 **buffer, guint16 *buffer_size, QmiEndian endian, guint32 *in); -G_DEPRECATED +/** + * qmi_utils_write_gint32_to_buffer: + * @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. + * + * 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. + * + * Since: 1.0 + * Deprecated: 1.12: Use qmi_message_tlv_write_gint32() instead. + */ +G_DEPRECATED_FOR (qmi_message_tlv_write_gint32) void qmi_utils_write_gint32_to_buffer (guint8 **buffer, guint16 *buffer_size, QmiEndian endian, gint32 *in); -G_DEPRECATED +/** + * qmi_utils_write_guint64_to_buffer: + * @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. + * + * 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. + * + * Since: 1.0 + * Deprecated: 1.12: Use qmi_message_tlv_write_guint64() instead. + */ +G_DEPRECATED_FOR (qmi_message_tlv_write_guint64) void qmi_utils_write_guint64_to_buffer (guint8 **buffer, guint16 *buffer_size, QmiEndian endian, guint64 *in); -G_DEPRECATED +/** + * qmi_utils_write_gint64_to_buffer: + * @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. + * + * 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. + * + * Since: 1.0 + * Deprecated: 1.12: Use qmi_message_tlv_write_gint64() instead. + */ +G_DEPRECATED_FOR (qmi_message_tlv_write_gint64) void qmi_utils_write_gint64_to_buffer (guint8 **buffer, guint16 *buffer_size, QmiEndian endian, gint64 *in); -G_DEPRECATED +/** + * qmi_utils_write_sized_guint_to_buffer: + * @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. + * + * 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. + * + * Since: 1.0 + * Deprecated: 1.12: Use qmi_message_tlv_write_sized_guint() instead. + */ +G_DEPRECATED_FOR (qmi_message_tlv_write_sized_guint) void qmi_utils_write_sized_guint_to_buffer (guint8 **buffer, guint16 *buffer_size, guint n_bytes, @@ -160,34 +521,123 @@ void qmi_utils_write_sized_guint_to_buffer (guint8 **buffer, /* Reading/Writing string variables */ -G_DEPRECATED +/** + * qmi_utils_read_string_from_buffer: + * @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(). + * + * 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. + * + * Since: 1.0 + * Deprecated: 1.12: Use qmi_message_tlv_read_string() instead. + */ +G_DEPRECATED_FOR (qmi_message_tlv_read_string) void qmi_utils_read_string_from_buffer (const guint8 **buffer, guint16 *buffer_size, guint8 length_prefix_size, guint16 max_size, gchar **out); -G_DEPRECATED +/** + * qmi_utils_write_string_to_buffer: + * @buffer: a buffer. + * @buffer_size: size of @buffer. + * @length_prefix_size: size of the length prefix integer in bits. + * @in: string to write. + * + * 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. + * + * Since: 1.0 + * Deprecated: 1.12: Use qmi_message_tlv_write_string() instead. + */ +G_DEPRECATED_FOR (qmi_message_tlv_write_string) void qmi_utils_write_string_to_buffer (guint8 **buffer, guint16 *buffer_size, guint8 length_prefix_size, const gchar *in); -G_DEPRECATED +/** + * qmi_utils_read_fixed_size_string_from_buffer: + * @buffer: a buffer with raw binary data. + * @buffer_size: size of @buffer. + * @fixed_size: number of bytes to read. + * @out: buffer preallocated by the client, with at least @fixed_size bytes. + * + * Reads a @fixed_size-sized string from the buffer into the @out buffer. + * + * Also note that both @buffer and @buffer_size get updated after the + * @fixed_size bytes read. + * + * Since: 1.0 + * Deprecated: 1.12: Use qmi_message_tlv_read_fixed_size_string() instead. + */ +G_DEPRECATED_FOR (qmi_message_tlv_read_fixed_size_string) void qmi_utils_read_fixed_size_string_from_buffer (const guint8 **buffer, guint16 *buffer_size, guint16 fixed_size, gchar *out); -G_DEPRECATED +/** + * qmi_utils_write_fixed_size_string_to_buffer: + * @buffer: a buffer. + * @buffer_size: size of @buffer. + * @fixed_size: number of bytes to write. + * @in: string to write. + * + * 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. + * + * Since: 1.0 + * Deprecated: 1.12: Use qmi_message_tlv_write_string() instead. + */ +G_DEPRECATED_FOR (qmi_message_tlv_write_string) void qmi_utils_write_fixed_size_string_to_buffer (guint8 **buffer, guint16 *buffer_size, guint16 fixed_size, const gchar *in); /* Enabling/Disabling traces */ +/** + * qmi_utils_get_traces_enabled: + * + * Checks whether QMI message traces are currently enabled. + * + * Returns: %TRUE if traces are enabled, %FALSE otherwise. + * + * Since: 1.0 + */ gboolean qmi_utils_get_traces_enabled (void); -void qmi_utils_set_traces_enabled (gboolean enabled); + +/** + * qmi_utils_set_traces_enabled: + * @enabled: %TRUE to enable traces, %FALSE to disable them. + * + * Sets whether QMI message traces are enabled or disabled. + * + * Since: 1.0 + */ +void qmi_utils_set_traces_enabled (gboolean enabled); /* Other private methods */ |