Debian Codegraph @

src/libqmi-glib/qmi-message.h

raw
1 /* -*- Mode: C; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
2
3 /*
4 * Copyright (c) 2012 The Chromium OS Authors. All rights reserved.
5 * Use of this source code is governed by a BSD-style license that can be
6 * found in the LICENSE file.
7 */
8
9 /*
10 * libqmi-glib -- GLib/GIO based library to control QMI devices
11 *
12 * This library is free software; you can redistribute it and/or
13 * modify it under the terms of the GNU Lesser General Public
14 * License as published by the Free Software Foundation; either
15 * version 2 of the License, or (at your option) any later version.
16 *
17 * This library is distributed in the hope that it will be useful,
18 * but WITHOUT ANY WARRANTY; without even the implied warranty of
19 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
20 * Lesser General Public License for more details.
21 *
22 * You should have received a copy of the GNU Lesser General Public
23 * License along with this library; if not, write to the
24 * Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
25 * Boston, MA 02110-1301 USA.
26 *
27 * Copyright (C) 2012-2017 Aleksander Morgado <[email protected]>
28 */
29
30 #ifndef _LIBQMI_GLIB_QMI_MESSAGE_H_
31 #define _LIBQMI_GLIB_QMI_MESSAGE_H_
32
33 #if !defined (__LIBQMI_GLIB_H_INSIDE__) && !defined (LIBQMI_GLIB_COMPILATION)
34 #error "Only <libqmi-glib.h> can be included directly."
35 #endif
36
37 #include <glib.h>
38
39 #include "qmi-utils.h"
40 #include "qmi-enums.h"
41 #include "qmi-errors.h"
42 #include "qmi-message-context.h"
43
44 G_BEGIN_DECLS
45
46 /**
47 * SECTION:qmi-message
48 * @short_description: Generic QMI message handling routines
49 *
50 * #QmiMessage is a generic type representing a QMI message of any kind
51 * (request, response, indication) or service (including #QMI_SERVICE_CTL).
52 *
53 * This set of generic routines help in handling these message types, and
54 * allow creating any kind of message with any kind of TLV.
55 */
56
57 /**
58 * QMI_MESSAGE_QMUX_MARKER:
59 *
60 * First byte of every QMI QMUX message.
61 *
62 * Since: 1.0
63 */
64 #define QMI_MESSAGE_QMUX_MARKER (guint8) 0x01
65
66 /**
67 * QMI_MESSAGE_QRTR_MARKER:
68 *
69 * Fake header added by libqmi to re-use existing QMUX message parsers for QRTR messages.
70 * QRTR QMI services with a service ID > 0xFF use this fake header where the service ID
71 * is set to 16 bits instead of 8 bits. This header has no purpose outside of libqmi
72 * and is never send to the actual device implementing these QMI services.
73 *
74 * Since: 1.34
75 */
76 #define QMI_MESSAGE_QRTR_MARKER (guint8) 0x02
77
78 /**
79 * QmiMessage:
80 *
81 * An opaque type representing a QMI message.
82 *
83 * Since: 1.0
84 */
85 typedef GByteArray QmiMessage;
86
87 /*****************************************************************************/
88 /* QMI Message life cycle */
89
90 /**
91 * qmi_message_new:
92 * @service: a #QmiService
93 * @client_id: client ID of the originating control point.
94 * @transaction_id: transaction ID.
95 * @message_id: message ID.
96 *
97 * Create a new #QmiMessage with the specified parameters.
98 *
99 * Note that @transaction_id must be less than #G_MAXUINT8 if @service is
100 * #QMI_SERVICE_CTL.
101 *
102 * Returns: (transfer full): a newly created #QmiMessage. The returned value should be freed with qmi_message_unref().
103 *
104 * Since: 1.0
105 */
106 QmiMessage *qmi_message_new (QmiService service,
107 guint8 client_id,
108 guint16 transaction_id,
109 guint16 message_id);
110
111 /**
112 * qmi_message_new_from_raw:
113 * @raw: (inout): raw data buffer.
114 * @error: return location for error or %NULL.
115 *
116 * Create a new #QmiMessage from the given raw data buffer.
117 *
118 * Whenever a complete QMI message is read, its raw data gets removed from the @raw buffer.
119 *
120 * Returns: (transfer full): a newly created #QmiMessage, which should be freed with qmi_message_unref(). If @raw doesn't contain a complete QMI message %NULL is returned. If there is a complete QMI message but it appears not to be valid, %NULL is returned and @error is set.
121 *
122 * Since: 1.0
123 */
124 QmiMessage *qmi_message_new_from_raw (GByteArray *raw,
125 GError **error);
126
127 /**
128 * qmi_message_new_from_data:
129 * @service: a #QmiService
130 * @client_id: client ID of the originating control point.
131 * @qmi_data: (inout): data buffer containing only the QMI part of the message.
132 * @error: return location for error or %NULL.
133 *
134 * Create a new #QmiMessage for the given @service and @client_id and including the given QMI data buffer.
135 *
136 * Whenever a complete QMI message is read, its data gets removed from the @qmi_data buffer.
137 *
138 * This method should be used instead of qmi_message_new_from_raw() if the input data doesn't have QMUX headers.
139 *
140 * Returns: (transfer full): a newly created #QmiMessage, which should be freed with qmi_message_unref(). If @qmi_data doesn't contain a complete QMI data payload %NULL is returned. If there is a complete QMI data payload but it appears not to be valid, %NULL is returned and @error is set.
141 *
142 * Since: 1.24
143 */
144 QmiMessage *qmi_message_new_from_data (QmiService service,
145 guint8 client_id,
146 GByteArray *qmi_data,
147 GError **error);
148
149 /**
150 * qmi_message_response_new:
151 * @request: a request #QmiMessage.
152 * @error: a #QmiProtocolError to set in the result TLV.
153 *
154 * Create a new response #QmiMessage for the specified @request.
155 *
156 * Returns: (transfer full): a newly created #QmiMessage. The returned value should be freed with qmi_message_unref().
157 *
158 * Since: 1.8
159 */
160 QmiMessage *qmi_message_response_new (QmiMessage *request,
161 QmiProtocolError error);
162
163 /**
164 * qmi_message_ref:
165 * @self: a #QmiMessage.
166 *
167 * Atomically increments the reference count of @self by one.
168 *
169 * Returns: (transfer full): the new reference to @self.
170 *
171 * Since: 1.0
172 */
173 QmiMessage *qmi_message_ref (QmiMessage *self);
174
175 /**
176 * qmi_message_unref:
177 * @self: a #QmiMessage.
178 *
179 * Atomically decrements the reference count of @self by one.
180 * If the reference count drops to 0, @self is completely disposed.
181 *
182 * Since: 1.0
183 */
184 void qmi_message_unref (QmiMessage *self);
185 G_DEFINE_AUTOPTR_CLEANUP_FUNC (QmiMessage, qmi_message_unref)
186
187 /*****************************************************************************/
188 /* QMI Message content getters */
189
190 /**
191 * qmi_message_is_request:
192 * @self: a #QmiMessage.
193 *
194 * Checks whether the given #QmiMessage is a request.
195 *
196 * Returns: %TRUE if @self is a request message, %FALSE otherwise.
197 *
198 * Since: 1.8
199 */
200 gboolean qmi_message_is_request (QmiMessage *self);
201
202 /**
203 * qmi_message_is_response:
204 * @self: a #QmiMessage.
205 *
206 * Checks whether the given #QmiMessage is a response.
207 *
208 * Returns: %TRUE if @self is a response message, %FALSE otherwise.
209 *
210 * Since: 1.0
211 */
212 gboolean qmi_message_is_response (QmiMessage *self);
213
214 /**
215 * qmi_message_is_indication:
216 * @self: a #QmiMessage.
217 *
218 * Checks whether the given #QmiMessage is an indication.
219 *
220 * Returns: %TRUE if @self is an indication message, %FALSE otherwise.
221 *
222 * Since: 1.0
223 */
224 gboolean qmi_message_is_indication (QmiMessage *self);
225
226 /**
227 * qmi_message_get_service:
228 * @self: a #QmiMessage.
229 *
230 * Gets the service corresponding to the given #QmiMessage.
231 *
232 * Returns: a #QmiService.
233 *
234 * Since: 1.0
235 */
236 QmiService qmi_message_get_service (QmiMessage *self);
237
238 /**
239 * qmi_message_get_client_id:
240 * @self: a #QmiMessage.
241 *
242 * Gets the client ID of the message.
243 *
244 * Returns: the client ID.
245 *
246 * Since: 1.0
247 */
248 guint8 qmi_message_get_client_id (QmiMessage *self);
249
250 /**
251 * qmi_message_get_transaction_id:
252 * @self: a #QmiMessage.
253 *
254 * Gets the transaction ID of the message.
255 *
256 * Returns: the transaction ID.
257 *
258 * Since: 1.0
259 */
260 guint16 qmi_message_get_transaction_id (QmiMessage *self);
261
262 /**
263 * qmi_message_get_message_id:
264 * @self: a #QmiMessage.
265 *
266 * Gets the ID of the message.
267 *
268 * Returns: the ID.
269 *
270 * Since: 1.0
271 */
272 guint16 qmi_message_get_message_id (QmiMessage *self);
273
274 /**
275 * qmi_message_get_length:
276 * @self: a #QmiMessage.
277 *
278 * Gets the length of the raw data corresponding to the given #QmiMessage.
279 *
280 * Returns: the length of the raw data.
281 *
282 * Since: 1.0
283 */
284 gsize qmi_message_get_length (QmiMessage *self);
285
286 /**
287 * qmi_message_get_raw:
288 * @self: a #QmiMessage.
289 * @length: (out): return location for the size of the output buffer.
290 * @error: return location for error or %NULL.
291 *
292 * Gets the raw data buffer of the #QmiMessage.
293 *
294 * Returns: (transfer none): The raw data buffer, or %NULL if @error is set.
295 *
296 * Since: 1.0
297 */
298 const guint8 *qmi_message_get_raw (QmiMessage *self,
299 gsize *length,
300 GError **error);
301
302
303 /**
304 * qmi_message_get_data:
305 * @self: a #QmiMessage.
306 * @length: (out): return location for the size of the output buffer.
307 * @error: return location for error or %NULL.
308 *
309 * Gets the data buffer of the #QmiMessage without the QMUX header.
310 *
311 * Returns: (transfer none): The raw QMI buffer, or %NULL if @error is set.
312 *
313 * Since: 1.24
314 */
315 const guint8 *qmi_message_get_data (QmiMessage *self,
316 gsize *length,
317 GError **error);
318
319 /**
320 * qmi_message_get_marker:
321 * @self: a #QmiMessage.
322 *
323 * Gets the marker of the #QmiMessage.
324 *
325 * Returns: The message marker.
326 *
327 * Since: 1.34
328 */
329 guint8 qmi_message_get_marker (QmiMessage *self);
330
331 /*****************************************************************************/
332 /* TLV builder & writer */
333
334 /**
335 * qmi_message_tlv_write_init:
336 * @self: a #QmiMessage.
337 * @type: specific ID of the TLV to add.
338 * @error: return location for error or %NULL.
339 *
340 * Starts building a new TLV in the #QmiMessage.
341 *
342 * In order to finish adding the TLV, qmi_message_tlv_write_complete() needs to be
343 * called.
344 *
345 * If any error happens adding fields on the TLV, the previous state can be
346 * recovered using qmi_message_tlv_write_reset().
347 *
348 * Returns: the offset where the TLV was started to be added, or 0 if an error happens.
349 *
350 * Since: 1.12
351 */
352 gsize qmi_message_tlv_write_init (QmiMessage *self,
353 guint8 type,
354 GError **error);
355
356 /**
357 * qmi_message_tlv_write_reset:
358 * @self: a #QmiMessage.
359 * @tlv_offset: offset that was returned by qmi_message_tlv_write_init().
360 *
361 * Removes the TLV being currently added.
362 *
363 * Since: 1.12
364 */
365 void qmi_message_tlv_write_reset (QmiMessage *self,
366 gsize tlv_offset);
367
368 /**
369 * qmi_message_tlv_write_complete:
370 * @self: a #QmiMessage.
371 * @tlv_offset: offset that was returned by qmi_message_tlv_write_init().
372 * @error: return location for error or %NULL.
373 *
374 * Completes building a TLV in the #QmiMessage.
375 *
376 * In case of error the TLV will be reseted; i.e. there is no need to explicitly
377 * call qmi_message_tlv_write_reset().
378 *
379 * Returns: %TRUE if the TLV is successfully completed, otherwise %FALSE is returned and @error is set.
380 *
381 * Since: 1.12
382 */
383 gboolean qmi_message_tlv_write_complete (QmiMessage *self,
384 gsize tlv_offset,
385 GError **error);
386
387 /**
388 * qmi_message_tlv_write_guint8:
389 * @self: a #QmiMessage.
390 * @in: a #guint8.
391 * @error: return location for error or %NULL.
392 *
393 * Appends an unsigned byte to the TLV being built.
394 *
395 * Returns: %TRUE if the variable is successfully added, otherwise %FALSE is returned and @error is set.
396 *
397 * Since: 1.12
398 */
399 gboolean qmi_message_tlv_write_guint8 (QmiMessage *self,
400 guint8 in,
401 GError **error);
402
403 /**
404 * qmi_message_tlv_write_gint8:
405 * @self: a #QmiMessage.
406 * @in: a #gint8.
407 * @error: return location for error or %NULL.
408 *
409 * Appends a signed byte variable to the TLV being built.
410 *
411 * Returns: %TRUE if the variable is successfully added, otherwise %FALSE is returned and @error is set.
412 *
413 * Since: 1.12
414 */
415 gboolean qmi_message_tlv_write_gint8 (QmiMessage *self,
416 gint8 in,
417 GError **error);
418
419 /**
420 * qmi_message_tlv_write_guint16:
421 * @self: a #QmiMessage.
422 * @endian: target endianness, swapped from host byte order if necessary.
423 * @in: a #guint16 in host byte order.
424 * @error: return location for error or %NULL.
425 *
426 * Appends an unsigned 16-bit integer to the TLV being built. The number to be
427 * written is expected to be given in host endianness, and this method takes
428 * care of converting the value written to the byte order specified by @endian.
429 *
430 * Returns: %TRUE if the variable is successfully added, otherwise %FALSE is returned and @error is set.
431 *
432 * Since: 1.12
433 */
434 gboolean qmi_message_tlv_write_guint16 (QmiMessage *self,
435 QmiEndian endian,
436 guint16 in,
437 GError **error);
438
439 /**
440 * qmi_message_tlv_write_gint16:
441 * @self: a #QmiMessage.
442 * @endian: target endianness, swapped from host byte order if necessary.
443 * @in: a #gint16 in host byte order.
444 * @error: return location for error or %NULL.
445 *
446 * Appends a signed 16-bit integer to the TLV being built. The number to be
447 * written is expected to be given in host endianness, and this method takes
448 * care of converting the value written to the byte order specified by @endian.
449 *
450 * Returns: %TRUE if the variable is successfully added, otherwise %FALSE is returned and @error is set.
451 *
452 * Since: 1.12
453 */
454 gboolean qmi_message_tlv_write_gint16 (QmiMessage *self,
455 QmiEndian endian,
456 gint16 in,
457 GError **error);
458
459 /**
460 * qmi_message_tlv_write_guint32:
461 * @self: a #QmiMessage.
462 * @endian: target endianness, swapped from host byte order if necessary.
463 * @in: a #guint32 in host byte order.
464 * @error: return location for error or %NULL.
465 *
466 * Appends an unsigned 32-bit integer to the TLV being built. The number to be
467 * written is expected to be given in host endianness, and this method takes
468 * care of converting the value written to the byte order specified by @endian.
469 *
470 * Returns: %TRUE if the variable is successfully added, otherwise %FALSE is returned and @error is set.
471 *
472 * Since: 1.12
473 */
474 gboolean qmi_message_tlv_write_guint32 (QmiMessage *self,
475 QmiEndian endian,
476 guint32 in,
477 GError **error);
478
479 /**
480 * qmi_message_tlv_write_gint32:
481 * @self: a #QmiMessage.
482 * @endian: target endianness, swapped from host byte order if necessary.
483 * @in: a #gint32 in host byte order.
484 * @error: return location for error or %NULL.
485 *
486 * Appends a signed 32-bit integer to the TLV being built. The number to be
487 * written is expected to be given in host endianness, and this method takes
488 * care of converting the value written to the byte order specified by @endian.
489 *
490 * Returns: %TRUE if the variable is successfully added, otherwise %FALSE is returned and @error is set.
491 *
492 * Since: 1.12
493 */
494 gboolean qmi_message_tlv_write_gint32 (QmiMessage *self,
495 QmiEndian endian,
496 gint32 in,
497 GError **error);
498
499 /**
500 * qmi_message_tlv_write_guint64:
501 * @self: a #QmiMessage.
502 * @endian: target endianness, swapped from host byte order if necessary.
503 * @in: a #guint64 in host byte order.
504 * @error: return location for error or %NULL.
505 *
506 * Appends an unsigned 64-bit integer to the TLV being built. The number to be
507 * written is expected to be given in host endianness, and this method takes
508 * care of converting the value written to the byte order specified by @endian.
509 *
510 * Returns: %TRUE if the variable is successfully added, otherwise %FALSE is returned and @error is set.
511 *
512 * Since: 1.12
513 */
514 gboolean qmi_message_tlv_write_guint64 (QmiMessage *self,
515 QmiEndian endian,
516 guint64 in,
517 GError **error);
518
519 /**
520 * qmi_message_tlv_write_gint64:
521 * @self: a #QmiMessage.
522 * @endian: target endianness, swapped from host byte order if necessary.
523 * @in: a #gint64 in host byte order.
524 * @error: return location for error or %NULL.
525 *
526 * Appends a signed 32-bit integer to the TLV being built. The number to be
527 * written is expected to be given in host endianness, and this method takes
528 * care of converting the value written to the byte order specified by @endian.
529 *
530 * Returns: %TRUE if the variable is successfully added, otherwise %FALSE is returned and @error is set.
531 *
532 * Since: 1.12
533 */
534 gboolean qmi_message_tlv_write_gint64 (QmiMessage *self,
535 QmiEndian endian,
536 gint64 in,
537 GError **error);
538
539 /**
540 * qmi_message_tlv_write_sized_guint:
541 * @self: a #QmiMessage.
542 * @n_bytes: number of bytes to write.
543 * @endian: target endianness, swapped from host byte order if necessary.
544 * @in: a #guint64 in host byte order.
545 * @error: return location for error or %NULL.
546 *
547 * Appends a @n_bytes-sized unsigned integer to the TLV being built. The number
548 * to be written is expected to be given in host endianness, and this method
549 * takes care of converting the value written to the byte order specified by
550 * @endian.
551 *
552 * The value of @n_bytes can be any between 1 and 8.
553 *
554 * Returns: %TRUE if the variable is successfully added, otherwise %FALSE is returned and @error is set.
555 *
556 * Since: 1.12
557 */
558 gboolean qmi_message_tlv_write_sized_guint (QmiMessage *self,
559 guint n_bytes,
560 QmiEndian endian,
561 guint64 in,
562 GError **error);
563
564 /**
565 * qmi_message_tlv_write_gfloat:
566 * @self: a #QmiMessage.
567 * @endian: target endianness, swapped from host byte order if necessary.
568 * @in: a #gfloat in host byte order.
569 * @error: return location for error or %NULL.
570 *
571 * Appends a float to the TLV being built. The number to be
572 * written is expected to be given in host endianness, and this method takes
573 * care of converting the value written to the byte order specified by @endian.
574 *
575 * Returns: %TRUE if the variable is successfully added, otherwise %FALSE is returned and @error is set.
576 *
577 * Since: 1.37
578 */
579 gboolean qmi_message_tlv_write_gfloat (QmiMessage *self,
580 QmiEndian endian,
581 gfloat in,
582 GError **error);
583
584
585 /**
586 * qmi_message_tlv_write_gdouble:
587 * @self: a #QmiMessage.
588 * @endian: target endianness, swapped from host byte order if necessary.
589 * @in: a #gdouble in host byte order.
590 * @error: return location for error or %NULL.
591 *
592 * Appends a double to the TLV being built. The number to be
593 * written is expected to be given in host endianness, and this method takes
594 * care of converting the value written to the byte order specified by @endian.
595 *
596 * Returns: %TRUE if the variable is successfully added, otherwise %FALSE is returned and @error is set.
597 *
598 * Since: 1.37
599 */
600 gboolean qmi_message_tlv_write_gdouble (QmiMessage *self,
601 QmiEndian endian,
602 gdouble in,
603 GError **error);
604
605 /**
606 * qmi_message_tlv_write_string:
607 * @self: a #QmiMessage.
608 * @n_size_prefix_bytes: number of bytes to use in the size prefix.
609 * @in: string to write.
610 * @in_length: length of @in, or -1 if @in is NUL-terminated.
611 * @error: return location for error or %NULL.
612 *
613 * Appends a string to the TLV being built.
614 *
615 * Fixed-sized strings should give @n_size_prefix_bytes equal to 0.
616 *
617 * Returns: %TRUE if the string is successfully added, otherwise %FALSE is returned and @error is set.
618 *
619 * Since: 1.12
620 */
621 gboolean qmi_message_tlv_write_string (QmiMessage *self,
622 guint8 n_size_prefix_bytes,
623 const gchar *in,
624 gssize in_length,
625 GError **error);
626
627 /*****************************************************************************/
628 /* TLV reader */
629
630 /**
631 * qmi_message_tlv_read_init:
632 * @self: a #QmiMessage.
633 * @type: specific ID of the TLV to read.
634 * @out_tlv_length: (out): optional return location for the TLV size.
635 * @error: return location for error or %NULL.
636 *
637 * Starts reading a given TLV from the #QmiMessage.
638 *
639 * Returns: the offset where the TLV starts, or 0 if an error happens.
640 *
641 * Since: 1.12
642 */
643 gsize qmi_message_tlv_read_init (QmiMessage *self,
644 guint8 type,
645 guint16 *out_tlv_length,
646 GError **error);
647
648 /**
649 * qmi_message_tlv_read_guint8:
650 * @self: a #QmiMessage.
651 * @tlv_offset: offset that was returned by qmi_message_tlv_read_init().
652 * @offset: (inout): address of the offset within the TLV value.
653 * @out: (out): return location for the read #guint8.
654 * @error: return location for error or %NULL.
655 *
656 * Reads an unsigned byte from the TLV.
657 *
658 * @offset needs to point to a valid @gsize specifying the index to start
659 * reading from within the TLV value (0 for the first item). If the variable
660 * is successfully read, @offset will be updated to point past the read item.
661 *
662 * Returns: %TRUE if the variable is successfully read, otherwise %FALSE is returned and @error is set.
663 *
664 * Since: 1.12
665 */
666 gboolean qmi_message_tlv_read_guint8 (QmiMessage *self,
667 gsize tlv_offset,
668 gsize *offset,
669 guint8 *out,
670 GError **error);
671
672 /**
673 * qmi_message_tlv_read_gint8:
674 * @self: a #QmiMessage.
675 * @tlv_offset: offset that was returned by qmi_message_tlv_read_init().
676 * @offset: (inout): address of a the offset within the TLV value.
677 * @out: (out): return location for the read #gint8.
678 * @error: return location for error or %NULL.
679 *
680 * Reads a signed byte from the TLV.
681 *
682 * @offset needs to point to a valid @gsize specifying the index to start
683 * reading from within the TLV value (0 for the first item). If the variable
684 * is successfully read, @offset will be updated to point past the read item.
685 *
686 * Returns: %TRUE if the variable is successfully read, otherwise %FALSE is returned and @error is set.
687 *
688 * Since: 1.12
689 */
690 gboolean qmi_message_tlv_read_gint8 (QmiMessage *self,
691 gsize tlv_offset,
692 gsize *offset,
693 gint8 *out,
694 GError **error);
695
696 /**
697 * qmi_message_tlv_read_guint16:
698 * @self: a #QmiMessage.
699 * @tlv_offset: offset that was returned by qmi_message_tlv_read_init().
700 * @offset: (inout): address of a the offset within the TLV value.
701 * @endian: source endianness, which will be swapped to host byte order if necessary.
702 * @out: (out): return location for the read #guint16.
703 * @error: return location for error or %NULL.
704 *
705 * Reads an unsigned 16-bit integer from the TLV, in host byte order.
706 *
707 * @offset needs to point to a valid @gsize specifying the index to start
708 * reading from within the TLV value (0 for the first item). If the variable
709 * is successfully read, @offset will be updated to point past the read item.
710 *
711 * Returns: %TRUE if the variable is successfully read, otherwise %FALSE is returned and @error is set.
712 *
713 * Since: 1.12
714 */
715 gboolean qmi_message_tlv_read_guint16 (QmiMessage *self,
716 gsize tlv_offset,
717 gsize *offset,
718 QmiEndian endian,
719 guint16 *out,
720 GError **error);
721
722 /**
723 * qmi_message_tlv_read_gint16:
724 * @self: a #QmiMessage.
725 * @tlv_offset: offset that was returned by qmi_message_tlv_read_init().
726 * @offset: (inout): address of a the offset within the TLV value.
727 * @endian: source endianness, which will be swapped to host byte order if necessary.
728 * @out: (out): return location for the read #gint16.
729 * @error: return location for error or %NULL.
730 *
731 * Reads a signed 16-bit integer from the TLV, in host byte order.
732 *
733 * @offset needs to point to a valid @gsize specifying the index to start
734 * reading from within the TLV value (0 for the first item). If the variable
735 * is successfully read, @offset will be updated to point past the read item.
736 *
737 * Returns: %TRUE if the variable is successfully read, otherwise %FALSE is returned and @error is set.
738 *
739 * Since: 1.12
740 */
741 gboolean qmi_message_tlv_read_gint16 (QmiMessage *self,
742 gsize tlv_offset,
743 gsize *offset,
744 QmiEndian endian,
745 gint16 *out,
746 GError **error);
747
748 /**
749 * qmi_message_tlv_read_guint32:
750 * @self: a #QmiMessage.
751 * @tlv_offset: offset that was returned by qmi_message_tlv_read_init().
752 * @offset: (inout): address of a the offset within the TLV value.
753 * @endian: source endianness, which will be swapped to host byte order if necessary.
754 * @out: (out): return location for the read #guint32.
755 * @error: return location for error or %NULL.
756 *
757 * Reads an unsigned 32-bit integer from the TLV, in host byte order.
758 *
759 * @offset needs to point to a valid @gsize specifying the index to start
760 * reading from within the TLV value (0 for the first item). If the variable
761 * is successfully read, @offset will be updated to point past the read item.
762 *
763 * Returns: %TRUE if the variable is successfully read, otherwise %FALSE is returned and @error is set.
764 *
765 * Since: 1.12
766 */
767 gboolean qmi_message_tlv_read_guint32 (QmiMessage *self,
768 gsize tlv_offset,
769 gsize *offset,
770 QmiEndian endian,
771 guint32 *out,
772 GError **error);
773
774 /**
775 * qmi_message_tlv_read_gint32:
776 * @self: a #QmiMessage.
777 * @tlv_offset: offset that was returned by qmi_message_tlv_read_init().
778 * @offset: (inout): address of a the offset within the TLV value.
779 * @endian: source endianness, which will be swapped to host byte order if necessary.
780 * @out: (out): return location for the read #gint32.
781 * @error: return location for error or %NULL.
782 *
783 * Reads a signed 32-bit integer from the TLV, in host byte order.
784 *
785 * @offset needs to point to a valid @gsize specifying the index to start
786 * reading from within the TLV value (0 for the first item). If the variable
787 * is successfully read, @offset will be updated to point past the read item.
788 *
789 * Returns: %TRUE if the variable is successfully read, otherwise %FALSE is returned and @error is set.
790 *
791 * Since: 1.12
792 */
793 gboolean qmi_message_tlv_read_gint32 (QmiMessage *self,
794 gsize tlv_offset,
795 gsize *offset,
796 QmiEndian endian,
797 gint32 *out,
798 GError **error);
799
800 /**
801 * qmi_message_tlv_read_guint64:
802 * @self: a #QmiMessage.
803 * @tlv_offset: offset that was returned by qmi_message_tlv_read_init().
804 * @offset: (inout): address of a the offset within the TLV value.
805 * @endian: source endianness, which will be swapped to host byte order if necessary.
806 * @out: (out): return location for the read #guint64.
807 * @error: return location for error or %NULL.
808 *
809 * Reads an unsigned 64-bit integer from the TLV, in host byte order.
810 *
811 * @offset needs to point to a valid @gsize specifying the index to start
812 * reading from within the TLV value (0 for the first item). If the variable
813 * is successfully read, @offset will be updated to point past the read item.
814 *
815 * Returns: %TRUE if the variable is successfully read, otherwise %FALSE is returned and @error is set.
816 *
817 * Since: 1.12
818 */
819 gboolean qmi_message_tlv_read_guint64 (QmiMessage *self,
820 gsize tlv_offset,
821 gsize *offset,
822 QmiEndian endian,
823 guint64 *out,
824 GError **error);
825
826 /**
827 * qmi_message_tlv_read_gint64:
828 * @self: a #QmiMessage.
829 * @tlv_offset: offset that was returned by qmi_message_tlv_read_init().
830 * @offset: (inout): address of a the offset within the TLV value.
831 * @endian: source endianness, which will be swapped to host byte order if necessary.
832 * @out: (out): return location for the read #gint64.
833 * @error: return location for error or %NULL.
834 *
835 * Reads a signed 64-bit integer from the TLV, in host byte order.
836 *
837 * @offset needs to point to a valid @gsize specifying the index to start
838 * reading from within the TLV value (0 for the first item). If the variable
839 * is successfully read, @offset will be updated to point past the read item.
840 *
841 * Returns: %TRUE if the variable is successfully read, otherwise %FALSE is returned and @error is set.
842 *
843 * Since: 1.12
844 */
845 gboolean qmi_message_tlv_read_gint64 (QmiMessage *self,
846 gsize tlv_offset,
847 gsize *offset,
848 QmiEndian endian,
849 gint64 *out,
850 GError **error);
851
852 /**
853 * qmi_message_tlv_read_sized_guint:
854 * @self: a #QmiMessage.
855 * @tlv_offset: offset that was returned by qmi_message_tlv_read_init().
856 * @offset: (inout): address of a the offset within the TLV value.
857 * @n_bytes: number of bytes to read.
858 * @endian: source endianness, which will be swapped to host byte order if necessary.
859 * @out: (out): return location for the read #guint64.
860 * @error: return location for error or %NULL.
861 *
862 * Reads a @b_bytes-sized integer from the TLV, in host byte order.
863 *
864 * @offset needs to point to a valid @gsize specifying the index to start
865 * reading from within the TLV value (0 for the first item). If the variable
866 * is successfully read, @offset will be updated to point past the read item.
867 *
868 * Returns: %TRUE if the variable is successfully read, otherwise %FALSE is returned and @error is set.
869 *
870 * Since: 1.12
871 */
872 gboolean qmi_message_tlv_read_sized_guint (QmiMessage *self,
873 gsize tlv_offset,
874 gsize *offset,
875 guint n_bytes,
876 QmiEndian endian,
877 guint64 *out,
878 GError **error);
879
880 /**
881 * qmi_message_tlv_read_gfloat_endian:
882 * @self: a #QmiMessage.
883 * @tlv_offset: offset that was returned by qmi_message_tlv_read_init().
884 * @offset: (inout): address of a the offset within the TLV value.
885 * @endian: source endianness, which will be swapped to host byte order if necessary.
886 * @out: (out): return location for the read #gfloat.
887 * @error: return location for error or %NULL.
888 *
889 * Reads a 32-bit floating-point number from the TLV.
890 *
891 * @offset needs to point to a valid @gsize specifying the index to start
892 * reading from within the TLV value (0 for the first item). If the variable
893 * is successfully read, @offset will be updated to point past the read item.
894 *
895 * Returns: %TRUE if the variable is successfully read, otherwise %FALSE is returned and @error is set.
896 *
897 * Since: 1.12
898 */
899 gboolean qmi_message_tlv_read_gfloat_endian (QmiMessage *self,
900 gsize tlv_offset,
901 gsize *offset,
902 QmiEndian endian,
903 gfloat *out,
904 GError **error);
905
906 /**
907 * qmi_message_tlv_read_gdouble:
908 * @self: a #QmiMessage.
909 * @tlv_offset: offset that was returned by qmi_message_tlv_read_init().
910 * @offset: (inout): address of a the offset within the TLV value.
911 * @endian: source endianness, which will be swapped to host byte order if necessary.
912 * @out: (out): return location for the read #gdouble.
913 * @error: return location for error or %NULL.
914 *
915 * Reads a 64-bit floating-point number from the TLV.
916 *
917 * @offset needs to point to a valid @gsize specifying the index to start
918 * reading from within the TLV value (0 for the first item). If the variable
919 * is successfully read, @offset will be updated to point past the read item.
920 *
921 * Returns: %TRUE if the variable is successfully read, otherwise %FALSE is returned and @error is set.
922 *
923 * Since: 1.22
924 */
925 gboolean qmi_message_tlv_read_gdouble (QmiMessage *self,
926 gsize tlv_offset,
927 gsize *offset,
928 QmiEndian endian,
929 gdouble *out,
930 GError **error);
931
932 /**
933 * qmi_message_tlv_read_string:
934 * @self: a #QmiMessage.
935 * @tlv_offset: offset that was returned by qmi_message_tlv_read_init().
936 * @offset: (inout): address of a the offset within the TLV value.
937 * @n_size_prefix_bytes: number of bytes used in the size prefix.
938 * @max_size: maximum number of bytes to read, or 0 to read all available bytes.
939 * @out: (out): return location for the read string. The returned value should be freed with g_free().
940 * @error: return location for error or %NULL.
941 *
942 * Reads a string from the TLV.
943 *
944 * @offset needs to point to a valid @gsize specifying the index to start
945 * reading from within the TLV value (0 for the first item). If the variable
946 * is successfully read, @offset will be updated to point past the read item.
947 *
948 * Since 1.24.6 the read string is guaranteed to be valid UTF-8. Also, in order to
949 * overcome known firmware errors on string fields, this method will also
950 * attempt to parse the string as GSM-7 or UCS-2 if the initial UTF-8 validation
951 * fails.
952 *
953 * Returns: %TRUE if the variable is successfully read, otherwise %FALSE is returned and @error is set.
954 *
955 * Since: 1.12
956 */
957 gboolean qmi_message_tlv_read_string (QmiMessage *self,
958 gsize tlv_offset,
959 gsize *offset,
960 guint8 n_size_prefix_bytes,
961 guint16 max_size,
962 gchar **out,
963 GError **error);
964
965 /**
966 * qmi_message_tlv_read_fixed_size_string:
967 * @self: a #QmiMessage.
968 * @tlv_offset: offset that was returned by qmi_message_tlv_read_init().
969 * @offset: (inout): address of a the offset within the TLV value.
970 * @string_length: amount of bytes to read.
971 * @out: (out): buffer preallocated by the client, with at least @string_length bytes.
972 * @error: return location for error or %NULL.
973 *
974 * Reads a string from the TLV.
975 *
976 * The string written in @out will need to be NUL-terminated by the caller.
977 *
978 * @offset needs to point to a valid @gsize specifying the index to start
979 * reading from within the TLV value (0 for the first item). If the variable
980 * is successfully read, @offset will be updated to point past the read item.
981 *
982 * Since 1.24.6 the read string is guaranteed to be valid UTF-8.
983 *
984 * The fixed sized field may be suffixed with e.g. 0xFF if the contents are
985 * shorter than @string_length. Since 1.26, this method will return the valid
986 * UTF-8 characters in the start of the string, instead of returning an error
987 * when doing the full UTF-8 string validation.
988 *
989 * Returns: %TRUE if the variable is successfully read, otherwise %FALSE is returned and @error is set.
990 *
991 * Since: 1.12
992 */
993 gboolean qmi_message_tlv_read_fixed_size_string (QmiMessage *self,
994 gsize tlv_offset,
995 gsize *offset,
996 guint16 string_length,
997 gchar *out,
998 GError **error);
999
1000 #if defined (LIBQMI_GLIB_COMPILATION)
1001 G_GNUC_INTERNAL
1002 guint16 qmi_message_tlv_read_remaining_size (QmiMessage *self,
1003 gsize tlv_offset,
1004 gsize offset);
1005 #endif
1006
1007 /*****************************************************************************/
1008 /* Raw TLV handling */
1009
1010 /**
1011 * QmiMessageForeachRawTlvFn:
1012 * @type: specific ID of the TLV.
1013 * @value: value of the TLV.
1014 * @length: length of the TLV, in bytes.
1015 * @user_data: user data.
1016 *
1017 * Callback type to use when iterating raw TLVs with
1018 * qmi_message_foreach_raw_tlv().
1019 *
1020 * Since: 1.0
1021 */
1022 typedef void (* QmiMessageForeachRawTlvFn) (guint8 type,
1023 const guint8 *value,
1024 gsize length,
1025 gpointer user_data);
1026
1027 /**
1028 * qmi_message_foreach_raw_tlv:
1029 * @self: a #QmiMessage.
1030 * @func: (scope call): the function to call for each TLV.
1031 * @user_data: (closure): user data to pass to the function.
1032 *
1033 * Calls the given function for each TLV found within the #QmiMessage.
1034 *
1035 * Since: 1.0
1036 */
1037 void qmi_message_foreach_raw_tlv (QmiMessage *self,
1038 QmiMessageForeachRawTlvFn func,
1039 gpointer user_data);
1040
1041 /**
1042 * qmi_message_get_raw_tlv:
1043 * @self: a #QmiMessage.
1044 * @type: specific ID of the TLV to get.
1045 * @length: (out): return location for the length of the TLV.
1046 *
1047 * Get the raw data buffer of a specific TLV within the #QmiMessage.
1048 *
1049 * Returns: (transfer none): The raw data buffer of the TLV, or %NULL if not found.
1050 *
1051 * Since: 1.0
1052 */
1053 const guint8 *qmi_message_get_raw_tlv (QmiMessage *self,
1054 guint8 type,
1055 guint16 *length);
1056
1057 /**
1058 * qmi_message_add_raw_tlv:
1059 * @self: a #QmiMessage.
1060 * @type: specific ID of the TLV to add.
1061 * @raw: raw data buffer with the value of the TLV.
1062 * @length: length of the raw data buffer.
1063 * @error: return location for error or %NULL.
1064 *
1065 * Creates a new @type TLV with the value given in @raw, and adds it to the #QmiMessage.
1066 *
1067 * Returns: %TRUE if the TLV is successfully added, otherwise %FALSE is returned and @error is set.
1068 *
1069 * Since: 1.0
1070 */
1071 gboolean qmi_message_add_raw_tlv (QmiMessage *self,
1072 guint8 type,
1073 const guint8 *raw,
1074 gsize length,
1075 GError **error);
1076
1077 /*****************************************************************************/
1078 /* Other helpers */
1079
1080 /**
1081 * qmi_message_set_transaction_id:
1082 * @self: a #QmiMessage.
1083 * @transaction_id: transaction id.
1084 *
1085 * Overwrites the transaction ID of the message.
1086 *
1087 * Since: 1.8
1088 */
1089 void qmi_message_set_transaction_id (QmiMessage *self,
1090 guint16 transaction_id);
1091
1092 #if defined (LIBQMI_GLIB_COMPILATION)
1093 G_GNUC_INTERNAL
1094 gboolean __qmi_message_is_abortable (QmiMessage *self,
1095 QmiMessageContext *context);
1096 #endif
1097
1098 /*****************************************************************************/
1099 /* Printable helpers */
1100
1101 /**
1102 * qmi_message_get_printable_full:
1103 * @self: a #QmiMessage.
1104 * @context: a #QmiMessageContext.
1105 * @line_prefix: prefix string to use in each new generated line.
1106 *
1107 * Gets a printable string with the contents of the whole QMI message.
1108 *
1109 * If known, the printable string will contain translated TLV values as well as
1110 * the raw data buffer contents.
1111 *
1112 * The translation of the contents may be specific to the @context provided,
1113 * e.g. for vendor-specific messages.
1114 *
1115 * If no @context given, the behavior is the same as qmi_message_get_printable().
1116 *
1117 * Returns: (transfer full): a newly allocated string, which should be freed with g_free().
1118 *
1119 * Since: 1.18
1120 */
1121 gchar *qmi_message_get_printable_full (QmiMessage *self,
1122 QmiMessageContext *context,
1123 const gchar *line_prefix);
1124
1125 /**
1126 * qmi_message_get_tlv_printable:
1127 * @self: a #QmiMessage.
1128 * @line_prefix: prefix string to use in each new generated line.
1129 * @type: type of the TLV.
1130 * @raw: raw data buffer with the value of the TLV.
1131 * @raw_length: length of the raw data buffer.
1132 *
1133 * Gets a printable string with the contents of the TLV.
1134 *
1135 * This method is the most generic one and doesn't try to translate the TLV contents.
1136 *
1137 * Returns: (transfer full): a newly allocated string, which should be freed with g_free().
1138 *
1139 * Since: 1.0
1140 */
1141 gchar *qmi_message_get_tlv_printable (QmiMessage *self,
1142 const gchar *line_prefix,
1143 guint8 type,
1144 const guint8 *raw,
1145 gsize raw_length);
1146
1147 G_END_DECLS
1148
1149 #endif /* _LIBQMI_GLIB_QMI_MESSAGE_H_ */