libmm-glib,simple: `MMModemSimple' is now a real object

Not just a typedef of the gdbus-codegen generated `MmGdbusModemSimple'.

1 files changed, 182 insertions, 33 deletions

diff --git a/libmm-glib/mm-modem-simple.c b/libmm-glib/mm-modem-simple.c
index 4d5c5645..e9d09b2f 100644
--- a/libmm-glib/mm-modem-simple.c
+++ b/libmm-glib/mm-modem-simple.c
@@ -17,7 +17,8 @@
  * Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
  * Boston, MA 02110-1301 USA.
  *
- * Copyright (C) 2011 Aleksander Morgado <aleksander@gnu.org>
+ * Copyright (C) 2011 - 2012 Aleksander Morgado <aleksander@gnu.org>
+ * Copyright (C) 2012 Google, Inc.
  */
 
 #include <gio/gio.h>
@@ -26,6 +27,21 @@
 #include "mm-modem-simple.h"
 
 /**
+ * SECTION: mm-modem-simple
+ * @title: MMModemSimple
+ * @short_description: The Simple interface
+ *
+ * The #MMModemSimple is an object providing access to the methods, signals and
+ * properties of the Simple interface.
+ *
+ * The Simple interface is exposed on modems which are not in %MM_MODEM_STATE_FAILED state.
+ */
+
+G_DEFINE_TYPE (MMModemSimple, mm_modem_simple, MM_GDBUS_TYPE_MODEM_SIMPLE_PROXY)
+
+/*****************************************************************************/
+
+/**
  * mm_modem_simple_get_path:
  * @self: A #MMModemSimple.
  *
@@ -36,7 +52,7 @@
 const gchar *
 mm_modem_simple_get_path (MMModemSimple *self)
 {
-    g_return_val_if_fail (G_IS_DBUS_PROXY (self), NULL);
+    g_return_val_if_fail (MM_IS_MODEM_SIMPLE (self), NULL);
 
     RETURN_NON_EMPTY_CONSTANT_STRING (
         g_dbus_proxy_get_object_path (G_DBUS_PROXY (self)));
@@ -55,7 +71,7 @@ mm_modem_simple_dup_path (MMModemSimple *self)
 {
     gchar *value;
 
-    g_return_val_if_fail (G_IS_DBUS_PROXY (self), NULL);
+    g_return_val_if_fail (MM_IS_MODEM_SIMPLE (self), NULL);
 
     g_object_get (G_OBJECT (self),
                   "g-object-path", &value,
@@ -63,6 +79,8 @@ mm_modem_simple_dup_path (MMModemSimple *self)
     RETURN_NON_EMPTY_STRING (value);
 }
 
+/*****************************************************************************/
+
 typedef struct {
     GSimpleAsyncResult *result;
     GCancellable *cancellable;
@@ -78,12 +96,22 @@ connect_context_complete_and_free (ConnectContext *ctx)
     g_slice_free (ConnectContext, ctx);
 }
 
