Common utilities: libqmi-glib Reference Manual

## Common utilities Common utilities |

## Functions

gboolean | qmi_utils_get_traces_enabled ()
void | qmi_utils_set_traces_enabled ()
void | qmi_utils_read_guint8_from_buffer ()
void | qmi_utils_read_gint8_from_buffer ()
void | qmi_utils_read_guint16_from_buffer ()
void | qmi_utils_read_gint16_from_buffer ()
void | qmi_utils_read_guint32_from_buffer ()
void | qmi_utils_read_gint32_from_buffer ()
void | qmi_utils_read_guint64_from_buffer ()
void | qmi_utils_read_gint64_from_buffer ()
void | qmi_utils_read_sized_guint_from_buffer ()
void | qmi_utils_read_gfloat_from_buffer ()
void | qmi_utils_read_string_from_buffer ()
void | qmi_utils_read_fixed_size_string_from_buffer ()
void | qmi_utils_write_guint8_to_buffer ()
void | qmi_utils_write_gint8_to_buffer ()
void | qmi_utils_write_guint16_to_buffer ()
void | qmi_utils_write_gint16_to_buffer ()
void | qmi_utils_write_guint32_to_buffer ()
void | qmi_utils_write_gint32_to_buffer ()
void | qmi_utils_write_guint64_to_buffer ()
void | qmi_utils_write_gint64_to_buffer ()
void | qmi_utils_write_sized_guint_to_buffer ()
void | qmi_utils_write_string_to_buffer ()
void | qmi_utils_write_fixed_size_string_to_buffer ()

## Types and Values

enum | QmiEndian

## Description

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

## Functions

### 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.

Since: 1.0

### qmi_utils_set_traces_enabled ()

    void
    qmi_utils_set_traces_enabled (gboolean enabled);

Sets whether QMI message traces are enabled or disabled.

#### Parameters

enabled | `TRUE` to enable traces, `FALSE` to disable them. |

Since: 1.0

### qmi_utils_read_guint8_from_buffer ()

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

`qmi_utils_read_guint8_from_buffer` has been deprecated since version 1.12 and should not be used in newly-written code.

Use `qmi_message_tlv_read_guint8()` instead.

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.

#### Parameters

buffer | a buffer with raw binary data. |
buffer_size | size of `buffer` . |
out | return location for the read variable. |

Since: 1.0

### qmi_utils_read_gint8_from_buffer ()

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

`qmi_utils_read_gint8_from_buffer` has been deprecated since version 1.12 and should not be used in newly-written code.

Use `qmi_message_tlv_read_gint8()` instead.

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.

#### Parameters

buffer | a buffer with raw binary data. |
buffer_size | size of `buffer` . |
out | return location for the read variable. |

Since: 1.0

### qmi_utils_read_guint16_from_buffer ()

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

`qmi_utils_read_guint16_from_buffer` has been deprecated since version 1.12 and should not be used in newly-written code.

Use `qmi_message_tlv_read_guint16()` instead.

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.

#### Parameters

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

Since: 1.0

### qmi_utils_read_gint16_from_buffer ()

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

`qmi_utils_read_gint16_from_buffer` has been deprecated since version 1.12 and should not be used in newly-written code.

Use `qmi_message_tlv_read_gint16()` instead.

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.

#### Parameters

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

Since: 1.0

### qmi_utils_read_guint32_from_buffer ()

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

`qmi_utils_read_guint32_from_buffer` has been deprecated since version 1.12 and should not be used in newly-written code.

Use `qmi_message_tlv_read_guint32()` instead.

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.

#### Parameters

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

Since: 1.0

### qmi_utils_read_gint32_from_buffer ()

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

`qmi_utils_read_gint32_from_buffer` has been deprecated since version 1.12 and should not be used in newly-written code.

Use `qmi_message_tlv_read_gint32()` instead.

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.

#### Parameters

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

Since: 1.0

### qmi_utils_read_guint64_from_buffer ()

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

`qmi_utils_read_guint64_from_buffer` has been deprecated since version 1.12 and should not be used in newly-written code.

Use `qmi_message_tlv_read_guint64()` instead.

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.

#### Parameters

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

Since: 1.0

### qmi_utils_read_gint64_from_buffer ()

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

`qmi_utils_read_gint64_from_buffer` has been deprecated since version 1.12 and should not be used in newly-written code.

Use `qmi_message_tlv_read_gint64()` instead.

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.

#### Parameters

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

Since: 1.0

### 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);

`qmi_utils_read_sized_guint_from_buffer` has been deprecated since version 1.12 and should not be used in newly-written code.

Use `qmi_message_tlv_read_sized_guint()` instead.

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.

