libmm-glib,sms-properties: improve documentation

This commit is contained in:
Aleksander Morgado
2012-10-03 17:40:25 +02:00
parent 054915299a
commit b52bbf7b0b
3 changed files with 274 additions and 94 deletions

View File

@@ -866,30 +866,33 @@ mm_sms_get_type
<FILE>mm-sms-properties</FILE>
<TITLE>MMSmsProperties</TITLE>
MMSmsProperties
MMSmsPropertiesClass
mm_sms_properties_dup
mm_sms_properties_get_class
mm_sms_properties_get_data
mm_sms_properties_get_data_bytearray
mm_sms_properties_get_delivery_report_request
mm_sms_properties_get_dictionary
mm_sms_properties_get_number
mm_sms_properties_get_smsc
mm_sms_properties_get_text
mm_sms_properties_get_validity
<SUBSECTION New>
mm_sms_properties_new
<SUBSECTION GettersSetters>
mm_sms_properties_get_text
mm_sms_properties_set_text
mm_sms_properties_get_data
mm_sms_properties_set_data
mm_sms_properties_peek_data_bytearray
mm_sms_properties_get_data_bytearray
mm_sms_properties_set_data_bytearray
mm_sms_properties_get_number
mm_sms_properties_set_number
mm_sms_properties_get_smsc
mm_sms_properties_set_smsc
mm_sms_properties_get_validity
mm_sms_properties_set_validity
mm_sms_properties_get_class
mm_sms_properties_set_class
mm_sms_properties_get_delivery_report_request
mm_sms_properties_set_delivery_report_request
<SUBSECTION Private>
mm_sms_properties_get_dictionary
mm_sms_properties_dup
mm_sms_properties_new_from_dictionary
mm_sms_properties_new_from_string
mm_sms_properties_peek_data_bytearray
mm_sms_properties_set_class
mm_sms_properties_set_data
mm_sms_properties_set_data_bytearray
mm_sms_properties_set_delivery_report_request
mm_sms_properties_set_number
mm_sms_properties_set_smsc
mm_sms_properties_set_text
mm_sms_properties_set_validity
<SUBSECTION Standard>
MMSmsPropertiesClass
MMSmsPropertiesPrivate
MM_IS_SMS_PROPERTIES
MM_IS_SMS_PROPERTIES_CLASS

View File

