diff options
| -rw-r--r-- | src/libqmi-glib/qmi-utils.c | 374 | ||||
| -rw-r--r-- | src/libqmi-glib/qmi-utils.h | 506 |
2 files changed, 478 insertions, 402 deletions
diff --git a/src/libqmi-glib/qmi-utils.c b/src/libqmi-glib/qmi-utils.c index 813c56d..29e5f22 100644 --- a/src/libqmi-glib/qmi-utils.c +++ b/src/libqmi-glib/qmi-utils.c @@ -143,20 +143,6 @@ print_read_bytes_trace (const gchar *type, #define print_read_bytes_trace(...) #endif -/** - * 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. - */ void qmi_utils_read_guint8_from_buffer (const guint8 **buffer, guint16 *buffer_size, @@ -175,20 +161,6 @@ qmi_utils_read_guint8_from_buffer (const guint8 **buffer, *buffer_size = (*buffer_size) - 1; } -/** - * 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. - */ void qmi_utils_read_gint8_from_buffer (const guint8 **buffer, guint16 *buffer_size, @@ -207,23 +179,6 @@ qmi_utils_read_gint8_from_buffer (const guint8 **buffer, *buffer_size = (*buffer_size) - 1; } -/** - * 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. - */ void qmi_utils_read_guint16_from_buffer (const guint8 **buffer, guint16 *buffer_size, @@ -247,23 +202,6 @@ qmi_utils_read_guint16_from_buffer (const guint8 **buffer, *buffer_size = (*buffer_size) - 2; } -/** - * 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. - */ void qmi_utils_read_gint16_from_buffer (const guint8 **buffer, guint16 *buffer_size, @@ -287,23 +225,6 @@ qmi_utils_read_gint16_from_buffer (const guint8 **buffer, *buffer_size = (*buffer_size) - 2; } -/** - * 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. - */ void qmi_utils_read_guint32_from_buffer (const guint8 **buffer, guint16 *buffer_size, @@ -327,23 +248,6 @@ qmi_utils_read_guint32_from_buffer (const guint8 **buffer, *buffer_size = (*buffer_size) - 4; } -/** - * 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. - */ void qmi_utils_read_gint32_from_buffer (const guint8 **buffer, guint16 *buffer_size, @@ -367,23 +271,6 @@ qmi_utils_read_gint32_from_buffer (const guint8 **buffer, *buffer_size = (*buffer_size) - 4; } -/** - * 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. - */ void qmi_utils_read_guint64_from_buffer (const guint8 **buffer, guint16 *buffer_size, @@ -407,23 +294,6 @@ qmi_utils_read_guint64_from_buffer (const guint8 **buffer, *buffer_size = (*buffer_size) - 8; } -/** - * 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. - */ void qmi_utils_read_gint64_from_buffer (const guint8 **buffer, guint16 *buffer_size, @@ -447,25 +317,6 @@ qmi_utils_read_gint64_from_buffer (const guint8 **buffer, *buffer_size = (*buffer_size) - 8; } -/** - * 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. - */ void qmi_utils_read_sized_guint_from_buffer (const guint8 **buffer, guint16 *buffer_size, @@ -500,20 +351,6 @@ qmi_utils_read_sized_guint_from_buffer (const guint8 **buffer, *buffer_size = (*buffer_size) - n_bytes; } -/** - * 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. - */ void qmi_utils_read_gfloat_from_buffer (const guint8 **buffer, guint16 *buffer_size, @@ -533,19 +370,6 @@ qmi_utils_read_gfloat_from_buffer (const guint8 **buffer, *buffer_size = (*buffer_size) - 4; } -/** - * 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. - */ void qmi_utils_write_guint8_to_buffer (guint8 **buffer, guint16 *buffer_size, @@ -562,19 +386,6 @@ qmi_utils_write_guint8_to_buffer (guint8 **buffer, *buffer_size = (*buffer_size) - 1; } -/** - * 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. - */ void qmi_utils_write_gint8_to_buffer (guint8 **buffer, guint16 *buffer_size, @@ -591,22 +402,6 @@ qmi_utils_write_gint8_to_buffer (guint8 **buffer, *buffer_size = (*buffer_size) - 1; } -/** - * 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. - */ void qmi_utils_write_guint16_to_buffer (guint8 **buffer, guint16 *buffer_size, @@ -630,22 +425,6 @@ qmi_utils_write_guint16_to_buffer (guint8 **buffer, *buffer_size = (*buffer_size) - 2; } -/** - * 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. - */ void qmi_utils_write_gint16_to_buffer (guint8 **buffer, guint16 *buffer_size, @@ -669,22 +448,6 @@ qmi_utils_write_gint16_to_buffer (guint8 **buffer, *buffer_size = (*buffer_size) - 2; } -/** - * 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. - */ void qmi_utils_write_guint32_to_buffer (guint8 **buffer, guint16 *buffer_size, @@ -708,22 +471,6 @@ qmi_utils_write_guint32_to_buffer (guint8 **buffer, *buffer_size = (*buffer_size) - 4; } -/** - * 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. - */ void qmi_utils_write_gint32_to_buffer (guint8 **buffer, guint16 *buffer_size, @@ -747,22 +494,6 @@ qmi_utils_write_gint32_to_buffer (guint8 **buffer, *buffer_size = (*buffer_size) - 4; } -/** - * 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. - */ void qmi_utils_write_guint64_to_buffer (guint8 **buffer, guint16 *buffer_size, @@ -786,22 +517,6 @@ qmi_utils_write_guint64_to_buffer (guint8 **buffer, *buffer_size = (*buffer_size) - 8; } -/** - * 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. - */ void qmi_utils_write_gint64_to_buffer (guint8 **buffer, guint16 *buffer_size, @@ -825,23 +540,6 @@ qmi_utils_write_gint64_to_buffer (guint8 **buffer, *buffer_size = (*buffer_size) - 8; } -/** - * 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. - */ void qmi_utils_write_sized_guint_to_buffer (guint8 **buffer, guint16 *buffer_size, @@ -878,21 +576,6 @@ qmi_utils_write_sized_guint_to_buffer (guint8 **buffer, *buffer_size = (*buffer_size) - n_bytes; } -/** - * 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. - */ void qmi_utils_read_string_from_buffer (const guint8 **buffer, guint16 *buffer_size, @@ -949,18 +632,6 @@ qmi_utils_read_string_from_buffer (const guint8 **buffer, *buffer_size = (*buffer_size) - string_length; } -/** - * 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. - */ void qmi_utils_read_fixed_size_string_from_buffer (const guint8 **buffer, guint16 *buffer_size, @@ -978,23 +649,6 @@ qmi_utils_read_fixed_size_string_from_buffer (const guint8 **buffer, *buffer_size = (*buffer_size) - fixed_size; } -/** - * 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. - */ void qmi_utils_write_string_to_buffer (guint8 **buffer, guint16 *buffer_size, @@ -1047,21 +701,6 @@ qmi_utils_write_string_to_buffer (guint8 **buffer, *buffer_size = (*buffer_size) - len; } -/** - * 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. - */ void qmi_utils_write_fixed_size_string_to_buffer (guint8 **buffer, guint16 *buffer_size, @@ -1118,25 +757,12 @@ __qmi_utils_get_driver (const gchar *cdc_wdm_path) static volatile gint __traces_enabled = FALSE; -/** - * qmi_utils_get_traces_enabled: - * - * Checks whether QMI message traces are currently enabled. - * - * Returns: %TRUE if traces are enabled, %FALSE otherwise. - */ gboolean qmi_utils_get_traces_enabled (void) { return (gboolean) g_atomic_int_get (&__traces_enabled); } -/** - * qmi_utils_set_traces_enabled: - * @enabled: %TRUE to enable traces, %FALSE to disable them. - * - * Sets whether QMI message traces are enabled or disabled. - */ void qmi_utils_set_traces_enabled (gboolean enabled) { 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 */ |