libmm-glib,cdma: `MMModemCdma' is now a real object

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

1 files changed, 127 insertions, 48 deletions

diff --git a/libmm-glib/mm-modem-cdma.c b/libmm-glib/mm-modem-cdma.c
index 9cf066a59..d86db3172 100644
--- a/libmm-glib/mm-modem-cdma.c
+++ b/libmm-glib/mm-modem-cdma.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,22 @@
 #include "mm-modem-cdma.h"
 
 /**
+ * SECTION: mm-modem-cdma
+ * @title: MMModemCdma
+ * @short_description: The CDMA interface
+ *
+ * The #MMModemCdma is an object providing access to the methods, signals and
+ * properties of the CDMA interface.
+ *
+ * The CDMA interface is exposed whenever a modem has CDMA capabilities
+ * (%MM_MODEM_CAPABILITY_CDMA_EVDO).
+ */
+
+G_DEFINE_TYPE (MMModemCdma, mm_modem_cdma, MM_GDBUS_TYPE_MODEM_CDMA_PROXY)
+
+/*****************************************************************************/
+
+/**
  * mm_modem_cdma_get_path:
  * @self: A #MMModemCdma.
  *
@@ -36,7 +53,7 @@
 const gchar *
 mm_modem_cdma_get_path (MMModemCdma *self)
 {
-    g_return_val_if_fail (G_IS_DBUS_PROXY (self), NULL);
+    g_return_val_if_fail (MM_IS_MODEM_CDMA (self), NULL);
 
     RETURN_NON_EMPTY_CONSTANT_STRING (
         g_dbus_proxy_get_object_path (G_DBUS_PROXY (self)));
@@ -55,7 +72,7 @@ mm_modem_cdma_dup_path (MMModemCdma *self)
 {
     gchar *value;
 
-    g_return_val_if_fail (G_IS_DBUS_PROXY (self), NULL);
+    g_return_val_if_fail (MM_IS_MODEM_CDMA (self), NULL);
 
     g_object_get (G_OBJECT (self),
                   "g-object-path", &value,
@@ -63,24 +80,29 @@ mm_modem_cdma_dup_path (MMModemCdma *self)
     RETURN_NON_EMPTY_STRING (value);
 }
 
+/*****************************************************************************/
+
 /**
  * mm_modem_cdma_get_meid:
  * @self: A #MMModemCdma.
  *
  * Gets the <ulink url="http://en.wikipedia.org/wiki/MEID">Mobile Equipment Identifier</ulink>,
- * as reported by this #MMModem.
+ * as reported by this #MMModemCdma.
  *
- * <warning>It is only safe to use this function on the thread where @self was constructed. Use mm_modem_cdma_dup_meid() if on another thread.</warning>
+ * <warning>The returned value is only valid until the property changes so
+ * it is only safe to use this function on the thread where
+ * @self was constructed. Use mm_modem_cdma_dup_meid() if on another
+ * thread.</warning>
  *
  * Returns: (transfer none): The MEID, or %NULL if none available.
  */
 const gchar *
 mm_modem_cdma_get_meid (MMModemCdma *self)
 {
-    g_return_val_if_fail (MM_GDBUS_IS_MODEM_CDMA (self), NULL);
+    g_return_val_if_fail (MM_IS_MODEM_CDMA (self), NULL);
 
     RETURN_NON_EMPTY_CONSTANT_STRING (
-        mm_gdbus_modem_cdma_get_meid (self));
+        mm_gdbus_modem_cdma_get_meid (MM_GDBUS_MODEM_CDMA (self)));
 }
 
 /**
@@ -88,39 +110,44 @@ mm_modem_cdma_get_meid (MMModemCdma *self)
  * @self: A #MMModemCdma.
  *
  * Gets a copy of the <ulink url="http://en.wikipedia.org/wiki/MEID">Mobile Equipment Identifier</ulink>,
- * as reported by this #MMModem.
+ * as reported by this #MMModemCdma.
  *
  * Returns: (transfer full): The MEID, or %NULL if none available. The returned value should be freed with g_free().
  */
 gchar *
 mm_modem_cdma_dup_meid (MMModemCdma *self)
 {
-    g_return_val_if_fail (MM_GDBUS_IS_MODEM_CDMA (self), NULL);
+    g_return_val_if_fail (MM_IS_MODEM_CDMA (self), NULL);
 
     RETURN_NON_EMPTY_STRING (
-        mm_gdbus_modem_cdma_dup_meid (self));
+        mm_gdbus_modem_cdma_dup_meid (MM_GDBUS_MODEM_CDMA (self)));
 }
 
+/*****************************************************************************/
+
 /**
  * mm_modem_cdma_get_esn:
  * @self: A #MMModemCdma.
  *
  * Gets the <ulink url="http://en.wikipedia.org/wiki/Electronic_serial_number">Electronic Serial Number</ulink>,
- * as reported by this #MMModem.
+ * as reported by this #MMModemCdma.
  *
  * The ESN is superceded by MEID, but still used in older devices.
  *
- * <warning>It is only safe to use this function on the thread where @self was constructed. Use mm_modem_cdma_dup_esn() if on another thread.</warning>
+ * <warning>The returned value is only valid until the property changes so
+ * it is only safe to use this function on the thread where
+ * @self was constructed. Use mm_modem_cdma_dup_esn() if on another
+ * thread.</warning>
  *
  * Returns: (transfer none): The ESN, or %NULL if none available.
  */
 const gchar *
 mm_modem_cdma_get_esn (MMModemCdma *self)
 {
-    g_return_val_if_fail (MM_GDBUS_IS_MODEM_CDMA (self), NULL);
+    g_return_val_if_fail (MM_IS_MODEM_CDMA (self), NULL);
 
     RETURN_NON_EMPTY_CONSTANT_STRING (
-        mm_gdbus_modem_cdma_get_esn (self));
+        mm_gdbus_modem_cdma_get_esn (MM_GDBUS_MODEM_CDMA (self)));
 }
 
 /**
@@ -128,7 +155,7 @@ mm_modem_cdma_get_esn (MMModemCdma *self)
  * @self: A #MMModemCdma.
  *
  * Gets a copy of the <ulink url="http://en.wikipedia.org/wiki/Electronic_serial_number">Electronic Serial Number</ulink>,
- * as reported by this #MMModem.
+ * as reported by this #MMModemCdma.
  *
  * The ESN is superceded by MEID, but still used in older devices.
  *
@@ -137,12 +164,14 @@ mm_modem_cdma_get_esn (MMModemCdma *self)
 gchar *
 mm_modem_cdma_dup_esn (MMModemCdma *self)
 {
-    g_return_val_if_fail (MM_GDBUS_IS_MODEM_CDMA (self), NULL);
+    g_return_val_if_fail (MM_IS_MODEM_CDMA (self), NULL);
 
     RETURN_NON_EMPTY_STRING (
-        mm_gdbus_modem_cdma_dup_esn (self));
+        mm_gdbus_modem_cdma_dup_esn (MM_GDBUS_MODEM_CDMA (self)));
 }
 
+/*****************************************************************************/
+
 /**
  * mm_modem_cdma_get_sid:
  * @self: A #MMModemCdma.
@@ -156,11 +185,13 @@ mm_modem_cdma_dup_esn (MMModemCdma *self)
 guint
 mm_modem_cdma_get_sid (MMModemCdma *self)
 {
-    g_return_val_if_fail (MM_GDBUS_IS_MODEM_CDMA (self), MM_MODEM_CDMA_SID_UNKNOWN);
+    g_return_val_if_fail (MM_IS_MODEM_CDMA (self), MM_MODEM_CDMA_SID_UNKNOWN);
 
-    return mm_gdbus_modem_cdma_get_sid (self);
+    return mm_gdbus_modem_cdma_get_sid (MM_GDBUS_MODEM_CDMA (self));
 }
 
+/*****************************************************************************/
+
 /**
  * mm_modem_cdma_get_nid:
  * @self: A #MMModemCdma.
@@ -174,11 +205,13 @@ mm_modem_cdma_get_sid (MMModemCdma *self)
 guint
 mm_modem_cdma_get_nid (MMModemCdma *self)
 {
-    g_return_val_if_fail (MM_GDBUS_IS_MODEM_CDMA (self), MM_MODEM_CDMA_NID_UNKNOWN);
+    g_return_val_if_fail (MM_IS_MODEM_CDMA (self), MM_MODEM_CDMA_NID_UNKNOWN);
 
-    return mm_gdbus_modem_cdma_get_nid (self);
+    return mm_gdbus_modem_cdma_get_nid (MM_GDBUS_MODEM_CDMA (self));
 }
 
+/*****************************************************************************/
+
 /**
  * mm_modem_cdma_get_cdma1x_registration_state:
  * @self: A #MMModemCdma.
@@ -190,9 +223,9 @@ mm_modem_cdma_get_nid (MMModemCdma *self)
 MMModemCdmaRegistrationState
 mm_modem_cdma_get_cdma1x_registration_state (MMModemCdma *self)
 {
-    g_return_val_if_fail (MM_GDBUS_IS_MODEM_CDMA (self), MM_MODEM_CDMA_REGISTRATION_STATE_UNKNOWN);
+    g_return_val_if_fail (MM_IS_MODEM_CDMA (self), MM_MODEM_CDMA_REGISTRATION_STATE_UNKNOWN);
 
-    return mm_gdbus_modem_cdma_get_cdma1x_registration_state (self);
+    return mm_gdbus_modem_cdma_get_cdma1x_registration_state (MM_GDBUS_MODEM_CDMA (self));
 }
 
 /**
@@ -206,11 +239,49 @@ mm_modem_cdma_get_cdma1x_registration_state (MMModemCdma *self)
 MMModemCdmaRegistrationState
 mm_modem_cdma_get_evdo_registration_state (MMModemCdma *self)
 {
-    g_return_val_if_fail (MM_GDBUS_IS_MODEM_CDMA (self), MM_MODEM_CDMA_REGISTRATION_STATE_UNKNOWN);
+    g_return_val_if_fail (MM_IS_MODEM_CDMA (self), MM_MODEM_CDMA_REGISTRATION_STATE_UNKNOWN);
 
-    return mm_gdbus_modem_cdma_get_evdo_registration_state (self);
+    return mm_gdbus_modem_cdma_get_evdo_registration_state (MM_GDBUS_MODEM_CDMA (self));
 }
 
+/*****************************************************************************/
+
+/**
+ * mm_modem_cdma_activate_finish:
+ * @self: A #MMModemCdma.
+ * @res: The #GAsyncResult obtained from the #GAsyncReadyCallback passed to mm_modem_cdma_activate().
+ * @error: Return location for error or %NULL.
+ *
+ * Finishes an operation started with mm_modem_cdma_activate().
+ *
+ * Returns: %TRUE if the activation was successful, %FALSE if @error is set.
+ */
+gboolean
+mm_modem_cdma_activate_finish (MMModemCdma *self,
+                               GAsyncResult *res,
+                               GError **error)
+{
+    g_return_val_if_fail (MM_IS_MODEM_CDMA (self), FALSE);
+
+    return mm_gdbus_modem_cdma_call_activate_finish (MM_GDBUS_MODEM_CDMA (self), res, error);
+}
+
+/**
+ * mm_modem_cdma_activate:
+ * @self: A #MMModemCdma.
+ * @carrier: Name of the carrier.
+ * @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 provision the modem for use with a given carrier
+ * using the modem's OTA activation functionality, if any.
+ *
+ * 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_cdma_activate_finish() to get the result of the operation.
+ *
+ * See mm_modem_cdma_activate_sync() for the synchronous, blocking version of this method.
+ */
 void
 mm_modem_cdma_activate (MMModemCdma *self,
                         const gchar *carrier,
@@ -218,37 +289,45 @@ mm_modem_cdma_activate (MMModemCdma *self,
                         GAsyncReadyCallback callback,
                         gpointer user_data)
 {
-    g_return_if_fail (MM_GDBUS_IS_MODEM_CDMA (self));
-
-    mm_gdbus_modem_cdma_call_activate (self,
-                                       carrier,
-                                       cancellable,
-                                       callback,
-                                       user_data);
-}
-
-gboolean
-mm_modem_cdma_activate_finish (MMModemCdma *self,
-                               GAsyncResult *res,
-                               GError **error)
-{
-    g_return_val_if_fail (MM_GDBUS_IS_MODEM_CDMA (self), FALSE);
+    g_return_if_fail (MM_IS_MODEM_CDMA (self));
 
-    return mm_gdbus_modem_cdma_call_activate_finish (self,
-                                                     res,
-                                                     error);
+    mm_gdbus_modem_cdma_call_activate (MM_GDBUS_MODEM_CDMA (self), carrier, cancellable, callback, user_data);
 }
 
+/**
+ * mm_modem_cdma_activate_sync:
+ * @self: A #MMModemCdma.
+ * @carrier: Name of the carrier.
+ * @cancellable: (allow-none): A #GCancellable or %NULL.
+ * @error: Return location for error or %NULL.
+ *
+ * Synchronously requests to provision the modem for use with a given carrier
+ * using the modem's OTA activation functionality, if any.
+ *
+ * The calling thread is blocked until a reply is received. See mm_modem_cdma_activate()
+ * for the asynchronous version of this method.
+ *
+ * Returns: %TRUE if the activation was successful, %FALSE if @error is set.
+ */
 gboolean
 mm_modem_cdma_activate_sync (MMModemCdma *self,
                              const gchar *carrier,
                              GCancellable *cancellable,
                              GError **error)
 {
-    g_return_val_if_fail (MM_GDBUS_IS_MODEM_CDMA (self), FALSE);
+    g_return_val_if_fail (MM_IS_MODEM_CDMA (self), FALSE);
 
-    return mm_gdbus_modem_cdma_call_activate_sync (self,
-                                                   carrier,
-                                                   cancellable,
-                                                   error);
+    return mm_gdbus_modem_cdma_call_activate_sync (MM_GDBUS_MODEM_CDMA (self), carrier, cancellable, error);
+}
+
+/*****************************************************************************/
+
+static void
+mm_modem_cdma_init (MMModemCdma *self)
+{
+}
+
+static void
+mm_modem_cdma_class_init (MMModemCdmaClass *modem_class)
+{
 }