diff options
| -rw-r--r-- | src/libqmi-glib/qmi-device.c | 389 | ||||
| -rw-r--r-- | src/libqmi-glib/qmi-device.h | 691 |
2 files changed, 610 insertions, 470 deletions
diff --git a/src/libqmi-glib/qmi-device.c b/src/libqmi-glib/qmi-device.c index 9fab5e1..ab3664a 100644 --- a/src/libqmi-glib/qmi-device.c +++ b/src/libqmi-glib/qmi-device.c @@ -57,17 +57,6 @@ #include "qmi-enum-types.h" #include "qmi-proxy.h" -/** - * SECTION:qmi-device - * @title: QmiDevice - * @short_description: Generic QMI device handling routines - * - * #QmiDevice is a generic type in charge of controlling the access of multiple - * #QmiClient objects to the managed QMI port. - * - * A #QmiDevice can only handle one single QMI port. - */ - static void async_initable_iface_init (GAsyncInitableIface *iface); G_DEFINE_TYPE_EXTENDED (QmiDevice, qmi_device, G_TYPE_OBJECT, 0, @@ -360,16 +349,6 @@ device_match_transaction (QmiDevice *self, /*****************************************************************************/ /* Version info request */ -/** - * qmi_device_get_service_version_info_finish: - * @self: a #QmiDevice. - * @res: a #GAsyncResult. - * @error: Return location for error or %NULL. - * - * Finishes an operation started with qmi_device_get_service_version_info(). - * - * Returns: a #GArray of #QmiDeviceServiceVersionInfo elements, or #NULL if @error is set. The returned value should be freed with g_array_unref(). - */ GArray * qmi_device_get_service_version_info_finish (QmiDevice *self, GAsyncResult *res, @@ -432,20 +411,6 @@ version_info_ready (QmiClientCtl *client_ctl, g_object_unref (simple); } -/** - * qmi_device_get_service_version_info: - * @self: a #QmiDevice. - * @timeout: maximum time to wait for the method to complete, in seconds. - * @cancellable: a #GCancellable or %NULL. - * @callback: a #GAsyncReadyCallback to call when the request is satisfied. - * @user_data: user data to pass to @callback. - * - * Asynchronously requests the service version information of the device. - * - * When the operation is finished, @callback will be invoked in the thread-default main loop of the thread you are calling this method from. - * - * You can then call qmi_device_get_service_version_info_finish() to get the result of the operation. - */ void qmi_device_get_service_version_info (QmiDevice *self, guint timeout, @@ -574,14 +539,6 @@ check_message_supported (QmiDevice *self, /*****************************************************************************/ -/** - * qmi_device_get_file: - * @self: a #QmiDevice. - * - * Get the #GFile associated with this #QmiDevice. - * - * Returns: a #GFile that must be freed with g_object_unref(). - */ GFile * qmi_device_get_file (QmiDevice *self) { @@ -595,15 +552,6 @@ qmi_device_get_file (QmiDevice *self) return file; } -/** - * qmi_device_peek_file: - * @self: a #QmiDevice. - * - * Get the #GFile associated with this #QmiDevice, without increasing the reference count - * on the returned object. - * - * Returns: a #GFile. Do not free the returned object, it is owned by @self. - */ GFile * qmi_device_peek_file (QmiDevice *self) { @@ -612,14 +560,6 @@ qmi_device_peek_file (QmiDevice *self) return self->priv->file; } -/** - * qmi_device_get_path: - * @self: a #QmiDevice. - * - * Get the system path of the underlying QMI device. - * - * Returns: the system path of the device. - */ const gchar * qmi_device_get_path (QmiDevice *self) { @@ -628,14 +568,6 @@ qmi_device_get_path (QmiDevice *self) return self->priv->path; } -/** - * qmi_device_get_path_display: - * @self: a #QmiDevice. - * - * Get the system path of the underlying QMI device in UTF-8. - * - * Returns: UTF-8 encoded system path of the device. - */ const gchar * qmi_device_get_path_display (QmiDevice *self) { @@ -644,14 +576,6 @@ qmi_device_get_path_display (QmiDevice *self) return self->priv->path_display; } -/** - * qmi_device_is_open: - * @self: a #QmiDevice. - * - * Checks whether the #QmiDevice is open for I/O. - * - * Returns: %TRUE if @self is open, %FALSE otherwise. - */ gboolean qmi_device_is_open (QmiDevice *self) { @@ -732,17 +656,6 @@ reload_wwan_iface_name (QmiDevice *self) g_warning ("[%s] wwan iface not found", self->priv->path_display); } -/** - * qmi_device_get_wwan_iface: - * @self: a #QmiDevice. - * - * Get the WWAN interface name associated with this /dev/cdc-wdm control port. - * This value will be loaded every time it's asked for it. - * - * Returns: UTF-8 encoded network interface name, or %NULL if not available. - * - * Since: 1.14 - */ const gchar * qmi_device_get_wwan_iface (QmiDevice *self) { @@ -885,21 +798,6 @@ common_get_set_expected_data_format (QmiDevice *self, return expected; } -/** - * qmi_device_get_expected_data_format: - * @self: a #QmiDevice. - * @error: Return location for error or %NULL. - * - * Retrieves the data format currently expected by the kernel in the network - * interface. - * - * If @QMI_DEVICE_EXPECTED_DATA_FORMAT_UNKNOWN is returned, the user should assume - * that 802.3 is the expected format. - * - * Returns: a valid #QmiDeviceExpectedDataFormat, or @QMI_DEVICE_EXPECTED_DATA_FORMAT_UNKNOWN if @error is set. - * - * Since: 1.14 - */ QmiDeviceExpectedDataFormat qmi_device_get_expected_data_format (QmiDevice *self, GError **error) @@ -909,19 +807,6 @@ qmi_device_get_expected_data_format (QmiDevice *self, return common_get_set_expected_data_format (self, QMI_DEVICE_EXPECTED_DATA_FORMAT_UNKNOWN, error); } -/** - * qmi_device_set_expected_data_format: - * @self: a #QmiDevice. - * @format: a known #QmiDeviceExpectedDataFormat. - * @error: Return location for error or %NULL. - * - * Configures the data format currently expected by the kernel in the network - * interface. - * - * Returns: %TRUE if successful, or #NULL if @error is set. - * - * Since: 1.14 - */ gboolean qmi_device_set_expected_data_format (QmiDevice *self, QmiDeviceExpectedDataFormat format, @@ -998,16 +883,6 @@ allocate_client_context_complete_and_free (AllocateClientContext *ctx) g_slice_free (AllocateClientContext, ctx); } -/** - * qmi_device_allocate_client_finish: - * @self: a #QmiDevice. - * @res: a #GAsyncResult. - * @error: Return location for error or %NULL. - * - * Finishes an operation started with qmi_device_allocate_client(). - * - * Returns: a newly allocated #QmiClient, or #NULL if @error is set. - */ QmiClient * qmi_device_allocate_client_finish (QmiDevice *self, GAsyncResult *res, @@ -1128,27 +1003,6 @@ allocate_cid_ready (QmiClientCtl *client_ctl, qmi_message_ctl_allocate_cid_output_unref (output); } -/** - * qmi_device_allocate_client: - * @self: a #QmiDevice. - * @service: a valid #QmiService. - * @cid: a valid client ID, or #QMI_CID_NONE. - * @timeout: maximum time to wait. - * @cancellable: optional #GCancellable object, #NULL to ignore. - * @callback: a #GAsyncReadyCallback to call when the operation is finished. - * @user_data: the data to pass to callback function. - * - * Asynchronously allocates a new #QmiClient in @self. - * - * If #QMI_CID_NONE is given in @cid, a new client ID will be allocated; - * otherwise a client with the given @cid will be generated. - * - * When the operation is finished @callback will be called. You can then call - * qmi_device_allocate_client_finish() to get the result of the operation. - * - * Note: Clients for the #QMI_SERVICE_CTL cannot be created with this method; - * instead get/peek the implicit one from @self. - */ void qmi_device_allocate_client (QmiDevice *self, QmiService service, @@ -1290,19 +1144,6 @@ release_client_context_complete_and_free (ReleaseClientContext *ctx) g_slice_free (ReleaseClientContext, ctx); } -/** - * qmi_device_release_client_finish: - * @self: a #QmiDevice. - * @res: a #GAsyncResult. - * @error: Return location for error or %NULL. - * - * Finishes an operation started with qmi_device_release_client(). - * - * Note that even if the release operation returns an error, the client should - * anyway be considered released, and shouldn't be used afterwards. - * - * Returns: %TRUE if successful, or #NULL if @error is set. - */ gboolean qmi_device_release_client_finish (QmiDevice *self, GAsyncResult *res, @@ -1343,25 +1184,6 @@ client_ctl_release_cid_ready (QmiClientCtl *client_ctl, qmi_message_ctl_release_cid_output_unref (output); } -/** - * qmi_device_release_client: - * @self: a #QmiDevice. - * @client: the #QmiClient to release. - * @flags: mask of #QmiDeviceReleaseClientFlags specifying how the client should be released. - * @timeout: maximum time to wait. - * @cancellable: optional #GCancellable object, #NULL to ignore. - * @callback: a #GAsyncReadyCallback to call when the operation is finished. - * @user_data: the data to pass to callback function. - * - * Asynchronously releases the #QmiClient from the #QmiDevice. - * - * Once the #QmiClient has been released, it cannot be used any more to - * perform operations. - * - * - * When the operation is finished @callback will be called. You can then call - * qmi_device_release_client_finish() to get the result of the operation. - */ void qmi_device_release_client (QmiDevice *self, QmiClient *client, @@ -1455,17 +1277,6 @@ qmi_device_release_client (QmiDevice *self, /*****************************************************************************/ /* Set instance ID */ -/** - * qmi_device_set_instance_id_finish: - * @self: a #QmiDevice. - * @res: a #GAsyncResult. - * @link_id: a placeholder for the output #guint16, or #NULL if not required. - * @error: Return location for error or %NULL. - * - * Finishes an operation started with qmi_device_set_instance_id(). - * - * Returns: %TRUE if successful, %FALSE if @error is set. - */ gboolean qmi_device_set_instance_id_finish (QmiDevice *self, GAsyncResult *res, @@ -1509,20 +1320,6 @@ set_instance_id_ready (QmiClientCtl *client_ctl, g_simple_async_result_complete (simple); } -/** - * qmi_device_set_instance_id: - * @self: a #QmiDevice. - * @instance_id: the instance ID. - * @timeout: maximum time to wait. - * @cancellable: optional #GCancellable object, #NULL to ignore. - * @callback: a #GAsyncReadyCallback to call when the operation is finished. - * @user_data: the data to pass to callback function. - * - * Sets the instance ID of the #QmiDevice. - * - * When the operation is finished @callback will be called. You can then call - * qmi_device_set_instance_id_finish() to get the result of the operation. - */ void qmi_device_set_instance_id (QmiDevice *self, guint8 instance_id, @@ -2046,16 +1843,6 @@ device_open_context_complete_and_free (DeviceOpenContext *ctx) g_slice_free (DeviceOpenContext, ctx); } -/** - * qmi_device_open_finish: - * @self: a #QmiDevice. - * @res: a #GAsyncResult. - * @error: Return location for error or %NULL. - * - * Finishes an asynchronous open operation started with qmi_device_open(). - * - * Returns: %TRUE if successful, %FALSE if @error is set. - */ gboolean qmi_device_open_finish (QmiDevice *self, GAsyncResult *res, @@ -2546,20 +2333,6 @@ device_open_context_step (DeviceOpenContext *ctx) g_assert_not_reached (); } -/** - * qmi_device_open: - * @self: a #QmiDevice. - * @flags: mask of #QmiDeviceOpenFlags specifying how the device should be opened. - * @timeout: maximum time, in seconds, to wait for the device to be opened. - * @cancellable: optional #GCancellable object, #NULL to ignore. - * @callback: a #GAsyncReadyCallback to call when the operation is finished. - * @user_data: the data to pass to callback function. - * - * Asynchronously opens a #QmiDevice for I/O. - * - * When the operation is finished @callback will be called. You can then call - * qmi_device_open_finish() to get the result of the operation. - */ void qmi_device_open (QmiDevice *self, QmiDeviceOpenFlags flags, @@ -2638,18 +2411,6 @@ mbim_device_close_ready (MbimDevice *dev, #endif -/** - * qmi_device_close_finish: - * @self: a #QmiDevice. - * @res: a #GAsyncResult. - * @error: Return location for error or %NULL. - * - * Finishes an operation started with qmi_device_close_async(). - * - * Returns: %TRUE if successful, %FALSE if @error is set. - * - * Since: 1.18 - */ gboolean qmi_device_close_finish (QmiDevice *self, GAsyncResult *res, @@ -2658,27 +2419,6 @@ qmi_device_close_finish (QmiDevice *self, return g_task_propagate_boolean (G_TASK (res), error); } -/** - * qmi_device_close_async: - * @self: a #QmiDevice. - * @timeout: maximum time, in seconds, to wait for the device to be closed. - * @cancellable: a #GCancellable, or %NULL. - * @callback: a #GAsyncReadyCallback to call when the operation is finished. - * @user_data: the data to pass to callback function. - * - * Asynchronously closes a #QmiDevice, preventing any further I/O. - * - * If this device was opened with @QMI_DEVICE_OPEN_FLAGS_MBIM, this - * operation will wait for the response of the underlying MBIM close - * sequence. - * - * Closing a #QmiDevice multiple times will not return an error. - * - * When the operation is finished @callback will be called. You can then call - * qmi_device_close_finish() to get the result of the operation. - * - * Since: 1.18 - */ void qmi_device_close_async (QmiDevice *self, guint timeout, @@ -2711,23 +2451,6 @@ qmi_device_close_async (QmiDevice *self, g_object_unref (task); } -/** - * qmi_device_close: - * @self: a #QmiDevice - * @error: Return location for error or %NULL. - * - * Synchronously closes a #QmiDevice, preventing any further I/O. - * - * If this device was opened with @QMI_DEVICE_OPEN_FLAGS_MBIM, this - * operation will not wait for the response of the underlying MBIM - * close sequence. - * - * Closing a #QmiDevice multiple times will not return an error. - * - * Returns: %TRUE if successful, %FALSE if @error is set. - * - * Deprecated: 1.18: Use qmi_device_close_async() instead. - */ gboolean qmi_device_close (QmiDevice *self, GError **error) @@ -2866,18 +2589,6 @@ mbim_command (QmiDevice *self, /*****************************************************************************/ /* Command */ -/** - * qmi_device_command_full_finish: - * @self: a #QmiDevice. - * @res: a #GAsyncResult. - * @error: Return location for error or %NULL. - * - * Finishes an operation started with qmi_device_command_full(). - * - * Returns: a #QmiMessage response, or #NULL if @error is set. The returned value should be freed with qmi_message_unref(). - * - * Since: 1.18 - */ QmiMessage * qmi_device_command_full_finish (QmiDevice *self, GAsyncResult *res, @@ -2907,28 +2618,6 @@ transaction_early_error (QmiDevice *self, g_error_free (error); } -/** - * qmi_device_command_full: - * @self: a #QmiDevice. - * @message: the message to send. - * @message_context: the context of the message. - * @timeout: maximum time, in seconds, to wait for the response. - * @cancellable: a #GCancellable, or %NULL. - * @callback: a #GAsyncReadyCallback to call when the operation is finished. - * @user_data: the data to pass to callback function. - * - * Asynchronously sends a #QmiMessage to the device. - * - * The message will be processed according to the specific @message_context - * given. - * - * When the operation is finished @callback will be called. You can then call - * qmi_device_command_full_finish() to get the result of the operation. - * - * If no @context given, the behavior is the same as qmi_device_command(). - * - * Since: 1.18 - */ void qmi_device_command_full (QmiDevice *self, QmiMessage *message, @@ -3055,18 +2744,6 @@ qmi_device_command_full (QmiDevice *self, /*****************************************************************************/ /* Generic command */ -/** - * qmi_device_command_finish: - * @self: a #QmiDevice. - * @res: a #GAsyncResult. - * @error: Return location for error or %NULL. - * - * Finishes an operation started with qmi_device_command(). - * - * Returns: a #QmiMessage response, or #NULL if @error is set. The returned value should be freed with qmi_message_unref(). - * - * Deprecated: 1.18. - */ QmiMessage * qmi_device_command_finish (QmiDevice *self, GAsyncResult *res, @@ -3075,22 +2752,6 @@ qmi_device_command_finish (QmiDevice *self, return qmi_device_command_full_finish (self, res, error); } -/** - * qmi_device_command: - * @self: a #QmiDevice. - * @message: the message to send. - * @timeout: maximum time, in seconds, to wait for the response. - * @cancellable: a #GCancellable, or %NULL. - * @callback: a #GAsyncReadyCallback to call when the operation is finished. - * @user_data: the data to pass to callback function. - * - * Asynchronously sends a generic #QmiMessage to the device with no context. - * - * When the operation is finished @callback will be called. You can then call - * qmi_device_command_finish() to get the result of the operation. - * - * Deprecated: 1.18: Use qmi_device_command_full() instead. - */ void qmi_device_command (QmiDevice *self, QmiMessage *message, @@ -3105,15 +2766,6 @@ qmi_device_command (QmiDevice *self, /*****************************************************************************/ /* New QMI device */ -/** - * qmi_device_new_finish: - * @res: a #GAsyncResult. - * @error: Return location for error or %NULL. - * - * Finishes an operation started with qmi_device_new(). - * - * Returns: A newly created #QmiDevice, or #NULL if @error is set. - */ QmiDevice * qmi_device_new_finish (GAsyncResult *res, GError **error) @@ -3128,17 +2780,6 @@ qmi_device_new_finish (GAsyncResult *res, return (ret ? QMI_DEVICE (ret) : NULL); } -/** - * qmi_device_new: - * @file: a #GFile. - * @cancellable: optional #GCancellable object, #NULL to ignore. - * @callback: a #GAsyncReadyCallback to call when the initialization is finished. - * @user_data: the data to pass to callback function. - * - * Asynchronously creates a #QmiDevice object to manage @file. - * When the operation is finished, @callback will be invoked. You can then call - * qmi_device_new_finish() to get the result of the operation. - */ void qmi_device_new (GFile *file, GCancellable *cancellable, @@ -3458,6 +3099,11 @@ qmi_device_class_init (QmiDeviceClass *klass) object_class->finalize = finalize; object_class->dispose = dispose; + /** + * QmiDevice:device-file: + * + * Since: 1.0 + */ properties[PROP_FILE] = g_param_spec_object (QMI_DEVICE_FILE, "Device file", @@ -3466,6 +3112,11 @@ qmi_device_class_init (QmiDeviceClass *klass) G_PARAM_READWRITE | G_PARAM_CONSTRUCT_ONLY); g_object_class_install_property (object_class, PROP_FILE, properties[PROP_FILE]); + /** + * QmiDevice:device-no-file-check: + * + * Since: 1.12 + */ properties[PROP_NO_FILE_CHECK] = g_param_spec_boolean (QMI_DEVICE_NO_FILE_CHECK, "No file check", @@ -3474,6 +3125,11 @@ qmi_device_class_init (QmiDeviceClass *klass) G_PARAM_WRITABLE | G_PARAM_CONSTRUCT_ONLY); g_object_class_install_property (object_class, PROP_NO_FILE_CHECK, properties[PROP_NO_FILE_CHECK]); + /** + * QmiDevice:device-proxy-path: + * + * Since: 1.12 + */ properties[PROP_PROXY_PATH] = g_param_spec_string (QMI_DEVICE_PROXY_PATH, "Proxy path", @@ -3482,6 +3138,11 @@ qmi_device_class_init (QmiDeviceClass *klass) G_PARAM_WRITABLE | G_PARAM_CONSTRUCT_ONLY); g_object_class_install_property (object_class, PROP_PROXY_PATH, properties[PROP_PROXY_PATH]); + /** + * QmiDevice:device-wwan-iface: + * + * Since: 1.14 + */ properties[PROP_WWAN_IFACE] = g_param_spec_string (QMI_DEVICE_WWAN_IFACE, "WWAN iface", @@ -3491,11 +3152,13 @@ qmi_device_class_init (QmiDeviceClass *klass) g_object_class_install_property (object_class, PROP_WWAN_IFACE, properties[PROP_WWAN_IFACE]); /** - * QmiClientDms::event-report: - * @object: A #QmiClientDms. - * @output: A #QmiIndicationDmsEventReportOutput. + * QmiDevice::indication: + * @object: A #QmiDevice. + * @output: A #QmiMessage. + * + * The ::indication signal gets emitted when a QMI indication is received. * - * The ::event-report signal gets emitted when a '<link linkend="libqmi-glib-DMS-Event-Report.top_of_page">Event Report</link>' indication is received. + * Since: 1.8 */ signals[SIGNAL_INDICATION] = g_signal_new (QMI_DEVICE_SIGNAL_INDICATION, diff --git a/src/libqmi-glib/qmi-device.h b/src/libqmi-glib/qmi-device.h index 6ed832a..8ff2318 100644 --- a/src/libqmi-glib/qmi-device.h +++ b/src/libqmi-glib/qmi-device.h @@ -37,6 +37,17 @@ G_BEGIN_DECLS +/** + * SECTION:qmi-device + * @title: QmiDevice + * @short_description: Generic QMI device handling routines + * + * #QmiDevice is a generic type in charge of controlling the access of multiple + * #QmiClient objects to the managed QMI port. + * + * A #QmiDevice can only handle one single QMI port. + */ + #define QMI_TYPE_DEVICE (qmi_device_get_type ()) #define QMI_DEVICE(obj) (G_TYPE_CHECK_INSTANCE_CAST ((obj), QMI_TYPE_DEVICE, QmiDevice)) #define QMI_DEVICE_CLASS(klass) (G_TYPE_CHECK_CLASS_CAST ((klass), QMI_TYPE_DEVICE, QmiDeviceClass)) @@ -48,11 +59,49 @@ typedef struct _QmiDevice QmiDevice; typedef struct _QmiDeviceClass QmiDeviceClass; typedef struct _QmiDevicePrivate QmiDevicePrivate; -#define QMI_DEVICE_FILE "device-file" +/** + * QMI_DEVICE_FILE: + * + * Symbol defining the #QmiDevice:device-file property. + * + * Since: 1.0 + */ +#define QMI_DEVICE_FILE "device-file" + +/** + * QMI_DEVICE_NO_FILE_CHECK: + * + * Symbol defining the #QmiDevice:device-no-file-check property. + * + * Since: 1.12 + */ #define QMI_DEVICE_NO_FILE_CHECK "device-no-file-check" -#define QMI_DEVICE_PROXY_PATH "device-proxy-path" -#define QMI_DEVICE_WWAN_IFACE "device-wwan-iface" +/** + * QMI_DEVICE_PROXY_PATH: + * + * Symbol defining the #QmiDevice:device-proxy-path property. + * + * Since: 1.12 + */ +#define QMI_DEVICE_PROXY_PATH "device-proxy-path" + +/** + * QMI_DEVICE_WWAN_IFACE: + * + * Symbol defining the #QmiDevice:device-wwan-iface property. + * + * Since: 1.14 + */ +#define QMI_DEVICE_WWAN_IFACE "device-wwan-iface" + +/** + * QMI_DEVICE_SIGNAL_INDICATION: + * +* Symbol defining the #QmiDevice::indication signal. + * + * Since: 1.8 + */ #define QMI_DEVICE_SIGNAL_INDICATION "indication" /** @@ -60,6 +109,8 @@ typedef struct _QmiDevicePrivate QmiDevicePrivate; * * The #QmiDevice structure contains private data and should only be accessed * using the provided API. + * + * Since: 1.0 */ struct _QmiDevice { /*< private >*/ @@ -74,19 +125,111 @@ struct _QmiDeviceClass { GType qmi_device_get_type (void); -void qmi_device_new (GFile *file, - GCancellable *cancellable, - GAsyncReadyCallback callback, - gpointer user_data); -QmiDevice *qmi_device_new_finish (GAsyncResult *res, - GError **error); +/** + * qmi_device_new: + * @file: a #GFile. + * @cancellable: optional #GCancellable object, #NULL to ignore. + * @callback: a #GAsyncReadyCallback to call when the initialization is finished. + * @user_data: the data to pass to callback function. + * + * Asynchronously creates a #QmiDevice object to manage @file. + * When the operation is finished, @callback will be invoked. You can then call + * qmi_device_new_finish() to get the result of the operation. + * + * Since: 1.0 + */ +void qmi_device_new (GFile *file, + GCancellable *cancellable, + GAsyncReadyCallback callback, + gpointer user_data); -GFile *qmi_device_get_file (QmiDevice *self); -GFile *qmi_device_peek_file (QmiDevice *self); -const gchar *qmi_device_get_path (QmiDevice *self); -const gchar *qmi_device_get_path_display (QmiDevice *self); -const gchar *qmi_device_get_wwan_iface (QmiDevice *self); -gboolean qmi_device_is_open (QmiDevice *self); +/** + * qmi_device_new_finish: + * @res: a #GAsyncResult. + * @error: Return location for error or %NULL. + * + * Finishes an operation started with qmi_device_new(). + * + * Returns: A newly created #QmiDevice, or #NULL if @error is set. + * + * Since: 1.0 + */ +QmiDevice *qmi_device_new_finish (GAsyncResult *res, + GError **error); + +/** + * qmi_device_get_file: + * @self: a #QmiDevice. + * + * Get the #GFile associated with this #QmiDevice. + * + * Returns: a #GFile that must be freed with g_object_unref(). + * + * Since: 1.0 + */ +GFile *qmi_device_get_file (QmiDevice *self); + +/** + * qmi_device_peek_file: + * @self: a #QmiDevice. + * + * Get the #GFile associated with this #QmiDevice, without increasing the reference count + * on the returned object. + * + * Returns: a #GFile. Do not free the returned object, it is owned by @self. + * + * Since: 1.0 + */ +GFile *qmi_device_peek_file (QmiDevice *self); + +/** + * qmi_device_get_path: + * @self: a #QmiDevice. + * + * Get the system path of the underlying QMI device. + * + * Returns: the system path of the device. + * + * Since: 1.0 + */ +const gchar *qmi_device_get_path (QmiDevice *self); + +/** + * qmi_device_get_path_display: + * @self: a #QmiDevice. + * + * Get the system path of the underlying QMI device in UTF-8. + * + * Returns: UTF-8 encoded system path of the device. + * + * Since: 1.0 + */ +const gchar *qmi_device_get_path_display (QmiDevice *self); + +/** + * qmi_device_get_wwan_iface: + * @self: a #QmiDevice. + * + * Get the WWAN interface name associated with this /dev/cdc-wdm control port. + * This value will be loaded every time it's asked for it. + * + * Returns: UTF-8 encoded network interface name, or %NULL if not available. + * + * Since: 1.14 + */ +const gchar *qmi_device_get_wwan_iface (QmiDevice *self); + +/** + * qmi_device_is_open: + * @self: a #QmiDevice. + * + * Checks whether the #QmiDevice is open for I/O. + * + * Returns: %TRUE if @self is open, %FALSE otherwise. + * + * Since: 1.0 + */ +gboolean qmi_device_is_open (QmiDevice *self); /** * QmiDeviceOpenFlags: @@ -97,11 +240,13 @@ gboolean qmi_device_is_open (QmiDevice *self); * @QMI_DEVICE_OPEN_FLAGS_NET_RAW_IP: set network port to "raw IP" mode; mutally exclusive with @QMI_DEVICE_OPEN_FLAGS_NET_802_3 * @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 * @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 - * @QMI_DEVICE_OPEN_FLAGS_PROXY: Try to open the port through the 'qmi-proxy'. - * @QMI_DEVICE_OPEN_FLAGS_MBIM: open an MBIM port with QMUX tunneling service. - * @QMI_DEVICE_OPEN_FLAGS_AUTO: open a port either in QMI or MBIM mode, depending on device driver. + * @QMI_DEVICE_OPEN_FLAGS_PROXY: Try to open the port through the 'qmi-proxy'. Since: 1.8. + * @QMI_DEVICE_OPEN_FLAGS_MBIM: open an MBIM port with QMUX tunneling service. Since: 1.16. + * @QMI_DEVICE_OPEN_FLAGS_AUTO: open a port either in QMI or MBIM mode, depending on device driver. Since: 1.18. * * Flags to specify which actions to be performed when the device is open. + * + * Since: 1.0 */ typedef enum { QMI_DEVICE_OPEN_FLAGS_NONE = 0, @@ -116,39 +261,162 @@ typedef enum { QMI_DEVICE_OPEN_FLAGS_AUTO = 1 << 8, } QmiDeviceOpenFlags; -void qmi_device_open (QmiDevice *self, - QmiDeviceOpenFlags flags, - guint timeout, - GCancellable *cancellable, - GAsyncReadyCallback callback, - gpointer user_data); -gboolean qmi_device_open_finish (QmiDevice *self, - GAsyncResult *res, - GError **error); +/** + * qmi_device_open_flags_build_string_from_mask: + * + * Since: 1.0 + */ +/** + * qmi_device_open: + * @self: a #QmiDevice. + * @flags: mask of #QmiDeviceOpenFlags specifying how the device should be opened. + * @timeout: maximum time, in seconds, to wait for the device to be opened. + * @cancellable: optional #GCancellable object, #NULL to ignore. + * @callback: a #GAsyncReadyCallback to call when the operation is finished. + * @user_data: the data to pass to callback function. + * + * Asynchronously opens a #QmiDevice for I/O. + * + * When the operation is finished @callback will be called. You can then call + * qmi_device_open_finish() to get the result of the operation. + * + * Since: 1.0 + */ +void qmi_device_open (QmiDevice *self, + QmiDeviceOpenFlags flags, + guint timeout, + GCancellable *cancellable, + GAsyncReadyCallback callback, + gpointer user_data); + +/** + * qmi_device_open_finish: + * @self: a #QmiDevice. + * @res: a #GAsyncResult. + * @error: Return location for error or %NULL. + * + * Finishes an asynchronous open operation started with qmi_device_open(). + * + * Returns: %TRUE if successful, %FALSE if @error is set. + * + * Since: 1.0 + */ +gboolean qmi_device_open_finish (QmiDevice *self, + GAsyncResult *res, + GError **error); + +/** + * qmi_device_close: + * @self: a #QmiDevice + * @error: Return location for error or %NULL. + * + * Synchronously closes a #QmiDevice, preventing any further I/O. + * + * If this device was opened with @QMI_DEVICE_OPEN_FLAGS_MBIM, this + * operation will not wait for the response of the underlying MBIM + * close sequence. + * + * Closing a #QmiDevice multiple times will not return an error. + * + * Returns: %TRUE if successful, %FALSE if @error is set. + * + * Since: 1.0 + * Deprecated: 1.18: Use qmi_device_close_async() instead. + */ G_DEPRECATED -gboolean qmi_device_close (QmiDevice *self, - GError **error); - -void qmi_device_close_async (QmiDevice *self, - guint timeout, - GCancellable *cancellable, - GAsyncReadyCallback callback, - gpointer user_data); -gboolean qmi_device_close_finish (QmiDevice *self, - GAsyncResult *res, - GError **error); - -void qmi_device_allocate_client (QmiDevice *self, - QmiService service, - guint8 cid, - guint timeout, - GCancellable *cancellable, - GAsyncReadyCallback callback, - gpointer user_data); -QmiClient *qmi_device_allocate_client_finish (QmiDevice *self, - GAsyncResult *res, - GError **error); +gboolean qmi_device_close (QmiDevice *self, + GError **error); + +/** + * qmi_device_close_async: + * @self: a #QmiDevice. + * @timeout: maximum time, in seconds, to wait for the device to be closed. + * @cancellable: a #GCancellable, or %NULL. + * @callback: a #GAsyncReadyCallback to call when the operation is finished. + * @user_data: the data to pass to callback function. + * + * Asynchronously closes a #QmiDevice, preventing any further I/O. + * + * If this device was opened with @QMI_DEVICE_OPEN_FLAGS_MBIM, this + * operation will wait for the response of the underlying MBIM close + * sequence. + * + * Closing a #QmiDevice multiple times will not return an error. + * + * When the operation is finished @callback will be called. You can then call + * qmi_device_close_finish() to get the result of the operation. + * + * Since: 1.18 + */ +void qmi_device_close_async (QmiDevice *self, + guint timeout, + GCancellable *cancellable, + GAsyncReadyCallback callback, + gpointer user_data); + +/** + * qmi_device_close_finish: + * @self: a #QmiDevice. + * @res: a #GAsyncResult. + * @error: Return location for error or %NULL. + * + * Finishes an operation started with qmi_device_close_async(). + * + * Returns: %TRUE if successful, %FALSE if @error is set. + * + * Since: 1.18 + */ +gboolean qmi_device_close_finish (QmiDevice *self, + GAsyncResult *res, + GError **error); + +/** + * qmi_device_allocate_client: + * @self: a #QmiDevice. + * @service: a valid #QmiService. + * @cid: a valid client ID, or #QMI_CID_NONE. + * @timeout: maximum time to wait. + * @cancellable: optional #GCancellable object, #NULL to ignore. + * @callback: a #GAsyncReadyCallback to call when the operation is finished. + * @user_data: the data to pass to callback function. + * + * Asynchronously allocates a new #QmiClient in @self. + * + * If #QMI_CID_NONE is given in @cid, a new client ID will be allocated; + * otherwise a client with the given @cid will be generated. + * + * When the operation is finished @callback will be called. You can then call + * qmi_device_allocate_client_finish() to get the result of the operation. + * + * Note: Clients for the #QMI_SERVICE_CTL cannot be created with this method; + * instead get/peek the implicit one from @self. + * + * Since: 1.0 + */ +void qmi_device_allocate_client (QmiDevice *self, + QmiService service, + guint8 cid, + guint timeout, + GCancellable *cancellable, + GAsyncReadyCallback callback, + gpointer user_data); + +/** + * qmi_device_allocate_client_finish: + * @self: a #QmiDevice. + * @res: a #GAsyncResult. + * @error: Return location for error or %NULL. + * + * Finishes an operation started with qmi_device_allocate_client(). + * + * Returns: a newly allocated #QmiClient, or #NULL if @error is set. + * + * Since: 1.0 + */ +QmiClient *qmi_device_allocate_client_finish (QmiDevice *self, + GAsyncResult *res, + GError **error); /** * QmiDeviceReleaseClientFlags: @@ -156,56 +424,197 @@ QmiClient *qmi_device_allocate_client_finish (QmiDevice *self, * @QMI_DEVICE_RELEASE_CLIENT_FLAGS_RELEASE_CID: Release the CID when releasing the client. * * Flags to specify which actions to be performed when releasing the client. + * + * Since: 1.0 */ typedef enum { QMI_DEVICE_RELEASE_CLIENT_FLAGS_NONE = 0, QMI_DEVICE_RELEASE_CLIENT_FLAGS_RELEASE_CID = 1 << 0 } QmiDeviceReleaseClientFlags; -void qmi_device_release_client (QmiDevice *self, - QmiClient *client, - QmiDeviceReleaseClientFlags flags, - guint timeout, - GCancellable *cancellable, - GAsyncReadyCallback callback, - gpointer user_data); -gboolean qmi_device_release_client_finish (QmiDevice *self, - GAsyncResult *res, - GError **error); - -void qmi_device_set_instance_id (QmiDevice *self, - guint8 instance_id, - guint timeout, - GCancellable *cancellable, - GAsyncReadyCallback callback, - gpointer user_data); -gboolean qmi_device_set_instance_id_finish (QmiDevice *self, - GAsyncResult *res, - guint16 *link_id, - GError **error); +/** + * qmi_device_release_client_flags_build_string_from_mask: + * + * Since: 1.0 + */ -G_DEPRECATED -void qmi_device_command (QmiDevice *self, - QmiMessage *message, - guint timeout, - GCancellable *cancellable, - GAsyncReadyCallback callback, - gpointer user_data); -G_DEPRECATED -QmiMessage *qmi_device_command_finish (QmiDevice *self, - GAsyncResult *res, - GError **error); - -void qmi_device_command_full (QmiDevice *self, - QmiMessage *message, - QmiMessageContext *message_context, - guint timeout, - GCancellable *cancellable, - GAsyncReadyCallback callback, - gpointer user_data); -QmiMessage *qmi_device_command_full_finish (QmiDevice *self, - GAsyncResult *res, - GError **error); +/** + * qmi_device_release_client: + * @self: a #QmiDevice. + * @client: the #QmiClient to release. + * @flags: mask of #QmiDeviceReleaseClientFlags specifying how the client should be released. + * @timeout: maximum time to wait. + * @cancellable: optional #GCancellable object, #NULL to ignore. + * @callback: a #GAsyncReadyCallback to call when the operation is finished. + * @user_data: the data to pass to callback function. + * + * Asynchronously releases the #QmiClient from the #QmiDevice. + * + * Once the #QmiClient has been released, it cannot be used any more to + * perform operations. + * + * + * When the operation is finished @callback will be called. You can then call + * qmi_device_release_client_finish() to get the result of the operation. + * + * Since: 1.0 + */ +void qmi_device_release_client (QmiDevice *self, + QmiClient *client, + QmiDeviceReleaseClientFlags flags, + guint timeout, + GCancellable *cancellable, + GAsyncReadyCallback callback, + gpointer user_data); + +/** + * qmi_device_release_client_finish: + * @self: a #QmiDevice. + * @res: a #GAsyncResult. + * @error: Return location for error or %NULL. + * + * Finishes an operation started with qmi_device_release_client(). + * + * Note that even if the release operation returns an error, the client should + * anyway be considered released, and shouldn't be used afterwards. + * + * Returns: %TRUE if successful, or #NULL if @error is set. + * + * Since: 1.0 + */ +gboolean qmi_device_release_client_finish (QmiDevice *self, + GAsyncResult *res, + GError **error); + +/** + * qmi_device_set_instance_id: + * @self: a #QmiDevice. + * @instance_id: the instance ID. + * @timeout: maximum time to wait. + * @cancellable: optional #GCancellable object, #NULL to ignore. + * @callback: a #GAsyncReadyCallback to call when the operation is finished. + * @user_data: the data to pass to callback function. + * + * Sets the instance ID of the #QmiDevice. + * + * When the operation is finished @callback will be called. You can then call + * qmi_device_set_instance_id_finish() to get the result of the operation. + * + * Since: 1.0 + */ +void qmi_device_set_instance_id (QmiDevice *self, + guint8 instance_id, + guint timeout, + GCancellable *cancellable, + GAsyncReadyCallback callback, + gpointer user_data); + +/** + * qmi_device_set_instance_id_finish: + * @self: a #QmiDevice. + * @res: a #GAsyncResult. + * @link_id: a placeholder for the output #guint16, or #NULL if not required. + * @error: Return location for error or %NULL. + * + * Finishes an operation started with qmi_device_set_instance_id(). + * + * Returns: %TRUE if successful, %FALSE if @error is set. + * + * Since: 1.0 + */ +gboolean qmi_device_set_instance_id_finish (QmiDevice *self, + GAsyncResult *res, + guint16 *link_id, + GError **error); + +/** + * qmi_device_command: + * @self: a #QmiDevice. + * @message: the message to send. + * @timeout: maximum time, in seconds, to wait for the response. + * @cancellable: a #GCancellable, or %NULL. + * @callback: a #GAsyncReadyCallback to call when the operation is finished. + * @user_data: the data to pass to callback function. + * + * Asynchronously sends a generic #QmiMessage to the device with no context. + * + * When the operation is finished @callback will be called. You can then call + * qmi_device_command_finish() to get the result of the operation. + * + * Since: 1.0 + * Deprecated: 1.18: Use qmi_device_command_full() instead. + */ +G_DEPRECATED_FOR (qmi_device_command_full) +void qmi_device_command (QmiDevice *self, + QmiMessage *message, + guint timeout, + GCancellable *cancellable, + GAsyncReadyCallback callback, + gpointer user_data); + +/** + * qmi_device_command_finish: + * @self: a #QmiDevice. + * @res: a #GAsyncResult. + * @error: Return location for error or %NULL. + * + * Finishes an operation started with qmi_device_command(). + * + * Returns: a #QmiMessage response, or #NULL if @error is set. The returned value should be freed with qmi_message_unref(). + * + * Since: 1.0 + * Deprecated: 1.18. Use qmi_device_command_full_finish() instead. + */ +G_DEPRECATED_FOR (qmi_device_command_full_finish) +QmiMessage *qmi_device_command_finish (QmiDevice *self, + GAsyncResult *res, + GError **error); + +/** + * qmi_device_command_full: + * @self: a #QmiDevice. + * @message: the message to send. + * @message_context: the context of the message. + * @timeout: maximum time, in seconds, to wait for the response. + * @cancellable: a #GCancellable, or %NULL. + * @callback: a #GAsyncReadyCallback to call when the operation is finished. + * @user_data: the data to pass to callback function. + * + * Asynchronously sends a #QmiMessage to the device. + * + * The message will be processed according to the specific @message_context + * given. + * + * When the operation is finished @callback will be called. You can then call + * qmi_device_command_full_finish() to get the result of the operation. + * + * If no @context given, the behavior is the same as qmi_device_command(). + * + * Since: 1.18 + */ +void qmi_device_command_full (QmiDevice *self, + QmiMessage *message, + QmiMessageContext *message_context, + guint timeout, + GCancellable *cancellable, + GAsyncReadyCallback callback, + gpointer user_data); + +/** + * qmi_device_command_full_finish: + * @self: a #QmiDevice. + * @res: a #GAsyncResult. + * @error: Return location for error or %NULL. + * + * Finishes an operation started with qmi_device_command_full(). + * + * Returns: a #QmiMessage response, or #NULL if @error is set. The returned value should be freed with qmi_message_unref(). + * + * Since: 1.18 + */ +QmiMessage *qmi_device_command_full_finish (QmiDevice *self, + GAsyncResult *res, + GError **error); /** * QmiDeviceServiceVersionInfo: @@ -214,21 +623,52 @@ QmiMessage *qmi_device_command_full_finish (QmiDevice *self, * @minor_version: minor version of the service. * * Version information for a service. + * + * Since: 1.6 */ typedef struct { QmiService service; - guint16 major_version; - guint16 minor_version; + guint16 major_version; + guint16 minor_version; } QmiDeviceServiceVersionInfo; -void qmi_device_get_service_version_info (QmiDevice *self, - guint timeout, - GCancellable *cancellable, - GAsyncReadyCallback callback, - gpointer user_data); -GArray *qmi_device_get_service_version_info_finish (QmiDevice *self, - GAsyncResult *res, - GError **error); +/** + * qmi_device_get_service_version_info: + * @self: a #QmiDevice. + * @timeout: maximum time to wait for the method to complete, in seconds. + * @cancellable: a #GCancellable or %NULL. + * @callback: a #GAsyncReadyCallback to call when the request is satisfied. + * @user_data: user data to pass to @callback. + * + * Asynchronously requests the service version information of the device. + * + * When the operation is finished, @callback will be invoked in the thread-default main loop of the thread you are calling this method from. + * + * You can then call qmi_device_get_service_version_info_finish() to get the result of the operation. + * + * Since: 1.6 + */ +void qmi_device_get_service_version_info (QmiDevice *self, + guint timeout, + GCancellable *cancellable, + GAsyncReadyCallback callback, + gpointer user_data); + +/** + * qmi_device_get_service_version_info_finish: + * @self: a #QmiDevice. + * @res: a #GAsyncResult. + * @error: Return location for error or %NULL. + * + * Finishes an operation started with qmi_device_get_service_version_info(). + * + * Returns: a #GArray of #QmiDeviceServiceVersionInfo elements, or #NULL if @error is set. The returned value should be freed with g_array_unref(). + * + * Since: 1.6 + */ +GArray *qmi_device_get_service_version_info_finish (QmiDevice *self, + GAsyncResult *res, + GError **error); /** * QmiDeviceExpectedDataFormat: * @QMI_DEVICE_EXPECTED_DATA_FORMAT_UNKNOWN: Unknown. @@ -236,6 +676,8 @@ GArray *qmi_device_get_service_version_info_finish (QmiDevice *self, * @QMI_DEVICE_EXPECTED_DATA_FORMAT_RAW_IP: Raw IP. * * Data format expected by the kernel. + * + * Since: 1.14 */ typedef enum { QMI_DEVICE_EXPECTED_DATA_FORMAT_UNKNOWN, @@ -243,11 +685,46 @@ typedef enum { QMI_DEVICE_EXPECTED_DATA_FORMAT_RAW_IP, } QmiDeviceExpectedDataFormat; -QmiDeviceExpectedDataFormat qmi_device_get_expected_data_format (QmiDevice *self, - GError **error); -gboolean qmi_device_set_expected_data_format (QmiDevice *self, - QmiDeviceExpectedDataFormat format, - GError **error); +/** + * qmi_device_expected_data_format_get_string: + * + * Since: 1.14 + */ + +/** + * qmi_device_get_expected_data_format: + * @self: a #QmiDevice. + * @error: Return location for error or %NULL. + * + * Retrieves the data format currently expected by the kernel in the network + * interface. + * + * If @QMI_DEVICE_EXPECTED_DATA_FORMAT_UNKNOWN is returned, the user should assume + * that 802.3 is the expected format. + * + * Returns: a valid #QmiDeviceExpectedDataFormat, or @QMI_DEVICE_EXPECTED_DATA_FORMAT_UNKNOWN if @error is set. + * + * Since: 1.14 + */ +QmiDeviceExpectedDataFormat qmi_device_get_expected_data_format (QmiDevice *self, + GError **error); + +/** + * qmi_device_set_expected_data_format: + * @self: a #QmiDevice. + * @format: a known #QmiDeviceExpectedDataFormat. + * @error: Return location for error or %NULL. + * + * Configures the data format currently expected by the kernel in the network + * interface. + * + * Returns: %TRUE if successful, or #NULL if @error is set. + * + * Since: 1.14 + */ +gboolean qmi_device_set_expected_data_format (QmiDevice *self, + QmiDeviceExpectedDataFormat format, + GError **error); G_END_DECLS |