Debian Codegraph @

src/libqmi-glib/qmi-device.h

raw
1 /* -*- Mode: C; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
2 /*
3 * libqmi-glib -- GLib/GIO based library to control QMI devices
4 *
5 * This library is free software; you can redistribute it and/or
6 * modify it under the terms of the GNU Lesser General Public
7 * License as published by the Free Software Foundation; either
8 * version 2 of the License, or (at your option) any later version.
9 *
10 * This library is distributed in the hope that it will be useful,
11 * but WITHOUT ANY WARRANTY; without even the implied warranty of
12 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
13 * Lesser General Public License for more details.
14 *
15 * You should have received a copy of the GNU Lesser General Public
16 * License along with this library; if not, write to the
17 * Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
18 * Boston, MA 02110-1301 USA.
19 *
20 * Copyright (C) 2012-2017 Aleksander Morgado <[email protected]>
21 */
22
23 #ifndef _LIBQMI_GLIB_QMI_DEVICE_H_
24 #define _LIBQMI_GLIB_QMI_DEVICE_H_
25
26 #if !defined (__LIBQMI_GLIB_H_INSIDE__) && !defined (LIBQMI_GLIB_COMPILATION)
27 #error "Only <libqmi-glib.h> can be included directly."
28 #endif
29
30 #include <glib-object.h>
31 #include <gio/gio.h>
32
33 #include "qmi-enums.h"
34 #include "qmi-message.h"
35 #include "qmi-message-context.h"
36 #include "qmi-client.h"
37 #include "qmi-version.h"
38
39 #if QMI_QRTR_SUPPORTED
40 # include <libqrtr-glib.h>
41 #endif
42
43 G_BEGIN_DECLS
44
45 #define QMI_TYPE_DEVICE (qmi_device_get_type ())
46 #define QMI_DEVICE(obj) (G_TYPE_CHECK_INSTANCE_CAST ((obj), QMI_TYPE_DEVICE, QmiDevice))
47 #define QMI_DEVICE_CLASS(klass) (G_TYPE_CHECK_CLASS_CAST ((klass), QMI_TYPE_DEVICE, QmiDeviceClass))
48 #define QMI_IS_DEVICE(obj) (G_TYPE_CHECK_INSTANCE_TYPE ((obj), QMI_TYPE_DEVICE))
49 #define QMI_IS_DEVICE_CLASS(klass) (G_TYPE_CHECK_CLASS_TYPE ((klass), QMI_TYPE_DEVICE))
50 #define QMI_DEVICE_GET_CLASS(obj) (G_TYPE_INSTANCE_GET_CLASS ((obj), QMI_TYPE_DEVICE, QmiDeviceClass))
51
52 typedef struct _QmiDevice QmiDevice;
53 typedef struct _QmiDeviceClass QmiDeviceClass;
54 typedef struct _QmiDevicePrivate QmiDevicePrivate;
55
56 /**
57 * QMI_DEVICE_FILE:
58 *
59 * Symbol defining the #QmiDevice:device-file property.
60 *
61 * Since: 1.0
62 */
63 #define QMI_DEVICE_FILE "device-file"
64
65 /**
66 * QMI_DEVICE_NO_FILE_CHECK:
67 *
68 * Symbol defining the #QmiDevice:device-no-file-check property.
69 *
70 * Since: 1.12
71 */
72 #define QMI_DEVICE_NO_FILE_CHECK "device-no-file-check"
73
74 /**
75 * QMI_DEVICE_PROXY_PATH:
76 *
77 * Symbol defining the #QmiDevice:device-proxy-path property.
78 *
79 * Since: 1.12
80 */
81 #define QMI_DEVICE_PROXY_PATH "device-proxy-path"
82
83 /**
84 * QMI_DEVICE_WWAN_IFACE:
85 *
86 * Symbol defining the #QmiDevice:device-wwan-iface property.
87 *
88 * Since: 1.14
89 */
90 #define QMI_DEVICE_WWAN_IFACE "device-wwan-iface"
91
92 /**
93 * QMI_DEVICE_CONSECUTIVE_TIMEOUTS:
94 *
95 * Symbol defining the #QmiDevice:device-consecutive-timeouts property.
96 *
97 * Since: 1.32
98 */
99 #define QMI_DEVICE_CONSECUTIVE_TIMEOUTS "device-consecutive-timeouts"
100
101 /**
102 * QMI_DEVICE_SIGNAL_INDICATION:
103 *
104 * Symbol defining the #QmiDevice::indication signal.
105 *
106 * Since: 1.8
107 */
108 #define QMI_DEVICE_SIGNAL_INDICATION "indication"
109
110 /**
111 * QMI_DEVICE_SIGNAL_REMOVED:
112 *
113 * Symbol defining the #QmiDevice::device-removed signal.
114 *
115 * Since: 1.20
116 */
117 #define QMI_DEVICE_SIGNAL_REMOVED "device-removed"
118
119 /**
120 * QmiDevice:
121 *
122 * Generic QMI device handling routines
123 *
124 * `QmiDevice` is a generic type in charge of controlling the access of multiple
125 * [class@Client] objects to the managed QMI port.
126 *
127 * A `QmiDevice` can only handle one single QMI port.
128
129 * The #QmiDevice structure contains private data and should only be accessed
130 * using the provided API.
131 *
132 * Since: 1.0
133 */
134 struct _QmiDevice {
135 /*< private >*/
136 GObject parent;
137 QmiDevicePrivate *priv;
138 };
139
140 struct _QmiDeviceClass {
141 /*< private >*/
142 GObjectClass parent;
143 };
144
145 GType qmi_device_get_type (void);
146 G_DEFINE_AUTOPTR_CLEANUP_FUNC (QmiDevice, g_object_unref)
147
148 /**
149 * qmi_device_new:
150 * @file: a #GFile.
151 * @cancellable: optional #GCancellable object, %NULL to ignore.
152 * @callback: a #GAsyncReadyCallback to call when the initialization is finished.
153 * @user_data: the data to pass to callback function.
154 *
155 * Asynchronously creates a #QmiDevice object to manage @file.
156 * When the operation is finished, @callback will be invoked. You can then call
157 * qmi_device_new_finish() to get the result of the operation.
158 *
159 * Since: 1.0
160 */
161 void qmi_device_new (GFile *file,
162 GCancellable *cancellable,
163 GAsyncReadyCallback callback,
164 gpointer user_data);
165
166 /**
167 * qmi_device_new_finish:
168 * @res: a #GAsyncResult.
169 * @error: Return location for error or %NULL.
170 *
171 * Finishes an operation started with qmi_device_new().
172 *
173 * Returns: (transfer full): A newly created #QmiDevice, or %NULL if @error is set.
174 *
175 * Since: 1.0
176 */
177 QmiDevice *qmi_device_new_finish (GAsyncResult *res,
178 GError **error);
179
180 /**
181 * qmi_device_get_file:
182 * @self: a #QmiDevice.
183 *
184 * Get the #GFile associated with this #QmiDevice.
185 *
186 * Returns: (transfer full): a #GFile that must be freed with g_object_unref().
187 *
188 * Since: 1.0
189 */
190 GFile *qmi_device_get_file (QmiDevice *self);
191
192 /**
193 * qmi_device_peek_file:
194 * @self: a #QmiDevice.
195 *
196 * Get the #GFile associated with this #QmiDevice, without increasing the reference count
197 * on the returned object.
198 *
199 * Returns: (transfer none): a #GFile. Do not free the returned object, it is owned by @self.
200 *
201 * Since: 1.0
202 */
203 GFile *qmi_device_peek_file (QmiDevice *self);
204
205 /**
206 * qmi_device_get_path:
207 * @self: a #QmiDevice.
208 *
209 * Get the system path of the underlying QMI device.
210 *
211 * Returns: the system path of the device.
212 *
213 * Since: 1.0
214 */
215 const gchar *qmi_device_get_path (QmiDevice *self);
216
217 /**
218 * qmi_device_get_path_display:
219 * @self: a #QmiDevice.
220 *
221 * Get the system path of the underlying QMI device in UTF-8.
222 *
223 * Returns: UTF-8 encoded system path of the device.
224 *
225 * Since: 1.0
226 */
227 const gchar *qmi_device_get_path_display (QmiDevice *self);
228
229 /**
230 * qmi_device_is_open:
231 * @self: a #QmiDevice.
232 *
233 * Checks whether the #QmiDevice is open for I/O.
234 *
235 * Returns: %TRUE if @self is open, %FALSE otherwise.
236 *
237 * Since: 1.0
238 */
239 gboolean qmi_device_is_open (QmiDevice *self);
240
241 /**
242 * QmiDeviceOpenFlags:
243 * @QMI_DEVICE_OPEN_FLAGS_NONE: No flags.
244 * @QMI_DEVICE_OPEN_FLAGS_VERSION_INFO: Run version info check when opening. Since 1.24.4 this flag no longer prevents requests from being sent to the modem if they're assumed not supported based on the version info of each message.
245 * @QMI_DEVICE_OPEN_FLAGS_SYNC: Synchronize with endpoint once the device is open. Will release any previously allocated client ID.
246 * @QMI_DEVICE_OPEN_FLAGS_NET_802_3: Set network port to "802.3" mode; mutually exclusive with @QMI_DEVICE_OPEN_FLAGS_NET_RAW_IP
247 * @QMI_DEVICE_OPEN_FLAGS_NET_RAW_IP: Set network port to "raw IP" mode; mutally exclusive with @QMI_DEVICE_OPEN_FLAGS_NET_802_3
248 * @QMI_DEVICE_OPEN_FLAGS_NET_QOS_HEADER: Set network port to transmit/receive QoS headers; mutually exclusive with @QMI_DEVICE_OPEN_FLAGS_NET_NO_QOS_HEADER
249 * @QMI_DEVICE_OPEN_FLAGS_NET_NO_QOS_HEADER: Set network port to not transmit/receive QoS headers; mutually exclusive with @QMI_DEVICE_OPEN_FLAGS_NET_QOS_HEADER
250 * @QMI_DEVICE_OPEN_FLAGS_PROXY: Try to open the port through the 'qmi-proxy'. Since 1.8.
251 * @QMI_DEVICE_OPEN_FLAGS_MBIM: Open an MBIM port with QMUX tunneling service. Since 1.16.
252 * @QMI_DEVICE_OPEN_FLAGS_AUTO: Open a port either in QMI or MBIM mode, depending on device driver. Since 1.18.
253 * @QMI_DEVICE_OPEN_FLAGS_EXPECT_INDICATIONS: Explicitly state that indications are wanted (implicit in QMI mode, optional when in MBIM mode).
254 *
255 * Flags to specify which actions to be performed when the device is open.
256 *
257 * Since: 1.0
258 */
259 typedef enum { /*< since=1.0 >*/
260 QMI_DEVICE_OPEN_FLAGS_NONE = 0,
261 QMI_DEVICE_OPEN_FLAGS_VERSION_INFO = 1 << 0,
262 QMI_DEVICE_OPEN_FLAGS_SYNC = 1 << 1,
263 QMI_DEVICE_OPEN_FLAGS_NET_802_3 = 1 << 2,
264 QMI_DEVICE_OPEN_FLAGS_NET_RAW_IP = 1 << 3,
265 QMI_DEVICE_OPEN_FLAGS_NET_QOS_HEADER = 1 << 4,
266 QMI_DEVICE_OPEN_FLAGS_NET_NO_QOS_HEADER = 1 << 5,
267 QMI_DEVICE_OPEN_FLAGS_PROXY = 1 << 6,
268 QMI_DEVICE_OPEN_FLAGS_MBIM = 1 << 7,
269 QMI_DEVICE_OPEN_FLAGS_AUTO = 1 << 8,
270 QMI_DEVICE_OPEN_FLAGS_EXPECT_INDICATIONS = 1 << 9,
271 } QmiDeviceOpenFlags;
272
273 /**
274 * qmi_device_open:
275 * @self: a #QmiDevice.
276 * @flags: mask of #QmiDeviceOpenFlags specifying how the device should be opened.
277 * @timeout: maximum time, in seconds, to wait for the device to be opened.
278 * @cancellable: optional #GCancellable object, %NULL to ignore.
279 * @callback: a #GAsyncReadyCallback to call when the operation is finished.
280 * @user_data: the data to pass to callback function.
281 *
282 * Asynchronously opens a #QmiDevice for I/O.
283 *
284 * When the operation is finished @callback will be called. You can then call
285 * qmi_device_open_finish() to get the result of the operation.
286 *
287 * Since: 1.0
288 */
289 void qmi_device_open (QmiDevice *self,
290 QmiDeviceOpenFlags flags,
291 guint timeout,
292 GCancellable *cancellable,
293 GAsyncReadyCallback callback,
294 gpointer user_data);
295
296 /**
297 * qmi_device_open_finish:
298 * @self: a #QmiDevice.
299 * @res: a #GAsyncResult.
300 * @error: Return location for error or %NULL.
301 *
302 * Finishes an asynchronous open operation started with qmi_device_open().
303 *
304 * Returns: %TRUE if successful, %FALSE if @error is set.
305 *
306 * Since: 1.0
307 */
308 gboolean qmi_device_open_finish (QmiDevice *self,
309 GAsyncResult *res,
310 GError **error);
311
312 /**
313 * qmi_device_close_async:
314 * @self: a #QmiDevice.
315 * @timeout: maximum time, in seconds, to wait for the device to be closed.
316 * @cancellable: a #GCancellable, or %NULL.
317 * @callback: a #GAsyncReadyCallback to call when the operation is finished.
318 * @user_data: the data to pass to callback function.
319 *
320 * Asynchronously closes a #QmiDevice, preventing any further I/O.
321 *
322 * If this device was opened with @QMI_DEVICE_OPEN_FLAGS_MBIM, this
323 * operation will wait for the response of the underlying MBIM close
324 * sequence.
325 *
326 * Closing a #QmiDevice multiple times will not return an error.
327 *
328 * When the operation is finished @callback will be called. You can then call
329 * qmi_device_close_finish() to get the result of the operation.
330 *
331 * Since: 1.18
332 */
333 void qmi_device_close_async (QmiDevice *self,
334 guint timeout,
335 GCancellable *cancellable,
336 GAsyncReadyCallback callback,
337 gpointer user_data);
338
339 /**
340 * qmi_device_close_finish:
341 * @self: a #QmiDevice.
342 * @res: a #GAsyncResult.
343 * @error: Return location for error or %NULL.
344 *
345 * Finishes an operation started with qmi_device_close_async().
346 *
347 * Returns: %TRUE if successful, %FALSE if @error is set.
348 *
349 * Since: 1.18
350 */
351 gboolean qmi_device_close_finish (QmiDevice *self,
352 GAsyncResult *res,
353 GError **error);
354
355 /**
356 * qmi_device_allocate_client:
357 * @self: a #QmiDevice.
358 * @service: a valid #QmiService.
359 * @cid: a valid client ID, or %QMI_CID_NONE.
360 * @timeout: maximum time to wait.
361 * @cancellable: optional #GCancellable object, %NULL to ignore.
362 * @callback: a #GAsyncReadyCallback to call when the operation is finished.
363 * @user_data: the data to pass to callback function.
364 *
365 * Asynchronously allocates a new #QmiClient in @self.
366 *
367 * If %QMI_CID_NONE is given in @cid, a new client ID will be allocated;
368 * otherwise a client with the given @cid will be generated.
369 *
370 * When the operation is finished @callback will be called. You can then call
371 * qmi_device_allocate_client_finish() to get the result of the operation.
372 *
373 * Note: Clients for the %QMI_SERVICE_CTL cannot be created with this method;
374 * instead get/peek the implicit one from @self.
375 *
376 * Since: 1.0
377 */
378 void qmi_device_allocate_client (QmiDevice *self,
379 QmiService service,
380 guint8 cid,
381 guint timeout,
382 GCancellable *cancellable,
383 GAsyncReadyCallback callback,
384 gpointer user_data);
385
386 /**
387 * qmi_device_allocate_client_finish:
388 * @self: a #QmiDevice.
389 * @res: a #GAsyncResult.
390 * @error: Return location for error or %NULL.
391 *
392 * Finishes an operation started with qmi_device_allocate_client().
393 *
394 * Returns: (transfer full): a newly allocated #QmiClient, or %NULL if @error is set.
395 *
396 * Since: 1.0
397 */
398 QmiClient *qmi_device_allocate_client_finish (QmiDevice *self,
399 GAsyncResult *res,
400 GError **error);
401
402 /**
403 * QmiDeviceReleaseClientFlags:
404 * @QMI_DEVICE_RELEASE_CLIENT_FLAGS_NONE: No flags.
405 * @QMI_DEVICE_RELEASE_CLIENT_FLAGS_RELEASE_CID: Release the CID when releasing the client.
406 *
407 * Flags to specify which actions to be performed when releasing the client.
408 *
409 * Since: 1.0
410 */
411 typedef enum { /*< since=1.0 >*/
412 QMI_DEVICE_RELEASE_CLIENT_FLAGS_NONE = 0,
413 QMI_DEVICE_RELEASE_CLIENT_FLAGS_RELEASE_CID = 1 << 0
414 } QmiDeviceReleaseClientFlags;
415
416 /**
417 * qmi_device_release_client:
418 * @self: a #QmiDevice.
419 * @client: the #QmiClient to release.
420 * @flags: mask of #QmiDeviceReleaseClientFlags specifying how the client should be released.
421 * @timeout: maximum time to wait.
422 * @cancellable: optional #GCancellable object, %NULL to ignore.
423 * @callback: a #GAsyncReadyCallback to call when the operation is finished.
424 * @user_data: the data to pass to callback function.
425 *
426 * Asynchronously releases the #QmiClient from the #QmiDevice.
427 *
428 * Once the #QmiClient has been released, it cannot be used any more to
429 * perform operations.
430 *
431 *
432 * When the operation is finished @callback will be called. You can then call
433 * qmi_device_release_client_finish() to get the result of the operation.
434 *
435 * Since: 1.0
436 */
437 void qmi_device_release_client (QmiDevice *self,
438 QmiClient *client,
439 QmiDeviceReleaseClientFlags flags,
440 guint timeout,
441 GCancellable *cancellable,
442 GAsyncReadyCallback callback,
443 gpointer user_data);
444
445 /**
446 * qmi_device_release_client_finish:
447 * @self: a #QmiDevice.
448 * @res: a #GAsyncResult.
449 * @error: Return location for error or %NULL.
450 *
451 * Finishes an operation started with qmi_device_release_client().
452 *
453 * Note that even if the release operation returns an error, the client should
454 * anyway be considered released, and shouldn't be used afterwards.
455 *
456 * Returns: %TRUE if successful, or %NULL if @error is set.
457 *
458 * Since: 1.0
459 */
460 gboolean qmi_device_release_client_finish (QmiDevice *self,
461 GAsyncResult *res,
462 GError **error);
463
464 /**
465 * qmi_device_set_instance_id:
466 * @self: a #QmiDevice.
467 * @instance_id: the instance ID.
468 * @timeout: maximum time to wait.
469 * @cancellable: optional #GCancellable object, %NULL to ignore.
470 * @callback: a #GAsyncReadyCallback to call when the operation is finished.
471 * @user_data: the data to pass to callback function.
472 *
473 * Sets the instance ID of the #QmiDevice.
474 *
475 * When the operation is finished @callback will be called. You can then call
476 * qmi_device_set_instance_id_finish() to get the result of the operation.
477 *
478 * Since: 1.0
479 */
480 void qmi_device_set_instance_id (QmiDevice *self,
481 guint8 instance_id,
482 guint timeout,
483 GCancellable *cancellable,
484 GAsyncReadyCallback callback,
485 gpointer user_data);
486
487 /**
488 * qmi_device_set_instance_id_finish:
489 * @self: a #QmiDevice.
490 * @res: a #GAsyncResult.
491 * @link_id: a placeholder for the output #guint16, or %NULL if not required.
492 * @error: Return location for error or %NULL.
493 *
494 * Finishes an operation started with qmi_device_set_instance_id().
495 *
496 * Returns: %TRUE if successful, %FALSE if @error is set.
497 *
498 * Since: 1.0
499 */
500 gboolean qmi_device_set_instance_id_finish (QmiDevice *self,
501 GAsyncResult *res,
502 guint16 *link_id,
503 GError **error);
504
505 /**
506 * qmi_device_command_full:
507 * @self: a #QmiDevice.
508 * @message: the message to send.
509 * @message_context: the context of the message.
510 * @timeout: maximum time, in seconds, to wait for the response.
511 * @cancellable: a #GCancellable, or %NULL.
512 * @callback: a #GAsyncReadyCallback to call when the operation is finished.
513 * @user_data: the data to pass to callback function.
514 *
515 * Asynchronously sends a #QmiMessage to the device.
516 *
517 * The message will be processed according to the specific @message_context
518 * given. If no @context given, the behavior is the same as qmi_device_command().
519 *
520 * If the operation is cancelled via @cancellable, a %QMI_PROTOCOL_ERROR_ABORTED
521 * error will be returned always. If the QMI method may be aborted, there is
522 * no guarantee that the operation is truly aborted before the error is returned
523 * so it may really happen that the operation really succeeded and the method
524 * would still return %QMI_PROTOCOL_ERROR_ABORTED. In order to use abortable
525 * methods and make sure the response is the correct one, use
526 * qmi_device_command_abortable().
527 *
528 * When the operation is finished @callback will be called. You can then call
529 * qmi_device_command_full_finish() to get the result of the operation.
530 *
531 * Since: 1.18
532 */
533 void qmi_device_command_full (QmiDevice *self,
534 QmiMessage *message,
535 QmiMessageContext *message_context,
536 guint timeout,
537 GCancellable *cancellable,
538 GAsyncReadyCallback callback,
539 gpointer user_data);
540
541 /**
542 * qmi_device_command_full_finish:
543 * @self: a #QmiDevice.
544 * @res: a #GAsyncResult.
545 * @error: Return location for error or %NULL.
546 *
547 * Finishes an operation started with qmi_device_command_full().
548 *
549 * Returns: (transfer full): a #QmiMessage response, or %NULL if @error is set. The returned value should be freed with qmi_message_unref().
550 *
551 * Since: 1.18
552 */
553 QmiMessage *qmi_device_command_full_finish (QmiDevice *self,
554 GAsyncResult *res,
555 GError **error);
556
557 /**
558 * QmiDeviceCommandAbortableBuildRequestFn:
559 * @self: a #QmiDevice.
560 * @message: the #QmiMessage to abort.
561 * @user_data: the data provided when calling qmi_device_command_abortable().
562 * @error: Return location for error or %NULL.
563 *
564 * Callback to run when processing the command abortion. This callback
565 * should create a service-specific and client-specific abort request to
566 * be passed to the device.
567 *
568 * Returns: the abort request as a #QmiMessage or %NULL if @error is set.
569 *
570 * Since: 1.24
571 */
572 typedef QmiMessage * (* QmiDeviceCommandAbortableBuildRequestFn) (QmiDevice *self,
573 QmiMessage *message,
574 gpointer user_data,
575 GError **error);
576
577 /**
578 * QmiDeviceCommandAbortableParseResponseFn:
579 * @self: a #QmiDevice.
580 * @abort_response: the abort response #QmiMessage.
581 * @user_data: the data provided when calling qmi_device_command_abortable().
582 * @error: Return location for error or %NULL.
583 *
584 * Callback to run when processing the command abortion. This callback
585 * should parse the abort response provided by the device, and build an
586 * appropriate output.
587 *
588 * Returns: %TRUE if the abort succeeded, %FALSE if error is set.
589 *
590 * Since: 1.24
591 */
592 typedef gboolean (* QmiDeviceCommandAbortableParseResponseFn) (QmiDevice *self,
593 QmiMessage *abort_response,
594 gpointer user_data,
595 GError **error);
596
597 /**
598 * qmi_device_command_abortable:
599 * @self: a #QmiDevice.
600 * @message: the message to send.
601 * @message_context: the context of the message.
602 * @timeout: maximum time, in seconds, to wait for the response.
603 * @abort_build_request_fn: (scope async) (closure abort_user_data): callback to build an abort request.
604 * @abort_parse_response_fn: (scope async) (closure abort_user_data): callback to parse an abort response.
605 * @abort_user_data: user data to pass to @abort_build_request_fn and @abort_parse_response_fn.
606 * @abort_user_data_free: (destroy abort_user_data): a #GDestroyNotify to free @abort_user_data.
607 * @cancellable: a #GCancellable, or %NULL.
608 * @callback: a #GAsyncReadyCallback to call when the operation is finished.
609 * @user_data: the data to pass to callback function.
610 *
611 * Asynchronously sends a #QmiMessage to the device.
612 *
613 * The message will be processed according to the specific @message_context
614 * given.
615 *
616 * If the operation is cancelled via @cancellable, an abort message will
617 * be sent to the device in order to really abort the ongoing operation. The
618 * qmi_device_command_abortable() method will not finish until either a
619 * successful reply is received from the device or otherwise the command
620 * abortion is confirmed.
621 *
622 * If a successful command response arrives before the abort is processed by
623 * the device, the operation will succeed even if @cancellable has been set, so
624 * that upper layers can do whatever they need to do to properly tear down the
625 * operation.
626 *
627 * If an error command reponse arrives before the abort is processed by the
628 * device, the operation will fail with the error returned by the device.
629 *
630 * The %QMI_PROTOCOL_ERROR_ABORTED error will only be returned as a result
631 * of this operation if the command request was truly aborted by the device,
632 * and so, the user of the method should not assume that cancelling the
633 * @cancellable will always make the method return a %QMI_PROTOCOL_ERROR_ABORTED
634 * error.
635 *
636 * The @build_request_fn and @parse_response_fn callbacks are required in order
637 * to build the abort requests and parse the abort responses, because these
638 * are both service and client specific.
639 *
640 * When the operation is finished @callback will be called. You can then call
641 * qmi_device_command_abortable_finish() to get the result of the operation.
642 *
643 * Since: 1.24
644 */
645 void qmi_device_command_abortable (QmiDevice *self,
646 QmiMessage *message,
647 QmiMessageContext *message_context,
648 guint timeout,
649 QmiDeviceCommandAbortableBuildRequestFn abort_build_request_fn,
650 QmiDeviceCommandAbortableParseResponseFn abort_parse_response_fn,
651 gpointer abort_user_data,
652 GDestroyNotify abort_user_data_free,
653 GCancellable *cancellable,
654 GAsyncReadyCallback callback,
655 gpointer user_data);
656
657 /**
658 * qmi_device_command_abortable_finish:
659 * @self: a #QmiDevice.
660 * @res: a #GAsyncResult.
661 * @error: Return location for error or %NULL.
662 *
663 * Finishes an operation started with qmi_device_command_abortable().
664 *
665 * Returns: (transfer full): a #QmiMessage response, or %NULL if @error is set. The returned value should be freed with qmi_message_unref().
666 *
667 * Since: 1.24
668 */
669 QmiMessage *qmi_device_command_abortable_finish (QmiDevice *self,
670 GAsyncResult *res,
671 GError **error);
672
673 /**
674 * QmiDeviceServiceVersionInfo:
675 * @service: a #QmiService.
676 * @major_version: major version of the service.
677 * @minor_version: minor version of the service.
678 *
679 * Version information for a service.
680 *
681 * Since: 1.6
682 */
683 typedef struct {
684 QmiService service;
685 guint16 major_version;
686 guint16 minor_version;
687 } QmiDeviceServiceVersionInfo;
688
689 /**
690 * qmi_device_get_service_version_info:
691 * @self: a #QmiDevice.
692 * @timeout: maximum time to wait for the method to complete, in seconds.
693 * @cancellable: a #GCancellable or %NULL.
694 * @callback: a #GAsyncReadyCallback to call when the request is satisfied.
695 * @user_data: user data to pass to @callback.
696 *
697 * Asynchronously requests the service version information of the device.
698 *
699 * When the operation is finished, @callback will be invoked in the thread-default main loop of the thread you are calling this method from.
700 *
701 * You can then call qmi_device_get_service_version_info_finish() to get the result of the operation.
702 *
703 * Since: 1.6
704 */
705 void qmi_device_get_service_version_info (QmiDevice *self,
706 guint timeout,
707 GCancellable *cancellable,
708 GAsyncReadyCallback callback,
709 gpointer user_data);
710
711 /**
712 * qmi_device_get_service_version_info_finish:
713 * @self: a #QmiDevice.
714 * @res: a #GAsyncResult.
715 * @error: Return location for error or %NULL.
716 *
717 * Finishes an operation started with qmi_device_get_service_version_info().
718 *
719 * Returns: (transfer full)(element-type QmiDeviceServiceVersionInfo):
720 * a #GArray of #QmiDeviceServiceVersionInfo elements, or %NULL if @error
721 * is set. The returned value should be freed with g_array_unref().
722 *
723 * Since: 1.6
724 */
725 GArray *qmi_device_get_service_version_info_finish (QmiDevice *self,
726 GAsyncResult *res,
727 GError **error);
728
729 /**
730 * qmi_device_get_consecutive_timeouts:
731 * @self: a #QmiDevice.
732 *
733 * Gets the number of consecutive transaction timeouts in the device.
734 *
735 * Returns: a #guint.
736 *
737 * Since: 1.32
738 */
739 guint qmi_device_get_consecutive_timeouts (QmiDevice *self);
740
741 /******************************************************************************/
742 /* qmi_wwan specific APIs */
743
744 /**
745 * qmi_device_get_wwan_iface:
746 * @self: a #QmiDevice.
747 *
748 * Get the WWAN interface name associated with the QMI control port.
749 * This value will be loaded every time it's asked for it.
750 *
751 * <note><para>
752 * This method is only applicable when using the qmi_wwan kernel driver.
753 * </para></note>
754 *
755 * Returns: UTF-8 encoded network interface name, or %NULL if not available.
756 *
757 * Since: 1.14
758 */
759 const gchar *qmi_device_get_wwan_iface (QmiDevice *self);
760
761 /**
762 * QmiDeviceExpectedDataFormat:
763 * @QMI_DEVICE_EXPECTED_DATA_FORMAT_UNKNOWN: Unknown.
764 * @QMI_DEVICE_EXPECTED_DATA_FORMAT_802_3: 802.3.
765 * @QMI_DEVICE_EXPECTED_DATA_FORMAT_RAW_IP: Raw IP.
766 * @QMI_DEVICE_EXPECTED_DATA_FORMAT_QMAP_PASS_THROUGH: QMAP pass-through. Since 1.28.
767 *
768 * Data format expected by the kernel.
769 *
770 * <note><para>
771 * This type is only applicable when using the qmi_wwan kernel driver.
772 * </para></note>
773 *
774 * Since: 1.14
775 */
776 typedef enum { /*< since=1.14 >*/
777 QMI_DEVICE_EXPECTED_DATA_FORMAT_UNKNOWN,
778 QMI_DEVICE_EXPECTED_DATA_FORMAT_802_3,
779 QMI_DEVICE_EXPECTED_DATA_FORMAT_RAW_IP,
780 QMI_DEVICE_EXPECTED_DATA_FORMAT_QMAP_PASS_THROUGH,
781 } QmiDeviceExpectedDataFormat;
782
783 /**
784 * qmi_device_get_expected_data_format:
785 * @self: a #QmiDevice.
786 * @error: Return location for error or %NULL.
787 *
788 * Retrieves the data format currently expected by the kernel in the network
789 * interface.
790 *
791 * If @QMI_DEVICE_EXPECTED_DATA_FORMAT_UNKNOWN is returned, the user should
792 * assume that 802.3 is the expected format, as that is what the qmi_wwan
793 * driver expected by default before kernel 4.5.
794 *
795 * <note><para>
796 * This method is only applicable when using the qmi_wwan kernel driver.
797 * </para></note>
798 *
799 * Returns: a valid #QmiDeviceExpectedDataFormat, or @QMI_DEVICE_EXPECTED_DATA_FORMAT_UNKNOWN if @error is set.
800 *
801 * Since: 1.14
802 */
803 QmiDeviceExpectedDataFormat qmi_device_get_expected_data_format (QmiDevice *self,
804 GError **error);
805
806 /**
807 * qmi_device_set_expected_data_format:
808 * @self: a #QmiDevice.
809 * @format: a known #QmiDeviceExpectedDataFormat.
810 * @error: Return location for error or %NULL.
811 *
812 * Configures the data format currently expected by the kernel in the network
813 * interface.
814 *
815 * <note><para>
816 * This method is only applicable when using the qmi_wwan kernel driver.
817 * </para></note>
818 *
819 * Returns: %TRUE if successful, or %FALSE if @error is set.
820 *
821 * Since: 1.14
822 */
823 gboolean qmi_device_set_expected_data_format (QmiDevice *self,
824 QmiDeviceExpectedDataFormat format,
825 GError **error);
826
827 /**
828 * qmi_device_check_expected_data_format_supported:
829 * @self: a #QmiDevice.
830 * @format: a known #QmiDeviceExpectedDataFormat.
831 * @error: Return location for error or %NULL.
832 *
833 * Checks whether the given data format is supported by the kernel.
834 * interface.
835 *
836 * <note><para>
837 * This method is only applicable when using the qmi_wwan kernel driver.
838 * </para></note>
839 *
840 * Returns: %TRUE if the data format is supported, or %FALSE if @error is set.
841 *
842 * Since: 1.28
843 */
844 gboolean qmi_device_check_expected_data_format_supported (QmiDevice *self,
845 QmiDeviceExpectedDataFormat format,
846 GError **error);
847
848 /******************************************************************************/
849 /* Link management APIs */
850
851 /**
852 * QMI_DEVICE_MUX_ID_AUTOMATIC:
853 *
854 * Symbol defining a mux id that will be automatically allocated during runtime
855 * when creating net links.
856 *
857 * Since: 1.28
858 */
859 #define QMI_DEVICE_MUX_ID_AUTOMATIC G_MAXUINT
860
861 /**
862 * QMI_DEVICE_MUX_ID_UNBOUND:
863 *
864 * Symbol defining the mux id for an unbound interface. This value is also used
865 * to indicate an invalid mux id.
866 *
867 * Since: 1.28
868 */
869 #define QMI_DEVICE_MUX_ID_UNBOUND 0
870
871 /**
872 * QMI_DEVICE_MUX_ID_MIN:
873 *
874 * Symbol defining the minimum supported mux id.
875 *
876 * Since: 1.28
877 */
878 #define QMI_DEVICE_MUX_ID_MIN 1
879
880 /**
881 * QMI_DEVICE_MUX_ID_MAX:
882 *
883 * Symbol defining the maximum supported mux id.
884 *
885 * Since: 1.28
886 */
887 #define QMI_DEVICE_MUX_ID_MAX 0xFE
888
889 /**
890 * qmi_device_add_link:
891 * @self: a #QmiDevice.
892 * @mux_id: the mux id for the link, in the
893 * [%QMI_DEVICE_MUX_ID_MIN,%QMI_DEVICE_MUX_ID_MAX] range, or
894 * %QMI_DEVICE_MUX_ID_AUTOMATIC to find the first available mux id.
895 * @base_ifname: the interface which the new link will be created on.
896 * @ifname_prefix: the prefix suggested to be used for the name of the new link
897 * created.
898 * @cancellable: a #GCancellable, or %NULL.
899 * @callback: a #GAsyncReadyCallback to call when the operation is finished.
900 * @user_data: the data to pass to callback function.
901 *
902 * Asynchronously creates a new virtual network device node with a custom prefix
903 * on top of @base_ifname. This allows having multiple net interfaces running on
904 * top of another using multiplexing.
905 *
906 * If the kernel driver doesn't allow this functionality, a
907 * %QMI_CORE_ERROR_UNSUPPORTED error will be returned.
908 *
909 * The operation may fail if the given interface name is not associated to the
910 * QMI control port managed by the #QmiDevice.
911 *
912 * Depending on the kernel driver in use and the multiplexing method, the given
913 * @ifname_prefix may be ignored. The user should not assume that the returned
914 * link interface name is prefixed with @ifname_prefix as it may not be the
915 * case.
916 *
917 * When the operation is finished @callback will be called. You can then call
918 * qmi_device_add_link_finish() to get the result of the operation.
919 *
920 * <note><para>
921 * When using the qmi_wwan kernel driver, the configured expected kernel data
922 * format will be used to select the type of multiplexing method. If the
923 * format is %QMI_DEVICE_EXPECTED_DATA_FORMAT_RAW_IP the qmi_wwan specific
924 * add_mux/del_mux operations will be used. If the format is
925 * %QMI_DEVICE_EXPECTED_DATA_FORMAT_QMAP_PASS_THROUGH, the generic rmnet netlink
926 * operations will be used. No multiplexing support exists when the format is
927 * %QMI_DEVICE_EXPECTED_DATA_FORMAT_802_3.
928 * </para><para>
929 * For every other kernel driver (e.g. ipa), rmnet netlink operations are
930 * assumed to be supported.
931 * </para></note>
932 *
933 * <note><para>
934 * When using the qmi_wwan driver from a kernel older than v5.12, some of the
935 * multiplexing features like using %QMI_DEVICE_MUX_ID_AUTOMATIC may not be fully
936 * available for programs that use ephimeral #QmiDevice objects for single
937 * operations.
938 * </para></note>
939 *
940 * Since: 1.28
941 */
942 void qmi_device_add_link (QmiDevice *self,
943 guint mux_id,
944 const gchar *base_ifname,
945 const gchar *ifname_prefix,
946 GCancellable *cancellable,
947 GAsyncReadyCallback callback,
948 gpointer user_data);
949
950 /**
951 * qmi_device_add_link_finish:
952 * @self: a #QmiDevice.
953 * @res: a #GAsyncResult.
954 * @mux_id: the mux ID for the link created.
955 * @error: Return location for error or %NULL.
956 *
957 * Finishes an operation started with qmi_device_add_link().
958 *
959 * Returns: The name of the net interface created, %NULL if @error is set.
960 *
961 * Since: 1.28
962 */
963 gchar *qmi_device_add_link_finish (QmiDevice *self,
964 GAsyncResult *res,
965 guint *mux_id,
966 GError **error);
967
968 /**
969 * QmiDeviceAddLinkFlags:
970 * @QMI_DEVICE_ADD_LINK_FLAGS_NONE: none.
971 * @QMI_DEVICE_ADD_LINK_FLAGS_INGRESS_MAP_CKSUMV4: checksum offload (v4) is enabled in ingress path.
972 * @QMI_DEVICE_ADD_LINK_FLAGS_EGRESS_MAP_CKSUMV4: checksum offload (v4) is enabled in egress path.
973 * @QMI_DEVICE_ADD_LINK_FLAGS_INGRESS_MAP_CKSUMV5: checksum offload (v5) is enabled in ingress path. Since 1.32.
974 * @QMI_DEVICE_ADD_LINK_FLAGS_EGRESS_MAP_CKSUMV5: checksum offload (v5) is enabled in egress path. Since 1.32.
975 *
976 * Flags specifying the behavior of the new link.
977 *
978 * Since: 1.30
979 */
980 typedef enum { /*< since=1.30 >*/
981 QMI_DEVICE_ADD_LINK_FLAGS_NONE = 0,
982 QMI_DEVICE_ADD_LINK_FLAGS_INGRESS_MAP_CKSUMV4 = 1 << 1,
983 QMI_DEVICE_ADD_LINK_FLAGS_EGRESS_MAP_CKSUMV4 = 1 << 2,
984 QMI_DEVICE_ADD_LINK_FLAGS_INGRESS_MAP_CKSUMV5 = 1 << 3,
985 QMI_DEVICE_ADD_LINK_FLAGS_EGRESS_MAP_CKSUMV5 = 1 << 4,
986 } QmiDeviceAddLinkFlags;
987
988 /**
989 * qmi_device_add_link_with_flags:
990 * @self: a #QmiDevice.
991 * @mux_id: the mux id for the link, in the
992 * [%QMI_DEVICE_MUX_ID_MIN,%QMI_DEVICE_MUX_ID_MAX] range, or
993 * %QMI_DEVICE_MUX_ID_AUTOMATIC to find the first available mux id.
994 * @base_ifname: the interface which the new link will be created on.
995 * @ifname_prefix: the prefix suggested to be used for the name of the new link
996 * created.
997 * @flags: bitmask of %QmiDeviceAddLinkFlags values to pass to the kernel when
998 * creating the new link.
999 * @cancellable: a #GCancellable, or %NULL.
1000 * @callback: a #GAsyncReadyCallback to call when the operation is finished.
1001 * @user_data: the data to pass to callback function.
1002 *
1003 * Asynchronously creates a new virtual network device in the same way as
1004 * qmi_device_add_link() does, but passing the additional @flags to the kernel
1005 * during the operation.
1006 *
1007 * Using %QMI_DEVICE_ADD_LINK_FLAGS_NONE as @flags is equivalent to calling
1008 * qmi_device_add_link() directly.
1009 *
1010 * If the link creation with the given set of @flags is unsupported by the
1011 * backend, the operation may fail.
1012 *
1013 * <note><para>
1014 * None of the @flags supported are applicable when using the multiplexing
1015 * support provided by the qmi_wwan kernel driver, they are only used if using
1016 * the rmnet backend for link management support.
1017 * </para></note>
1018 *
1019 * Since: 1.30
1020 */
1021 void qmi_device_add_link_with_flags (QmiDevice *self,
1022 guint mux_id,
1023 const gchar *base_ifname,
1024 const gchar *ifname_prefix,
1025 QmiDeviceAddLinkFlags flags,
1026 GCancellable *cancellable,
1027 GAsyncReadyCallback callback,
1028 gpointer user_data);
1029
1030 /**
1031 * qmi_device_add_link_with_flags_finish:
1032 * @self: a #QmiDevice.
1033 * @res: a #GAsyncResult.
1034 * @mux_id: the mux ID for the link created.
1035 * @error: Return location for error or %NULL.
1036 *
1037 * Finishes an operation started with qmi_device_add_link_with_flags().
1038 *
1039 * Returns: The name of the net interface created, %NULL if @error is set.
1040 *
1041 * Since: 1.30
1042 */
1043 gchar *qmi_device_add_link_with_flags_finish (QmiDevice *self,
1044 GAsyncResult *res,
1045 guint *mux_id,
1046 GError **error);
1047
1048 /**
1049 * qmi_device_add_link_with_flags_and_initial_mux_id:
1050 * @self: a #QmiDevice.
1051 * @initial_mux_id: the initial mux id from which the first available mux id has
1052 * to be searched for in the [%QMI_DEVICE_MUX_ID_MIN,%QMI_DEVICE_MUX_ID_MAX]
1053 * range.
1054 * @base_ifname: the interface which the new link will be created on.
1055 * @ifname_prefix: the prefix suggested to be used for the name of the new link
1056 * created.
1057 * @flags: bitmask of %QmiDeviceAddLinkFlags values to pass to the kernel when
1058 * creating the new link.
1059 * @cancellable: a #GCancellable, or %NULL.
1060 * @callback: a #GAsyncReadyCallback to call when the operation is finished.
1061 * @user_data: the data to pass to callback function.
1062 *
1063 * Asynchronously creates a new virtual network device in the same way as
1064 * qmi_device_add_link_with_flags() does, but passing the additional @initial_mux_id
1065 * value from which the first available mux id interface should be looked for.
1066 *
1067 * Using %QMI_DEVICE_MUX_ID_MIN as @initial_mux_id is equivalent to calling
1068 * qmi_device_add_link_with_flags() with %QMI_DEVICE_MUX_ID_AUTOMATIC.
1069 *
1070 * If the link creation with the given set of @flags is unsupported by the
1071 * backend, the operation may fail.
1072 *
1073 * <note><para>
1074 * None of the @flags supported are applicable when using the multiplexing
1075 * support provided by the qmi_wwan kernel driver, they are only used if using
1076 * the rmnet backend for link management support.
1077 * </para></note>
1078 *
1079 * Since: 1.30
1080 */
1081 void qmi_device_add_link_with_flags_and_initial_mux_id (QmiDevice *self,
1082 guint initial_mux_id,
1083 const gchar *base_ifname,
1084 const gchar *ifname_prefix,
1085 QmiDeviceAddLinkFlags flags,
1086 GCancellable *cancellable,
1087 GAsyncReadyCallback callback,
1088 gpointer user_data);
1089
1090 /**
1091 * qmi_device_add_link_with_flags_and_initial_mux_id_finish:
1092 * @self: a #QmiDevice.
1093 * @res: a #GAsyncResult.
1094 * @mux_id: the mux ID for the link created.
1095 * @error: Return location for error or %NULL.
1096 *
1097 * Finishes an operation started with qmi_device_add_link_with_flags_and_initial_mux_id().
1098 *
1099 * Returns: The name of the net interface created, %NULL if @error is set.
1100 *
1101 * Since: 1.30
1102 */
1103 gchar *qmi_device_add_link_with_flags_and_initial_mux_id_finish (QmiDevice *self,
1104 GAsyncResult *res,
1105 guint *mux_id,
1106 GError **error);
1107
1108 /**
1109 * qmi_device_delete_link:
1110 * @self: a #QmiDevice.
1111 * @ifname: the name of the link to remove.
1112 * @mux_id: the mux ID of the link to remove.
1113 * @cancellable: a #GCancellable, or %NULL.
1114 * @callback: a #GAsyncReadyCallback to call when the operation is finished.
1115 * @user_data: the data to pass to callback function.
1116 *
1117 * Asynchronously deletes a virtual network interface that has been previously
1118 * created with qmi_device_add_link().
1119 *
1120 * If the kernel driver doesn't allow this functionality, a
1121 * %QMI_CORE_ERROR_UNSUPPORTED error will be returned.
1122 *
1123 * When the operation is finished @callback will be called. You can then call
1124 * qmi_device_delete_link_finish() to get the result of the operation.
1125 *
1126 * <note><para>
1127 * The %QMI_DEVICE_MUX_ID_UNBOUND value may be given as @mux_id if the user
1128 * can guarantee that the underlying kernel support doesn't require the
1129 * mux id info to delete the link. When using the qmi_wwan driver from a kernel
1130 * older than v5.12, a valid @mux_id is required.
1131 * </para></note>
1132 *
1133 * Since: 1.28
1134 */
1135 void qmi_device_delete_link (QmiDevice *self,
1136 const gchar *ifname,
1137 guint mux_id,
1138 GCancellable *cancellable,
1139 GAsyncReadyCallback callback,
1140 gpointer user_data);
1141
1142 /**
1143 * qmi_device_delete_link_finish:
1144 * @self: a #QmiDevice.
1145 * @res: a #GAsyncResult.
1146 * @error: Return location for error or %NULL.
1147 *
1148 * Finishes an operation started with qmi_device_delete_link().
1149 *
1150 * Returns: %TRUE if successful, %FALSE if @error is set.
1151 *
1152 * Since: 1.28
1153 */
1154 gboolean qmi_device_delete_link_finish (QmiDevice *self,
1155 GAsyncResult *res,
1156 GError **error);
1157
1158 /**
1159 * qmi_device_delete_all_links:
1160 * @self: a #QmiDevice.
1161 * @base_ifname: the interface where all links are available.
1162 * @cancellable: a #GCancellable, or %NULL.
1163 * @callback: a #GAsyncReadyCallback to call when the operation is finished.
1164 * @user_data: the data to pass to callback function.
1165 *
1166 * Asynchronously deletes all virtual network interfaces that have been previously
1167 * created with qmi_device_add_link() in @base_ifname.
1168 *
1169 * When the operation is finished @callback will be called. You can then call
1170 * qmi_device_delete_link_finish() to get the result of the operation.
1171 *
1172 * <note><para>
1173 * There is no guarantee that other processes haven't created new links by the
1174 * time this method returns. This method should be used with caution, or in setups
1175 * where only one single process is expected to do QMI network interface link
1176 * management.
1177 * </para></note>
1178 *
1179 * Since: 1.28
1180 */
1181 void qmi_device_delete_all_links (QmiDevice *self,
1182 const gchar *base_ifname,
1183 GCancellable *cancellable,
1184 GAsyncReadyCallback callback,
1185 gpointer user_data);
1186
1187 /**
1188 * qmi_device_delete_all_links_finish:
1189 * @self: a #QmiDevice.
1190 * @res: a #GAsyncResult.
1191 * @error: Return location for error or %NULL.
1192 *
1193 * Finishes an operation started with qmi_device_delete_all_links().
1194 *
1195 * Returns: %TRUE if successful, %FALSE if @error is set.
1196 *
1197 * Since: 1.28
1198 */
1199 gboolean qmi_device_delete_all_links_finish (QmiDevice *self,
1200 GAsyncResult *res,
1201 GError **error);
1202
1203 /**
1204 * qmi_device_list_links:
1205 * @self: a #QmiDevice.
1206 * @base_ifname: the base interface.
1207 * @out_links: (out)(transfer full)(element-type utf8): a placeholder for the
1208 * output #GPtrArray of link names.
1209 * @error: Return location for error or %NULL.
1210 *
1211 * Synchronously lists all virtual network interfaces that have been previously
1212 * created with qmi_device_add_link() in @base_ifname.
1213 *
1214 * Returns: %TRUE if successful, %FALSE if @error is set.
1215 *
1216 * Since: 1.28
1217 */
1218 gboolean qmi_device_list_links (QmiDevice *self,
1219 const gchar *base_ifname,
1220 GPtrArray **out_links,
1221 GError **error);
1222
1223 /**
1224 * qmi_device_check_link_supported:
1225 * @self: a #QmiDevice.
1226 * @error: Return location for error or %NULL.
1227 *
1228 * Checks whether link management is supported by the kernel.
1229 *
1230 * Returns: %TRUE if link management is supported, or %FALSE if @error is set.
1231 *
1232 * Since: 1.28
1233 */
1234 gboolean qmi_device_check_link_supported (QmiDevice *self,
1235 GError **error);
1236
1237 /******************************************************************************/
1238 /* New QRTR based APIs */
1239
1240 #if QMI_QRTR_SUPPORTED
1241
1242 /**
1243 * QMI_DEVICE_NODE:
1244 *
1245 * Symbol defining the #QmiDevice:device-node property.
1246 *
1247 * <note><para>
1248 * This property is only available when the library is built with QRTR support.
1249 * </para></note>
1250 *
1251 * Since: 1.28
1252 */
1253 #define QMI_DEVICE_NODE "device-node"
1254
1255 /**
1256 * qmi_device_new_from_node:
1257 * @node: a #QrtrNode.
1258 * @cancellable: optional #GCancellable object, #NULL to ignore.
1259 * @callback: a #GAsyncReadyCallback to call when the initialization is finished.
1260 * @user_data: the data to pass to callback function.
1261 *
1262 * Asynchronously creates a #QmiDevice object to manage @node.
1263 * When the operation is finished, @callback will be invoked. You can then call
1264 * qmi_device_new_finish() to get the result of the operation.
1265 *
1266 * <note><para>
1267 * This method is only available when the library is built with QRTR support.
1268 * </para></note>
1269 *
1270 * Since: 1.28
1271 */
1272 void qmi_device_new_from_node (QrtrNode *node,
1273 GCancellable *cancellable,
1274 GAsyncReadyCallback callback,
1275 gpointer user_data);
1276
1277 /**
1278 * qmi_device_new_from_node_finish:
1279 * @res: a #GAsyncResult.
1280 * @error: Return location for error or %NULL.
1281 *
1282 * Finishes an operation started with qmi_device_new_from_node().
1283 *
1284 * <note><para>
1285 * This method is only available when the library is built with QRTR support.
1286 * </para></note>
1287 *
1288 * Returns: (transfer full): A newly created #QmiDevice, or %NULL if @error is set.
1289 *
1290 * Since: 1.28
1291 */
1292 QmiDevice *qmi_device_new_from_node_finish (GAsyncResult *res,
1293 GError **error);
1294
1295 /**
1296 * qmi_device_get_node:
1297 * @self: a #QmiDevice.
1298 *
1299 * Get the #QrtrNode associated with this #QmiDevice.
1300 *
1301 * <note><para>
1302 * This method is only available when the library is built with QRTR support.
1303 * </para></note>
1304 *
1305 * Returns: (transfer full): a #QrtrNode that must be freed with g_object_unref() or %NULL if none available.
1306 *
1307 * Since: 1.28
1308 */
1309 QrtrNode *qmi_device_get_node (QmiDevice *self);
1310
1311 /**
1312 * qmi_device_peek_node:
1313 * @self: a #QmiDevice.
1314 *
1315 * Get the #QrtrNode associated with this #QmiDevice, without increasing the
1316 * reference count on the returned object.
1317 *
1318 * <note><para>
1319 * This method is only available when the library is built with QRTR support.
1320 * </para></note>
1321 *
1322 * Returns: (transfer none): a #QrtrNode or %NULL if none available. Do not free the returned object, it is owned by @self.
1323 *
1324 * Since: 1.28
1325 */
1326 QrtrNode *qmi_device_peek_node (QmiDevice *self);
1327
1328 #endif /* QMI_QRTR_SUPPORTED */
1329
1330 G_END_DECLS
1331
1332 #endif /* _LIBQMI_GLIB_QMI_DEVICE_H_ */