colin/ModemManager
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

libmm-glib,simple-status: improve documentation

Browse Source
This commit is contained in:
Aleksander Morgado
2012-10-03 14:35:46 +02:00
parent 8185f24e64
commit f99ac11cbb
3 changed files with 181 additions and 42 deletions
Download Patch File Download Diff File Expand all files Collapse all files

28
docs/reference/libmm-glib/libmm-glib-sections.txt
View File

@@ -616,7 +616,19 @@ mm_simple_connect_properties_get_type
<FILE>mm-simple-status</FILE> <FILE>mm-simple-status</FILE>
<TITLE>MMSimpleStatus</TITLE> <TITLE>MMSimpleStatus</TITLE>
MMSimpleStatus MMSimpleStatus
MMSimpleStatusClass <SUBSECTION Getters>
mm_simple_status_get_state
mm_simple_status_get_signal_quality
mm_simple_status_get_access_technologies
mm_simple_status_get_bands
mm_simple_status_get_3gpp_registration_state
mm_simple_status_get_3gpp_operator_code
mm_simple_status_get_3gpp_operator_name
mm_simple_status_get_cdma_cdma1x_registration_state
mm_simple_status_get_cdma_evdo_registration_state
mm_simple_status_get_cdma_nid
mm_simple_status_get_cdma_sid
<SUBSECTION Private>
MM_SIMPLE_PROPERTY_3GPP_OPERATOR_CODE MM_SIMPLE_PROPERTY_3GPP_OPERATOR_CODE
MM_SIMPLE_PROPERTY_3GPP_OPERATOR_NAME MM_SIMPLE_PROPERTY_3GPP_OPERATOR_NAME
MM_SIMPLE_PROPERTY_3GPP_REGISTRATION_STATE MM_SIMPLE_PROPERTY_3GPP_REGISTRATION_STATE
@@ -628,21 +640,11 @@ MM_SIMPLE_PROPERTY_CDMA_NID
MM_SIMPLE_PROPERTY_CDMA_SID MM_SIMPLE_PROPERTY_CDMA_SID
MM_SIMPLE_PROPERTY_SIGNAL_QUALITY MM_SIMPLE_PROPERTY_SIGNAL_QUALITY
MM_SIMPLE_PROPERTY_STATE MM_SIMPLE_PROPERTY_STATE
mm_simple_status_get_3gpp_operator_code
mm_simple_status_get_3gpp_operator_name
mm_simple_status_get_3gpp_registration_state
mm_simple_status_get_access_technologies
mm_simple_status_get_bands
mm_simple_status_get_cdma_cdma1x_registration_state
mm_simple_status_get_cdma_evdo_registration_state
mm_simple_status_get_cdma_nid
mm_simple_status_get_cdma_sid
mm_simple_status_get_dictionary
mm_simple_status_get_signal_quality
mm_simple_status_get_state
mm_simple_status_new mm_simple_status_new
mm_simple_status_new_from_dictionary mm_simple_status_new_from_dictionary
mm_simple_status_get_dictionary
<SUBSECTION Standard> <SUBSECTION Standard>
MMSimpleStatusClass
MMSimpleStatusPrivate MMSimpleStatusPrivate
MM_IS_SIMPLE_STATUS MM_IS_SIMPLE_STATUS
MM_IS_SIMPLE_STATUS_CLASS MM_IS_SIMPLE_STATUS_CLASS

143
libmm-glib/mm-simple-status.c
View File