+/**
+ * mm_modem_simple_connect_finish:
+ * @self: A #MMModemSimple.
+ * @res: The #GAsyncResult obtained from the #GAsyncReadyCallback passed to mm_modem_simple_connect().
+ * @error: Return location for error or %NULL.
+ *
+ * Finishes an operation started with mm_modem_simple_connect().
+ *
+ * Returns: (transfer full): A #MMBearer, or %FALSE if @error is set. The returned value must be freed with g_object_ref().
+ */
 MMBearer *
 mm_modem_simple_connect_finish (MMModemSimple *self,
                                 GAsyncResult *res,
                                 GError **error)
 {
-    g_return_val_if_fail (MM_GDBUS_IS_MODEM_SIMPLE (self), NULL);
+    g_return_val_if_fail (MM_IS_MODEM_SIMPLE (self), NULL);
 
     if (g_simple_async_result_propagate_error (G_SIMPLE_ASYNC_RESULT (res), error))
         return NULL;
@@ -118,7 +146,7 @@ simple_connect_ready (MMModemSimple *self,
     GError *error = NULL;
     gchar *bearer_path = NULL;
 
-    if (!mm_gdbus_modem_simple_call_connect_finish (self,
+    if (!mm_gdbus_modem_simple_call_connect_finish (MM_GDBUS_MODEM_SIMPLE (self),
                                                     &bearer_path,
                                                     res,
                                                     &error)) {
@@ -138,6 +166,21 @@ simple_connect_ready (MMModemSimple *self,
         ctx);
 }
 
+/**
+ * mm_modem_simple_connect:
+ * @self: A #MMModemSimple.
+ * @properties: (transfer none): A #MMSimpleConnectProperties bundle.
+ * @cancellable: (allow-none): A #GCancellable or %NULL.
+ * @callback: A #GAsyncReadyCallback to call when the request is satisfied or %NULL.
+ * @user_data: User data to pass to @callback.
+ *
+ * Asynchronously requests to connect the modem using the given @properties.
+ *
+ * When the operation is finished, @callback will be invoked in the <link linkend="g-main-context-push-thread-default">thread-default main loop</link> of the thread you are calling this method from.
+ * You can then call mm_modem_simple_connect_finish() to get the result of the operation.
+ *
+ * See mm_modem_simple_connect_sync() for the synchronous, blocking version of this method.
+ */
 void
 mm_modem_simple_connect (MMModemSimple *self,
                          MMSimpleConnectProperties *properties,
@@ -148,7 +191,7 @@ mm_modem_simple_connect (MMModemSimple *self,
     ConnectContext *ctx;
     GVariant *variant;
 
-    g_return_if_fail (MM_GDBUS_IS_MODEM_SIMPLE (self));
+    g_return_if_fail (MM_IS_MODEM_SIMPLE (self));
 
     ctx = g_slice_new0 (ConnectContext);
     ctx->result = g_simple_async_result_new (G_OBJECT (self),
@@ -160,7 +203,7 @@ mm_modem_simple_connect (MMModemSimple *self,
 
     variant = mm_simple_connect_properties_get_dictionary (properties);
     mm_gdbus_modem_simple_call_connect (
-        self,
+        MM_GDBUS_MODEM_SIMPLE (self),
         variant,
         cancellable,
         (GAsyncReadyCallback)simple_connect_ready,
@@ -169,6 +212,20 @@ mm_modem_simple_connect (MMModemSimple *self,
     g_variant_unref (variant);
 }
 
+/**
+ * mm_modem_simple_connect_sync:
+ * @self: A #MMModemSimple.
+ * @properties: (transfer none): A #MMSimpleConnectProperties bundle.
+ * @cancellable: (allow-none): A #GCancellable or %NULL.
+ * @error: Return location for error or %NULL.
+ *
+ * Synchronously requests to connect the modem using the given @properties.
+ *
+ * The calling thread is blocked until a reply is received. See mm_modem_simple_connect()
+ * for the asynchronous version of this method.
+ *
+ * Returns: (transfer full): A #MMBearer, or %FALSE if @error is set. The returned value must be freed with g_object_ref().
+ */
 MMBearer *
 mm_modem_simple_connect_sync (MMModemSimple *self,
                               MMSimpleConnectProperties *properties,
@@ -179,10 +236,10 @@ mm_modem_simple_connect_sync (MMModemSimple *self,
     gchar *bearer_path = NULL;
     GVariant *variant;
 
-    g_return_val_if_fail (MM_GDBUS_IS_MODEM_SIMPLE (self), NULL);
+    g_return_val_if_fail (MM_IS_MODEM_SIMPLE (self), NULL);
 
     variant = mm_simple_connect_properties_get_dictionary (properties);
-    mm_gdbus_modem_simple_call_connect_sync (self,
+    mm_gdbus_modem_simple_call_connect_sync (MM_GDBUS_MODEM_SIMPLE (self),
                                              variant,
                                              &bearer_path,
                                              cancellable,
@@ -204,46 +261,99 @@ mm_modem_simple_connect_sync (MMModemSimple *self,
     return bearer;
 }
 
+/*****************************************************************************/
+
+/**
+ * mm_modem_simple_disconnect_finish:
+ * @self: A #MMModemSimple.
+ * @res: The #GAsyncResult obtained from the #GAsyncReadyCallback passed to mm_modem_simple_disconnect().
+ * @error: Return location for error or %NULL.
+ *
+ * Finishes an operation started with mm_modem_simple_disconnect().
+ *
+ * Returns: %TRUE if the modem is successfully disconnected, %FALSE if @error is set.
+ */
+gboolean
+mm_modem_simple_disconnect_finish (MMModemSimple *self,
+                                   GAsyncResult *res,
+                                   GError **error)
+{
+    g_return_val_if_fail (MM_IS_MODEM_SIMPLE (self), FALSE);
+
+    return mm_gdbus_modem_simple_call_disconnect_finish (MM_GDBUS_MODEM_SIMPLE (self), res, error);
+}
+
+/**
+ * mm_modem_simple_disconnect:
+ * @self: A #MMModemSimple.
+ * @bearer: Path of the bearer to disconnect, or %NULL to disconnect all connected bearers.
+ * @cancellable: (allow-none): A #GCancellable or %NULL.
+ * @callback: A #GAsyncReadyCallback to call when the request is satisfied or %NULL.
+ * @user_data: User data to pass to @callback.
+ *
+ * Asynchronously requests to disconnect the modem.
+ *
+ * When the operation is finished, @callback will be invoked in the <link linkend="g-main-context-push-thread-default">thread-default main loop</link> of the thread you are calling this method from.
+ * You can then call mm_modem_simple_disconnect_finish() to get the result of the operation.
+ *
+ * See mm_modem_simple_disconnect_sync() for the synchronous, blocking version of this method.
+ */
 void
 mm_modem_simple_disconnect (MMModemSimple *self,
-                            const gchar *bearer_path,
+                            const gchar *bearer,
                             GCancellable *cancellable,
                             GAsyncReadyCallback callback,
                             gpointer user_data)
 {
-    g_return_if_fail (MM_GDBUS_IS_MODEM_SIMPLE (self));
+    g_return_if_fail (MM_IS_MODEM_SIMPLE (self));
 
-    mm_gdbus_modem_simple_call_disconnect (self,
-                                           bearer_path ? bearer_path : "/",
+    mm_gdbus_modem_simple_call_disconnect (MM_GDBUS_MODEM_SIMPLE (self),
+                                           bearer ? bearer : "/",
                                            cancellable,
                                            callback,
                                            user_data);
 }
 
-gboolean
-mm_modem_simple_disconnect_finish (MMModemSimple *self,
-                                   GAsyncResult *res,
-                                   GError **error)
-{
-    g_return_val_if_fail (MM_GDBUS_IS_MODEM_SIMPLE (self), FALSE);
-
-    return mm_gdbus_modem_simple_call_disconnect_finish (self, res, error);
-}
-
+/**
+ * mm_modem_simple_disconnect_sync:
+ * @self: A #MMModemSimple.
+ * @bearer: Path of the bearer to disconnect, or %NULL to disconnect all connected bearers.
+ * @cancellable: (allow-none): A #GCancellable or %NULL.
+ * @error: Return location for error or %NULL.
+ *
+ * Synchronously requests to disconnect the modem.
+ *
+ * The calling thread is blocked until a reply is received. See mm_modem_simple_disconnect()
+ * for the asynchronous version of this method.
+ *
+ * Returns: %TRUE if the modem is successfully disconnected, %FALSE if @error is set.
+ */
 gboolean
 mm_modem_simple_disconnect_sync (MMModemSimple *self,
-                                 const gchar *bearer_path,
+                                 const gchar *bearer,
                                  GCancellable *cancellable,
                                  GError **error)
 {
-    g_return_val_if_fail (MM_GDBUS_IS_MODEM_SIMPLE (self), FALSE);
+    g_return_val_if_fail (MM_IS_MODEM_SIMPLE (self), FALSE);
 
-    return mm_gdbus_modem_simple_call_disconnect_sync (self,
-                                                       bearer_path ? bearer_path : "/",
+    return mm_gdbus_modem_simple_call_disconnect_sync (MM_GDBUS_MODEM_SIMPLE (self),
+                                                       bearer ? bearer : "/",
                                                        cancellable,
                                                        error);
 }
 
+/*****************************************************************************/
+
+/**
+ * mm_modem_simple_get_status_finish:
+ * @self: A #MMModemSimple.
+ * @res: The #GAsyncResult obtained from the #GAsyncReadyCallback passed to mm_modem_simple_connect().
+ * @error: Return location for error or %NULL.
+ *
+ * Finishes an operation started with mm_modem_simple_get_status().
+ *
+ * Returns: (transfer full): A #MMSimpleStatus, or %FALSE if @error is set. The returned value must be freed with g_object_ref().
+ */
 MMSimpleStatus *
 mm_modem_simple_get_status_finish (MMModemSimple *self,
                                    GAsyncResult *res,
@@ -252,9 +362,9 @@ mm_modem_simple_get_status_finish (MMModemSimple *self,
     MMSimpleStatus *status;
     GVariant *dictionary = NULL;
 
-    g_return_val_if_fail (MM_GDBUS_IS_MODEM_SIMPLE (self), NULL);
+    g_return_val_if_fail (MM_IS_MODEM_SIMPLE (self), NULL);
 
-    if (!mm_gdbus_modem_simple_call_get_status_finish (self, &dictionary, res, error))
+    if (!mm_gdbus_modem_simple_call_get_status_finish (MM_GDBUS_MODEM_SIMPLE (self), &dictionary, res, error))
         return NULL;
 
     status = mm_simple_status_new_from_dictionary (dictionary, error);
@@ -262,20 +372,47 @@ mm_modem_simple_get_status_finish (MMModemSimple *self,
     return status;
 }
 
+/**
+ * mm_modem_simple_get_status:
+ * @self: A #MMModemSimple.
+ * @cancellable: (allow-none): A #GCancellable or %NULL.
+ * @callback: A #GAsyncReadyCallback to call when the request is satisfied or %NULL.
+ * @user_data: User data to pass to @callback.
+ *
+ * Asynchronously requests a compilation of the status of the modem.
+ *
+ * When the operation is finished, @callback will be invoked in the <link linkend="g-main-context-push-thread-default">thread-default main loop</link> of the thread you are calling this method from.
+ * You can then call mm_modem_simple_get_status_finish() to get the result of the operation.
+ *
+ * See mm_modem_simple_get_status_sync() for the synchronous, blocking version of this method.
+ */
 void
 mm_modem_simple_get_status (MMModemSimple *self,
                             GCancellable *cancellable,
                             GAsyncReadyCallback callback,
                             gpointer user_data)
 {
-    g_return_if_fail (MM_GDBUS_IS_MODEM_SIMPLE (self));
+    g_return_if_fail (MM_IS_MODEM_SIMPLE (self));
 
-    mm_gdbus_modem_simple_call_get_status (self,
+    mm_gdbus_modem_simple_call_get_status (MM_GDBUS_MODEM_SIMPLE (self),
                                            cancellable,
                                            callback,
                                            user_data);
 }
 
+/**
+ * mm_modem_simple_get_status_sync:
+ * @self: A #MMModemSimple.
+ * @cancellable: (allow-none): A #GCancellable or %NULL.
+ * @error: Return location for error or %NULL.
+ *
+ * Synchronously requests a compilation of the status of the modem.
+ *
+ * The calling thread is blocked until a reply is received. See mm_modem_simple_get_status()
+ * for the asynchronous version of this method.
+ *
+ * Returns: (transfer full): A #MMSimpleStatus, or %FALSE if @error is set. The returned value must be freed with g_object_ref().
+ */
 MMSimpleStatus *
 mm_modem_simple_get_status_sync (MMModemSimple *self,
                                  GCancellable *cancellable,
@@ -284,12 +421,24 @@ mm_modem_simple_get_status_sync (MMModemSimple *self,
     MMSimpleStatus *status;
     GVariant *dictionary = NULL;
 
-    g_return_val_if_fail (MM_GDBUS_IS_MODEM_SIMPLE (self), NULL);
+    g_return_val_if_fail (MM_IS_MODEM_SIMPLE (self), NULL);
 
-    if (!mm_gdbus_modem_simple_call_get_status_sync (self, &dictionary, cancellable, error))
+    if (!mm_gdbus_modem_simple_call_get_status_sync (MM_GDBUS_MODEM_SIMPLE (self), &dictionary, cancellable, error))
         return NULL;
 
     status = mm_simple_status_new_from_dictionary (dictionary, error);
     g_variant_unref (dictionary);
     return status;
 }
+
+/*****************************************************************************/
+
+static void
+mm_modem_simple_init (MMModemSimple *self)
+{
+}
+
+static void
+mm_modem_simple_class_init (MMModemSimpleClass *modem_class)
+{
+}