@@ -21,6 +21,18 @@
#include "mm-common-helpers.h"
#include "mm-sms-properties.h"
/**
* SECTION: mm-sms-properties
* @title: MMSmsProperties
* @short_description: Helper object to handle SMS properties.
*
* The #MMSmsProperties is an object handling the properties to be set
* in newly created SMS objects.
*
* This object is created by the user and passed to ModemManager with either
* mm_modem_messaging_create() or mm_modem_messaging_create_sync().
*/
G_DEFINE_TYPE (MMSmsProperties, mm_sms_properties, G_TYPE_OBJECT);
#define PROPERTY_TEXT "text"
@@ -46,6 +58,13 @@ struct _MMSmsPropertiesPrivate {
/*****************************************************************************/
/**
* mm_sms_properties_set_text:
* @self: A #MMSmsProperties.
* @text: The text to set, in UTF-8.
*
* Sets the message text.
*/
void
mm_sms_properties_set_text (MMSmsProperties *self,
const gchar *text)
@@ -56,6 +75,32 @@ mm_sms_properties_set_text (MMSmsProperties *self,
self->priv->text = g_strdup (text);
}
/**
* mm_sms_properties_get_text:
* @self: A #MMSmsProperties.
*
* Gets the message text, in UTF-8.
*
* Returns: (transfer none): The message text, or %NULL if it doesn't contain any (e.g. contains data instead). Do not free the returned value, it is owned by @self.
*/
const gchar *
mm_sms_properties_get_text (MMSmsProperties *self)
{
g_return_val_if_fail (MM_IS_SMS_PROPERTIES (self), NULL);
return self->priv->text;
}
/*****************************************************************************/
/**
* mm_sms_properties_set_data:
* @self: A #MMSmsProperties.
* @data: The data to set.
* @data_length: Length of @data.
*
* Sets the message data.
*/
void
mm_sms_properties_set_data (MMSmsProperties *self,
const guint8 *data,
@@ -74,6 +119,13 @@ mm_sms_properties_set_data (MMSmsProperties *self,
self->priv->data = NULL;
}
/**
* mm_sms_properties_set_data_bytearray:
* @self: A #MMSmsProperties.
* @data: A #GByteArray with the data to set. This method takes a new reference of @data.
*
* Sets the message data.
*/
void
mm_sms_properties_set_data_bytearray (MMSmsProperties *self,
GByteArray *data)
@@ -86,74 +138,15 @@ mm_sms_properties_set_data_bytearray (MMSmsProperties *self,
self->priv->data = (data ? g_byte_array_ref (data) : NULL);
}
void
mm_sms_properties_set_number (MMSmsProperties *self,
const gchar *number)
{
g_return_if_fail (MM_IS_SMS_PROPERTIES (self));
g_free (self->priv->number);
self->priv->number = g_strdup (number);
}
void
mm_sms_properties_set_smsc (MMSmsProperties *self,
const gchar *smsc)
{
g_return_if_fail (MM_IS_SMS_PROPERTIES (self));
g_free (self->priv->smsc);
self->priv->smsc = g_strdup (smsc);
}
void
mm_sms_properties_set_validity (MMSmsProperties *self,
guint validity)
{
g_return_if_fail (MM_IS_SMS_PROPERTIES (self));
self->priv->validity_set = TRUE;
self->priv->validity = validity;
}
void
mm_sms_properties_set_class (MMSmsProperties *self,
guint class)
{
g_return_if_fail (MM_IS_SMS_PROPERTIES (self));
self->priv->class_set = TRUE;
self->priv->class = class;
}
void
mm_sms_properties_set_delivery_report_request (MMSmsProperties *self,
gboolean request)
{
g_return_if_fail (MM_IS_SMS_PROPERTIES (self));
self->priv->delivery_report_request_set = TRUE;
self->priv->delivery_report_request = request;
}
/*****************************************************************************/
const gchar *
mm_sms_properties_get_text (MMSmsProperties *self)
{
g_return_val_if_fail (MM_IS_SMS_PROPERTIES (self), NULL);
return self->priv->text;
}
const gchar *
mm_sms_properties_get_number (MMSmsProperties *self)
{
g_return_val_if_fail (MM_IS_SMS_PROPERTIES (self), NULL);
return self->priv->number;
}
/**
* mm_sms_properties_get_data:
* @self: A #MMSmsProperties.
* @data_len: (out): Size of the output data, if any given.
*
* Gets the message data.
*
* Returns: (transfer none): The message data, or %NULL if it doesn't contain any (e.g. contains text instead).
*/
const guint8 *
mm_sms_properties_get_data (MMSmsProperties *self,
gsize *data_len)
@@ -166,6 +159,14 @@ mm_sms_properties_get_data (MMSmsProperties *self,
return self->priv->data->data;
}
/**
* mm_sms_properties_peek_data_bytearray:
* @self: A #MMSmsProperties.
*
* Gets the message data.
*
* Returns: (transfer none): A #GByteArray with the message data, or %NULL if it doesn't contain any (e.g. contains text instead). Do not free the returned value, it is owned by @self.
*/
GByteArray *
mm_sms_properties_peek_data_bytearray (MMSmsProperties *self)
{
@@ -174,6 +175,14 @@ mm_sms_properties_peek_data_bytearray (MMSmsProperties *self)
return self->priv->data;
}
/**
* mm_sms_properties_get_data_bytearray:
* @self: A #MMSmsProperties.
*
* Gets the message data.
*
* Returns: (transfer none): A #GByteArray with the message data, or %NULL if it doesn't contain any (e.g. contains text instead). The returned value should be freed with g_byte_array_unref().
*/
GByteArray *
mm_sms_properties_get_data_bytearray (MMSmsProperties *self)
{
@@ -182,6 +191,68 @@ mm_sms_properties_get_data_bytearray (MMSmsProperties *self)
return (self->priv->data ? g_byte_array_ref (self->priv->data) : NULL);
}
/*****************************************************************************/
/**
* mm_sms_properties_set_number:
* @self: A #MMSmsProperties.
* @number: The number.
*
* Sets the number to which the message is addressed.
*/
void
mm_sms_properties_set_number (MMSmsProperties *self,
const gchar *number)
{
g_return_if_fail (MM_IS_SMS_PROPERTIES (self));
g_free (self->priv->number);
self->priv->number = g_strdup (number);
}
/**
* mm_sms_properties_get_number:
* @self: A #MMSmsProperties.
*
* Gets the number to which the message is addressed.
*
* Returns: (transfer none): The number, or %NULL if it couldn't be retrieved. Do not free the returned value, it is owned by @self.
*/
const gchar *
mm_sms_properties_get_number (MMSmsProperties *self)
{
g_return_val_if_fail (MM_IS_SMS_PROPERTIES (self), NULL);
return self->priv->number;
}
/*****************************************************************************/
/**
* mm_sms_properties_set_smsc:
* @self: A #MMSmsProperties.
* @smsc: The SMSC number.
*
* Sets the SMS service center number.
*/
void
mm_sms_properties_set_smsc (MMSmsProperties *self,
const gchar *smsc)
{
g_return_if_fail (MM_IS_SMS_PROPERTIES (self));
g_free (self->priv->smsc);
self->priv->smsc = g_strdup (smsc);
}
/**
* mm_sms_properties_get_smsc:
* @self: A #MMSmsProperties.
*
* Gets the SMS service center number.
*
* Returns: (transfer none): The number of the SMSC, or %NULL if it couldn't be retrieved. Do not free the returned value, it is owned by @self.
*/
const gchar *
mm_sms_properties_get_smsc (MMSmsProperties *self)
{
@@ -190,6 +261,33 @@ mm_sms_properties_get_smsc (MMSmsProperties *self)
return self->priv->smsc;
}
/*****************************************************************************/
/**
* mm_sms_properties_set_validity:
* @self: A #MMSmsProperties.
* @validity: The validity.
*
* Sets the validity time of the SMS.
*/
void
mm_sms_properties_set_validity (MMSmsProperties *self,
guint validity)
{
g_return_if_fail (MM_IS_SMS_PROPERTIES (self));
self->priv->validity_set = TRUE;
self->priv->validity = validity;
}
/**
* mm_sms_properties_get_validity:
* @self: A #MMSmsProperties.
*
* Gets the validity time of the SMS.
*
* Returns: the validity time or 0 if unknown.
*/
guint
mm_sms_properties_get_validity (MMSmsProperties *self)
{
@@ -198,6 +296,33 @@ mm_sms_properties_get_validity (MMSmsProperties *self)
return self->priv->validity;
}
/*****************************************************************************/
/**
* mm_sms_properties_set_class:
* @self: A #MMSmsProperties.
* @class: The message class.
*
* Sets the 3GPP message class of the SMS.
*/
void
mm_sms_properties_set_class (MMSmsProperties *self,
guint class)
{
g_return_if_fail (MM_IS_SMS_PROPERTIES (self));
self->priv->class_set = TRUE;
self->priv->class = class;
}
/**
* mm_sms_properties_get_class:
* @self: A #MMSmsProperties.
*
* Gets the 3GPP message class of the SMS.
*
* Returns: the message class.
*/
guint
mm_sms_properties_get_class (MMSmsProperties *self)
{
@@ -206,6 +331,33 @@ mm_sms_properties_get_class (MMSmsProperties *self)
return self->priv->class;
}
/*****************************************************************************/
/**
* mm_sms_properties_set_delivery_report_request:
* @self: A #MMSmsProperties.
* @request: %TRUE if delivery report is requested, %FALSE otherwise.
*
* Sets whether delivery report is requested for the SMS.
*/
void
mm_sms_properties_set_delivery_report_request (MMSmsProperties *self,
gboolean request)
{
g_return_if_fail (MM_IS_SMS_PROPERTIES (self));
self->priv->delivery_report_request_set = TRUE;
self->priv->delivery_report_request = request;
}
/**
* mm_sms_properties_get_delivery_report_request:
* @self: A #MMSmsProperties.
*
* Checks whether delivery report is requested for the SMS.
*
* Returns: %TRUE if delivery report is requested, %FALSE otherwise.
*/
gboolean
mm_sms_properties_get_delivery_report_request (MMSmsProperties *self)
{
@@ -547,6 +699,13 @@ mm_sms_properties_dup (MMSmsProperties *orig)
/*****************************************************************************/
/**
* mm_sms_properties_new:
*
* Creates a new empty #MMSmsProperties.
*
* Returns: (transfer full): a #MMSmsProperties. The returned value should be freed with g_object_unref().
*/
MMSmsProperties *
mm_sms_properties_new (void)
{

View File

@@ -36,24 +36,26 @@ typedef struct _MMSmsProperties MMSmsProperties;
typedef struct _MMSmsPropertiesClass MMSmsPropertiesClass;
typedef struct _MMSmsPropertiesPrivate MMSmsPropertiesPrivate;
/**
* MMSmsProperties:
*
* The #MMSmsProperties structure contains private data and should only be
* accessed using the provided API.
*/
struct _MMSmsProperties {
/*< private >*/
GObject parent;
MMSmsPropertiesPrivate *priv;
};
struct _MMSmsPropertiesClass {
/*< private >*/
GObjectClass parent;
};
GType mm_sms_properties_get_type (void);
MMSmsProperties *mm_sms_properties_new (void);
MMSmsProperties *mm_sms_properties_new_from_string (const gchar *str,
GError **error);
MMSmsProperties *mm_sms_properties_new_from_dictionary (GVariant *dictionary,
GError **error);
MMSmsProperties *mm_sms_properties_dup (MMSmsProperties *orig);
void mm_sms_properties_set_text (MMSmsProperties *self,
const gchar *text);
@@ -84,8 +86,24 @@ guint mm_sms_properties_get_validity (MMSmsProperties *se
guint mm_sms_properties_get_class (MMSmsProperties *self);
gboolean mm_sms_properties_get_delivery_report_request (MMSmsProperties *self);
/*****************************************************************************/
/* ModemManager/libmm-glib/mmcli specific methods */
#if defined (_LIBMM_INSIDE_MM) || \
defined (_LIBMM_INSIDE_MMCLI) || \
defined (LIBMM_GLIB_COMPILATION)
MMSmsProperties *mm_sms_properties_new_from_string (const gchar *str,
GError **error);
MMSmsProperties *mm_sms_properties_new_from_dictionary (GVariant *dictionary,
GError **error);
MMSmsProperties *mm_sms_properties_dup (MMSmsProperties *orig);
GVariant *mm_sms_properties_get_dictionary (MMSmsProperties *self);
#endif
G_END_DECLS
#endif /* MM_SMS_PROPERTIES_H */