From 4f5dd8afaa79efecc1e7ffa56988d60f6e45c706 Mon Sep 17 00:00:00 2001 From: Aleksander Morgado Date: Wed, 3 Oct 2012 13:17:12 +0200 Subject: [PATCH] libmm-glib,unlock-retries: improve documentation --- .../libmm-glib/libmm-glib-sections.txt | 12 +++-- libmm-glib/mm-unlock-retries.c | 31 +++++++++++ libmm-glib/mm-unlock-retries.h | 52 +++++++++++++++---- 3 files changed, 79 insertions(+), 16 deletions(-) diff --git a/docs/reference/libmm-glib/libmm-glib-sections.txt b/docs/reference/libmm-glib/libmm-glib-sections.txt index 8b978041..fa837666 100644 --- a/docs/reference/libmm-glib/libmm-glib-sections.txt +++ b/docs/reference/libmm-glib/libmm-glib-sections.txt @@ -165,19 +165,21 @@ mm_modem_get_type mm-unlock-retries MMUnlockRetries MMUnlockRetries -MMUnlockRetriesClass -MMUnlockRetriesForeachCb MM_UNLOCK_RETRIES_UNKNOWN + +mm_unlock_retries_get +MMUnlockRetriesForeachCb +mm_unlock_retries_foreach + mm_unlock_retries_build_string mm_unlock_retries_cmp -mm_unlock_retries_foreach -mm_unlock_retries_get -mm_unlock_retries_get_dictionary mm_unlock_retries_new mm_unlock_retries_new_from_dictionary +mm_unlock_retries_get_dictionary mm_unlock_retries_set mm_unlock_retries_unset +MMUnlockRetriesClass MMUnlockRetriesPrivate MM_IS_UNLOCK_RETRIES MM_IS_UNLOCK_RETRIES_CLASS diff --git a/libmm-glib/mm-unlock-retries.c b/libmm-glib/mm-unlock-retries.c index a329c411..4ce6c324 100644 --- a/libmm-glib/mm-unlock-retries.c +++ b/libmm-glib/mm-unlock-retries.c @@ -20,6 +20,18 @@ #include "mm-enums-types.h" #include "mm-unlock-retries.h" +/** + * SECTION: mm-unlock-retries + * @title: MMUnlockRetries + * @short_description: Helper object to report unlock retries. + * + * The #MMUnlockRetries is an object exposing the unlock retry counts for + * different #MMModemLock values. + * + * This object is retrieved from the #MMModem object with either + * mm_modem_get_unlock_retries() or mm_modem_peek_unlock_retries(). + */ + G_DEFINE_TYPE (MMUnlockRetries, mm_unlock_retries, G_TYPE_OBJECT); struct _MMUnlockRetriesPrivate { @@ -46,6 +58,17 @@ mm_unlock_retries_unset (MMUnlockRetries *self, GUINT_TO_POINTER (lock)); } +/*****************************************************************************/ + +/** + * mm_unlock_retries_get: + * @self: a #MMUnlockRetries. + * @lock: a #MMModemLock. + * + * Gets the unlock retries for the given @lock. + * + * Returns: the unlock retries or %MM_UNLOCK_RETRIES_UNKNOWN if unknown. + */ guint mm_unlock_retries_get (MMUnlockRetries *self, MMModemLock lock) @@ -86,6 +109,14 @@ mm_unlock_retries_cmp (MMUnlockRetries *a, /*****************************************************************************/ +/** + * mm_unlock_retries_foreach: + * @self: a @MMUnlockRetries. + * @callback: callback to call for each available lock. + * @user_data: data to pass to @callback. + * + * Executes @callback for each lock information found in @self. + */ void mm_unlock_retries_foreach (MMUnlockRetries *self, MMUnlockRetriesForeachCb callback, diff --git a/libmm-glib/mm-unlock-retries.h b/libmm-glib/mm-unlock-retries.h index ea43cb6a..babdcbb3 100644 --- a/libmm-glib/mm-unlock-retries.h +++ b/libmm-glib/mm-unlock-retries.h @@ -32,23 +32,62 @@ G_BEGIN_DECLS #define MM_IS_UNLOCK_RETRIES_CLASS(klass) (G_TYPE_CHECK_CLASS_TYPE ((klass), MM_TYPE_UNLOCK_RETRIES)) #define MM_UNLOCK_RETRIES_GET_CLASS(obj) (G_TYPE_INSTANCE_GET_CLASS ((obj), MM_TYPE_UNLOCK_RETRIES, MMUnlockRetriesClass)) +/** + * MM_UNLOCK_RETRIES_UNKNOWN: + * + * Identifier for reporting unknown unlock retries. + */ #define MM_UNLOCK_RETRIES_UNKNOWN 999 typedef struct _MMUnlockRetries MMUnlockRetries; typedef struct _MMUnlockRetriesClass MMUnlockRetriesClass; typedef struct _MMUnlockRetriesPrivate MMUnlockRetriesPrivate; +/** + * MMUnlockRetries: + * + * The #MMUnlockRetries structure contains private data and should only be accessed + * using the provided API. + */ struct _MMUnlockRetries { + /*< private >*/ GObject parent; MMUnlockRetriesPrivate *priv; }; struct _MMUnlockRetriesClass { + /*< private >*/ GObjectClass parent; }; GType mm_unlock_retries_get_type (void); +guint mm_unlock_retries_get (MMUnlockRetries *self, + MMModemLock lock); + +/** + * MMUnlockRetriesForeachCb: + * @lock: a #MMModemLock. + * @count: the number of retries left for @lock. + * @user_data: data passed to the function. + * + * Specifies the type of function passed to mm_unlock_retries_foreach(). + */ +typedef void (* MMUnlockRetriesForeachCb) (MMModemLock lock, + guint count, + gpointer user_data); + +void mm_unlock_retries_foreach (MMUnlockRetries *self, + MMUnlockRetriesForeachCb callback, + gpointer user_data); + +/*****************************************************************************/ +/* ModemManager/libmm-glib/mmcli specific methods */ + +#if defined (_LIBMM_INSIDE_MM) || \ + defined (_LIBMM_INSIDE_MMCLI) || \ + defined (LIBMM_GLIB_COMPILATION) + MMUnlockRetries *mm_unlock_retries_new (void); MMUnlockRetries *mm_unlock_retries_new_from_dictionary (GVariant *dictionary); @@ -59,17 +98,6 @@ void mm_unlock_retries_set (MMUnlockRetries *self, void mm_unlock_retries_unset (MMUnlockRetries *self, MMModemLock lock); -guint mm_unlock_retries_get (MMUnlockRetries *self, - MMModemLock lock); - -typedef void (* MMUnlockRetriesForeachCb) (MMModemLock lock, - guint count, - gpointer user_data); - -void mm_unlock_retries_foreach (MMUnlockRetries *self, - MMUnlockRetriesForeachCb callback, - gpointer user_data); - gboolean mm_unlock_retries_cmp (MMUnlockRetries *a, MMUnlockRetries *b); @@ -77,6 +105,8 @@ GVariant *mm_unlock_retries_get_dictionary (MMUnlockRetries *self); gchar *mm_unlock_retries_build_string (MMUnlockRetries *self); +#endif + G_END_DECLS #endif /* MM_UNLOCK_RETRIES_H */