#### Parameters

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

Since: 1.0

### qmi_utils_read_gfloat_from_buffer ()

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

`qmi_utils_read_gfloat_from_buffer` has been deprecated since version 1.12 and should not be used in newly-written code.

Use `qmi_message_tlv_read_gfloat()` instead.

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.

#### Parameters

buffer | a buffer with raw binary data. |
buffer_size | size of `buffer` . |
out | return location for the read variable. |

Since: 1.10

### 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);

`qmi_utils_read_string_from_buffer` has been deprecated since version 1.12 and should not be used in newly-written code.

Use `qmi_message_tlv_read_string()` instead.

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.

#### Parameters

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

Since: 1.0

### 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);

`qmi_utils_read_fixed_size_string_from_buffer` has been deprecated since version 1.12 and should not be used in newly-written code.

Use `qmi_message_tlv_read_fixed_size_string()` instead.

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.

#### Parameters

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

Since: 1.0

### qmi_utils_write_guint8_to_buffer ()

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

`qmi_utils_write_guint8_to_buffer` has been deprecated since version 1.12 and should not be used in newly-written code.

Use `qmi_message_tlv_write_guint8()` instead.

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.

#### Parameters

buffer | a buffer. |
buffer_size | size of `buffer` . |
in | location of the variable to be written. |

Since: 1.0

### qmi_utils_write_gint8_to_buffer ()

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

`qmi_utils_write_gint8_to_buffer` has been deprecated since version 1.12 and should not be used in newly-written code.

Use `qmi_message_tlv_write_gint8()` instead.

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.

#### Parameters

buffer | a buffer. |
buffer_size | size of `buffer` . |
in | location of the variable to be written. |

Since: 1.0

### qmi_utils_write_guint16_to_buffer ()

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

`qmi_utils_write_guint16_to_buffer` has been deprecated since version 1.12 and should not be used in newly-written code.

Use `qmi_message_tlv_write_guint16()` instead.

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.

#### Parameters

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

Since: 1.0

### qmi_utils_write_gint16_to_buffer ()

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

`qmi_utils_write_gint16_to_buffer` has been deprecated since version 1.12 and should not be used in newly-written code.

Use `qmi_message_tlv_write_gint16()` instead.

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.

#### Parameters

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

Since: 1.0

### qmi_utils_write_guint32_to_buffer ()

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

`qmi_utils_write_guint32_to_buffer` has been deprecated since version 1.12 and should not be used in newly-written code.

Use `qmi_message_tlv_write_guint32()` instead.

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.

#### Parameters

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

Since: 1.0

### qmi_utils_write_gint32_to_buffer ()

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

`qmi_utils_write_gint32_to_buffer` has been deprecated since version 1.12 and should not be used in newly-written code.

Use `qmi_message_tlv_write_gint32()` instead.

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.

#### Parameters

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

Since: 1.0

### qmi_utils_write_guint64_to_buffer ()

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

`qmi_utils_write_guint64_to_buffer` has been deprecated since version 1.12 and should not be used in newly-written code.

Use `qmi_message_tlv_write_guint64()` instead.

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.

#### Parameters

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

Since: 1.0

### qmi_utils_write_gint64_to_buffer ()

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

`qmi_utils_write_gint64_to_buffer` has been deprecated since version 1.12 and should not be used in newly-written code.

Use `qmi_message_tlv_write_gint64()` instead.

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.

#### Parameters

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

Since: 1.0

### 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);

`qmi_utils_write_sized_guint_to_buffer` has been deprecated since version 1.12 and should not be used in newly-written code.

Use `qmi_message_tlv_write_sized_guint()` instead.

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.

#### Parameters

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

Since: 1.0

### 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);

`qmi_utils_write_string_to_buffer` has been deprecated since version 1.12 and should not be used in newly-written code.

Use `qmi_message_tlv_write_string()` instead.

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.

#### Parameters

buffer | a buffer. |
buffer_size | size of `buffer` . |
length_prefix_size | size of the length prefix integer in bits. |
in | string to write. |

Since: 1.0

### 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);

`qmi_utils_write_fixed_size_string_to_buffer` has been deprecated since version 1.12 and should not be used in newly-written code.

Use `qmi_message_tlv_write_string()` instead.

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.

#### Parameters

buffer | a buffer. |
buffer_size | size of `buffer` . |
fixed_size | number of bytes to write. |
in | string to write. |

Since: 1.0

## Types and Values

### enum QmiEndian

Type of endianness

#### Members

QMI_ENDIAN_LITTLE | Little endian. |
QMI_ENDIAN_BIG | Big endian. |

Since: 1.0