@@ -19,9 +19,19 @@
#include "mm-errors-types.h" #include "mm-errors-types.h"
#include "mm-common-helpers.h" #include "mm-common-helpers.h"
#include "mm-simple-status.h" #include "mm-simple-status.h"
#include "mm-modem-cdma.h"
#define SID_UNKNOWN 99999 /**
#define NID_UNKNOWN 99999 * SECTION: mm-simple-status
* @title: MMSimpleStatus
* @short_description: Helper object to handle overall modem status.
*
* The #MMSimpleStatus is an object handling the general modem status properties,
* available in the Simple interface.
*
* This object is retrieved with either mm_modem_simple_get_status() or
* mm_modem_simple_get_status_sync().
*/
G_DEFINE_TYPE (MMSimpleStatus, mm_simple_status, G_TYPE_OBJECT); G_DEFINE_TYPE (MMSimpleStatus, mm_simple_status, G_TYPE_OBJECT);
@@ -76,6 +86,14 @@ struct _MMSimpleStatusPrivate {
/*****************************************************************************/ /*****************************************************************************/
/**
* mm_simple_status_get_state:
* @self: a #MMSimpleStatus.
*
* Gets the state of the modem.
*
* Returns: a #MMModemState.
*/
MMModemState MMModemState
mm_simple_status_get_state (MMSimpleStatus *self) mm_simple_status_get_state (MMSimpleStatus *self)
{ {
@@ -84,6 +102,17 @@ mm_simple_status_get_state (MMSimpleStatus *self)
return self->priv->state; return self->priv->state;
} }
/*****************************************************************************/
/**
* mm_simple_status_get_signal_quality:
* @self: a #MMSimpleStatus.
* @recent: (out) (allow-none): indication of whether the given signal quality is considered recent.
*
* Gets the signal quality.
*
* Returns: the signal quality.
*/
guint32 guint32
mm_simple_status_get_signal_quality (MMSimpleStatus *self, mm_simple_status_get_signal_quality (MMSimpleStatus *self,
gboolean *recent) gboolean *recent)
@@ -105,6 +134,16 @@ mm_simple_status_get_signal_quality (MMSimpleStatus *self,
return signal_quality; return signal_quality;
} }
/*****************************************************************************/
/**
* mm_simple_status_get_bands:
* @self: a #MMSimpleStatus.
* @bands: (out): location for an array of #MMModemBand values. Do not free the returned value, it is owned by @self.
* @n_bands: (out): number of elements in @bands.
*
* Gets the currently used frequency bands.
*/
void void
mm_simple_status_get_bands (MMSimpleStatus *self, mm_simple_status_get_bands (MMSimpleStatus *self,
const MMModemBand **bands, const MMModemBand **bands,
@@ -119,6 +158,16 @@ mm_simple_status_get_bands (MMSimpleStatus *self,
*bands = (const MMModemBand *)self->priv->bands_array->data; *bands = (const MMModemBand *)self->priv->bands_array->data;
} }
/*****************************************************************************/
/**
* mm_simple_status_get_access_technologies:
* @self: a #MMSimpleStatus.
*
* Gets the currently used access technologies.
*
* Returns: a bitmask of #MMModemAccessTechnology values.
*/
MMModemAccessTechnology MMModemAccessTechnology
mm_simple_status_get_access_technologies (MMSimpleStatus *self) mm_simple_status_get_access_technologies (MMSimpleStatus *self)
{ {
@@ -127,6 +176,16 @@ mm_simple_status_get_access_technologies (MMSimpleStatus *self)
return self->priv->access_technologies; return self->priv->access_technologies;
} }
/*****************************************************************************/
/**
* mm_simple_status_get_3gpp_registration_state:
* @self: a #MMSimpleStatus.
*
* Gets the current state of the registration in the 3GPP network.
*
* Returns: a #MMModem3gppRegistrationState.
*/
MMModem3gppRegistrationState MMModem3gppRegistrationState
mm_simple_status_get_3gpp_registration_state (MMSimpleStatus *self) mm_simple_status_get_3gpp_registration_state (MMSimpleStatus *self)
{ {
@@ -135,6 +194,16 @@ mm_simple_status_get_3gpp_registration_state (MMSimpleStatus *self)
return self->priv->modem_3gpp_registration_state; return self->priv->modem_3gpp_registration_state;
} }
/*****************************************************************************/
/**
* mm_simple_status_get_3gpp_operator_code:
* @self: a #MMSimpleStatus.
*
* Gets the MCC/MNC of the operator of the 3GPP network where the modem is registered.
*
* Returns: the operator code, or %NULL if unknown. Do not free the returned value, it is owned by @self.
*/
const gchar * const gchar *
mm_simple_status_get_3gpp_operator_code (MMSimpleStatus *self) mm_simple_status_get_3gpp_operator_code (MMSimpleStatus *self)
{ {
@@ -143,6 +212,16 @@ mm_simple_status_get_3gpp_operator_code (MMSimpleStatus *self)
return self->priv->modem_3gpp_operator_code; return self->priv->modem_3gpp_operator_code;
} }
/*****************************************************************************/
/**
* mm_simple_status_get_3gpp_operator_name:
* @self: a #MMSimpleStatus.
*
* Gets the name of the operator of the 3GPP network where the modem is registered.
*
* Returns: the operator name, or %NULL if unknown. Do not free the returned value, it is owned by @self.
*/
const gchar * const gchar *
mm_simple_status_get_3gpp_operator_name (MMSimpleStatus *self) mm_simple_status_get_3gpp_operator_name (MMSimpleStatus *self)
{ {
@@ -151,6 +230,16 @@ mm_simple_status_get_3gpp_operator_name (MMSimpleStatus *self)
return self->priv->modem_3gpp_operator_name; return self->priv->modem_3gpp_operator_name;
} }
/*****************************************************************************/
/**
* mm_simple_status_get_cdma_cdma1x_registration_state:
* @self: a #MMSimpleStatus.
*
* Gets the current state of the registration in the CDMA-1x network.
*
* Returns: a #MMModemCdmaRegistrationState.
*/
MMModemCdmaRegistrationState MMModemCdmaRegistrationState
mm_simple_status_get_cdma_cdma1x_registration_state (MMSimpleStatus *self) mm_simple_status_get_cdma_cdma1x_registration_state (MMSimpleStatus *self)
{ {
@@ -159,6 +248,16 @@ mm_simple_status_get_cdma_cdma1x_registration_state (MMSimpleStatus *self)
return self->priv->modem_cdma_cdma1x_registration_state; return self->priv->modem_cdma_cdma1x_registration_state;
} }
/*****************************************************************************/
/**
* mm_simple_status_get_cdma_evdo_registration_state:
* @self: a #MMSimpleStatus.
*
* Gets the current state of the registration in the EV-DO network.
*
* Returns: a #MMModemCdmaRegistrationState.
*/
MMModemCdmaRegistrationState MMModemCdmaRegistrationState
mm_simple_status_get_cdma_evdo_registration_state (MMSimpleStatus *self) mm_simple_status_get_cdma_evdo_registration_state (MMSimpleStatus *self)
{ {
@@ -167,18 +266,38 @@ mm_simple_status_get_cdma_evdo_registration_state (MMSimpleStatus *self)
return self->priv->modem_cdma_evdo_registration_state; return self->priv->modem_cdma_evdo_registration_state;
} }
/*****************************************************************************/
/**
* mm_simple_status_get_cdma_sid:
* @self: a #MMSimpleStatus.
*
* Gets the System Identification number of the CDMA network.
*
* Returns: the SID, or %MM_MODEM_CDMA_SID_UNKNOWN if unknown.
*/
guint guint
mm_simple_status_get_cdma_sid (MMSimpleStatus *self) mm_simple_status_get_cdma_sid (MMSimpleStatus *self)
{ {
g_return_val_if_fail (MM_IS_SIMPLE_STATUS (self), 0); g_return_val_if_fail (MM_IS_SIMPLE_STATUS (self), MM_MODEM_CDMA_SID_UNKNOWN);
return self->priv->modem_cdma_sid; return self->priv->modem_cdma_sid;
} }
/*****************************************************************************/
/**
* mm_simple_status_get_cdma_nid:
* @self: a #MMSimpleStatus.
*
* Gets the Network Identification number of the CDMA network.
*
* Returns: the NID, or %MM_MODEM_CDMA_NID_UNKNOWN if unknown.
*/
guint guint
mm_simple_status_get_cdma_nid (MMSimpleStatus *self) mm_simple_status_get_cdma_nid (MMSimpleStatus *self)
{ {
g_return_val_if_fail (MM_IS_SIMPLE_STATUS (self), 0); g_return_val_if_fail (MM_IS_SIMPLE_STATUS (self), MM_MODEM_CDMA_NID_UNKNOWN);
return self->priv->modem_cdma_nid; return self->priv->modem_cdma_nid;
} }
@@ -237,12 +356,12 @@ mm_simple_status_get_dictionary (MMSimpleStatus *self)
"{sv}", "{sv}",
MM_SIMPLE_PROPERTY_CDMA_CDMA1X_REGISTRATION_STATE, MM_SIMPLE_PROPERTY_CDMA_CDMA1X_REGISTRATION_STATE,
g_variant_new_uint32 (self->priv->modem_cdma_cdma1x_registration_state)); g_variant_new_uint32 (self->priv->modem_cdma_cdma1x_registration_state));
if (self->priv->modem_cdma_sid != SID_UNKNOWN) if (self->priv->modem_cdma_sid != MM_MODEM_CDMA_SID_UNKNOWN)
g_variant_builder_add (&builder, g_variant_builder_add (&builder,
"{sv}", "{sv}",
MM_SIMPLE_PROPERTY_CDMA_SID, MM_SIMPLE_PROPERTY_CDMA_SID,
g_variant_new_uint32 (self->priv->modem_cdma_sid)); g_variant_new_uint32 (self->priv->modem_cdma_sid));
if (self->priv->modem_cdma_nid != NID_UNKNOWN) if (self->priv->modem_cdma_nid != MM_MODEM_CDMA_NID_UNKNOWN)
g_variant_builder_add (&builder, g_variant_builder_add (&builder,
"{sv}", "{sv}",
MM_SIMPLE_PROPERTY_CDMA_NID, MM_SIMPLE_PROPERTY_CDMA_NID,
@@ -467,8 +586,8 @@ mm_simple_status_init (MMSimpleStatus *self)
self->priv->signal_quality = g_variant_ref_sink (g_variant_new ("(ub)", 0, 0)); self->priv->signal_quality = g_variant_ref_sink (g_variant_new ("(ub)", 0, 0));
self->priv->modem_cdma_cdma1x_registration_state = MM_MODEM_CDMA_REGISTRATION_STATE_UNKNOWN; self->priv->modem_cdma_cdma1x_registration_state = MM_MODEM_CDMA_REGISTRATION_STATE_UNKNOWN;
self->priv->modem_cdma_evdo_registration_state = MM_MODEM_CDMA_REGISTRATION_STATE_UNKNOWN; self->priv->modem_cdma_evdo_registration_state = MM_MODEM_CDMA_REGISTRATION_STATE_UNKNOWN;
self->priv->modem_cdma_sid = SID_UNKNOWN; self->priv->modem_cdma_sid = MM_MODEM_CDMA_SID_UNKNOWN;
self->priv->modem_cdma_nid = NID_UNKNOWN; self->priv->modem_cdma_nid = MM_MODEM_CDMA_NID_UNKNOWN;
} }
static void static void
@@ -582,8 +701,8 @@ mm_simple_status_class_init (MMSimpleStatusClass *klass)
"CDMA1x SID", "CDMA1x SID",
"System Identifier of the serving CDMA1x network", "System Identifier of the serving CDMA1x network",
0, 0,
SID_UNKNOWN, MM_MODEM_CDMA_SID_UNKNOWN,
SID_UNKNOWN, MM_MODEM_CDMA_SID_UNKNOWN,
G_PARAM_READWRITE); G_PARAM_READWRITE);
g_object_class_install_property (object_class, PROP_CDMA_SID, properties[PROP_CDMA_SID]); g_object_class_install_property (object_class, PROP_CDMA_SID, properties[PROP_CDMA_SID]);
@@ -592,8 +711,8 @@ mm_simple_status_class_init (MMSimpleStatusClass *klass)
"CDMA1x NID", "CDMA1x NID",
"Network Identifier of the serving CDMA1x network", "Network Identifier of the serving CDMA1x network",
0, 0,
NID_UNKNOWN, MM_MODEM_CDMA_NID_UNKNOWN,
NID_UNKNOWN, MM_MODEM_CDMA_NID_UNKNOWN,
G_PARAM_READWRITE); G_PARAM_READWRITE);
g_object_class_install_property (object_class, PROP_CDMA_NID, properties[PROP_CDMA_NID]); g_object_class_install_property (object_class, PROP_CDMA_NID, properties[PROP_CDMA_NID]);
} }

52
libmm-glib/mm-simple-status.h
View File

@@ -32,38 +32,29 @@ G_BEGIN_DECLS
#define MM_IS_SIMPLE_STATUS_CLASS(klass) (G_TYPE_CHECK_CLASS_TYPE ((klass), MM_TYPE_SIMPLE_STATUS)) #define MM_IS_SIMPLE_STATUS_CLASS(klass) (G_TYPE_CHECK_CLASS_TYPE ((klass), MM_TYPE_SIMPLE_STATUS))
#define MM_SIMPLE_STATUS_GET_CLASS(obj) (G_TYPE_INSTANCE_GET_CLASS ((obj), MM_TYPE_SIMPLE_STATUS, MMSimpleStatusClass)) #define MM_SIMPLE_STATUS_GET_CLASS(obj) (G_TYPE_INSTANCE_GET_CLASS ((obj), MM_TYPE_SIMPLE_STATUS, MMSimpleStatusClass))
#define MM_SIMPLE_PROPERTY_STATE "state"
#define MM_SIMPLE_PROPERTY_SIGNAL_QUALITY "signal-quality"
#define MM_SIMPLE_PROPERTY_BANDS "bands"
#define MM_SIMPLE_PROPERTY_ACCESS_TECHNOLOGIES "access-technologies"
#define MM_SIMPLE_PROPERTY_3GPP_REGISTRATION_STATE "m3gpp-registration-state"
#define MM_SIMPLE_PROPERTY_3GPP_OPERATOR_CODE "m3gpp-operator-code"
#define MM_SIMPLE_PROPERTY_3GPP_OPERATOR_NAME "m3gpp-operator-name"
#define MM_SIMPLE_PROPERTY_CDMA_CDMA1X_REGISTRATION_STATE "cdma-cdma1x-registration-state"
#define MM_SIMPLE_PROPERTY_CDMA_EVDO_REGISTRATION_STATE "cdma-evdo-registration-state"
#define MM_SIMPLE_PROPERTY_CDMA_SID "cdma-sid"
#define MM_SIMPLE_PROPERTY_CDMA_NID "cdma-nid"
typedef struct _MMSimpleStatus MMSimpleStatus; typedef struct _MMSimpleStatus MMSimpleStatus;
typedef struct _MMSimpleStatusClass MMSimpleStatusClass; typedef struct _MMSimpleStatusClass MMSimpleStatusClass;
typedef struct _MMSimpleStatusPrivate MMSimpleStatusPrivate; typedef struct _MMSimpleStatusPrivate MMSimpleStatusPrivate;
/**
* MMSimpleStatus:
*
* The #MMSimpleStatus structure contains private data and should
* only be accessed using the provided API.
*/
struct _MMSimpleStatus { struct _MMSimpleStatus {
/*< private >*/
GObject parent; GObject parent;
MMSimpleStatusPrivate *priv; MMSimpleStatusPrivate *priv;
}; };
struct _MMSimpleStatusClass { struct _MMSimpleStatusClass {
/*< private >*/
GObjectClass parent; GObjectClass parent;
}; };
GType mm_simple_status_get_type (void); GType mm_simple_status_get_type (void);
MMSimpleStatus *mm_simple_status_new (void);
MMSimpleStatus *mm_simple_status_new_from_dictionary (GVariant *dictionary,
GError **error);
MMModemState mm_simple_status_get_state (MMSimpleStatus *self); MMModemState mm_simple_status_get_state (MMSimpleStatus *self);
guint32 mm_simple_status_get_signal_quality (MMSimpleStatus *self, guint32 mm_simple_status_get_signal_quality (MMSimpleStatus *self,
@@ -82,8 +73,35 @@ MMModemCdmaRegistrationState mm_simple_status_get_cdma_evdo_registration_state
guint mm_simple_status_get_cdma_sid (MMSimpleStatus *self); guint mm_simple_status_get_cdma_sid (MMSimpleStatus *self);
guint mm_simple_status_get_cdma_nid (MMSimpleStatus *self); guint mm_simple_status_get_cdma_nid (MMSimpleStatus *self);
/*****************************************************************************/
/* ModemManager/libmm-glib/mmcli specific methods */
#if defined (_LIBMM_INSIDE_MM) || \
defined (_LIBMM_INSIDE_MMCLI) || \
defined (LIBMM_GLIB_COMPILATION)
#define MM_SIMPLE_PROPERTY_STATE "state"
#define MM_SIMPLE_PROPERTY_SIGNAL_QUALITY "signal-quality"
#define MM_SIMPLE_PROPERTY_BANDS "bands"
#define MM_SIMPLE_PROPERTY_ACCESS_TECHNOLOGIES "access-technologies"
#define MM_SIMPLE_PROPERTY_3GPP_REGISTRATION_STATE "m3gpp-registration-state"
#define MM_SIMPLE_PROPERTY_3GPP_OPERATOR_CODE "m3gpp-operator-code"
#define MM_SIMPLE_PROPERTY_3GPP_OPERATOR_NAME "m3gpp-operator-name"
#define MM_SIMPLE_PROPERTY_CDMA_CDMA1X_REGISTRATION_STATE "cdma-cdma1x-registration-state"
#define MM_SIMPLE_PROPERTY_CDMA_EVDO_REGISTRATION_STATE "cdma-evdo-registration-state"
#define MM_SIMPLE_PROPERTY_CDMA_SID "cdma-sid"
#define MM_SIMPLE_PROPERTY_CDMA_NID "cdma-nid"
MMSimpleStatus *mm_simple_status_new (void);
MMSimpleStatus *mm_simple_status_new_from_dictionary (GVariant *dictionary,
GError **error);
GVariant *mm_simple_status_get_dictionary (MMSimpleStatus *self); GVariant *mm_simple_status_get_dictionary (MMSimpleStatus *self);
#endif
G_END_DECLS G_END_DECLS
#endif /* MM_SIMPLE_STATUS_H */ #endif /* MM_SIMPLE_STATUS_H */