MMSms

## MMSms MMSms — The SMS interface |

## Synopsis

    struct              MMSms;

    const gchar *       mm_sms_get_path                     (MMSms *self);
    gchar *             mm_sms_dup_path                     (MMSms *self);
    MMSmsState          mm_sms_get_state                    (MMSms *self);
    MMSmsPduType        mm_sms_get_pdu_type                 (MMSms *self);
    MMSmsStorage        mm_sms_get_storage                  (MMSms *self);
    const gchar *       mm_sms_get_text                     (MMSms *self);
    gchar *             mm_sms_dup_text                     (MMSms *self);
    const guint8 *      mm_sms_get_data                     (MMSms *self,
                                                             gsize *data_len);
    guint8 *            mm_sms_dup_data                     (MMSms *self,
                                                             gsize *data_len);
    const gchar *       mm_sms_get_number                   (MMSms *self);
    gchar *             mm_sms_dup_number                   (MMSms *self);
    const gchar *       mm_sms_get_smsc                     (MMSms *self);
    gchar *             mm_sms_dup_smsc                     (MMSms *self);
    guint               mm_sms_get_message_reference        (MMSms *self);
    gint                mm_sms_get_class                    (MMSms *self);
    MMSmsValidityType   mm_sms_get_validity_type            (MMSms *self);
    guint               mm_sms_get_validity_relative        (MMSms *self);
    const gchar *       mm_sms_get_timestamp                (MMSms *self);
    gchar *             mm_sms_dup_timestamp                (MMSms *self);
    const gchar *       mm_sms_get_discharge_timestamp      (MMSms *self);
    gchar *             mm_sms_dup_discharge_timestamp      (MMSms *self);
    guint               mm_sms_get_delivery_state           (MMSms *self);
    gboolean            mm_sms_get_delivery_report_request  (MMSms *self);

    void                mm_sms_send                         (MMSms *self,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    gboolean            mm_sms_send_finish                  (MMSms *self,
                                                             GAsyncResult *res,
                                                             GError **error);
    gboolean            mm_sms_send_sync                    (MMSms *self,
                                                             GCancellable *cancellable,
                                                             GError **error);
    void                mm_sms_store                        (MMSms *self,
                                                             MMSmsStorage storage,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    gboolean            mm_sms_store_finish                 (MMSms *self,
                                                             GAsyncResult *res,
                                                             GError **error);
    gboolean            mm_sms_store_sync                   (MMSms *self,
                                                             MMSmsStorage storage,
                                                             GCancellable *cancellable,
                                                             GError **error);

## Object Hierarchy

      GObject
       +----GDBusProxy
             +----MmGdbusSmsProxy
                   +----MMSms

## Implemented Interfaces

MMSms implements GDBusInterface, GInitable, GAsyncInitable and MmGdbusSms.

## Description

The MMSms is an object providing access to the methods, signals and properties of the SMS interface.

When the SMS is exposed and available in the bus, it is ensured that at least this interface is also available.

## Details

### struct MMSms

    struct MMSms;

The MMSms structure contains private data and should only be accessed using the provided API.

### mm_sms_get_path ()

    const gchar *       mm_sms_get_path                     (MMSms *self);

Gets the DBus path of the MMSms object.

`self` : | A MMSms.
Returns : | The DBus path of the MMSms object. [transfer none]

### mm_sms_dup_path ()

    gchar *             mm_sms_dup_path                     (MMSms *self);

Gets a copy of the DBus path of the MMSms object.

`self` : | A MMSms.
Returns : | The DBus path of the MMSms object. The returned value should be freed with `g_free()`. [transfer full]

### mm_sms_get_state ()

    MMSmsState          mm_sms_get_state                    (MMSms *self);

Gets the state of this SMS.

`self` : | A MMSms.
Returns : | A MMSmsState specifying the state.

### mm_sms_get_pdu_type ()

    MMSmsPduType        mm_sms_get_pdu_type                 (MMSms *self);

Gets the PDU type on which this SMS is based.

`self` : | A MMSms.
Returns : | A MMSmsPduType specifying the PDU type.

### mm_sms_get_storage ()

    MMSmsStorage        mm_sms_get_storage                  (MMSms *self);

Gets the storage in which this SMS is kept.

`self` : | A MMSms.
Returns : | A MMSmsStorage specifying the storage.

### mm_sms_get_text ()

    const gchar *       mm_sms_get_text                     (MMSms *self);

Gets the message text, in UTF-8.

### 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_sms_dup_text()` if on another thread.

`self` : | A MMSms.
Returns : | The message text, or `NULL` if it doesn't contain any (e.g. contains data instead). [transfer none]

### mm_sms_dup_text ()

    gchar *             mm_sms_dup_text                     (MMSms *self);

Gets the message text, in UTF-8.

`self` : | A MMSms.
Returns : | The message text, or `NULL` if it doesn't contain any (e.g. contains data instead). The returned value should be freed with `g_free()`. [transfer full]

### mm_sms_get_data ()

    const guint8 *      mm_sms_get_data                     (MMSms *self,
                                                             gsize *data_len);

Gets the message data.

`self` : | A MMSms.
`data_len` : | Size of the output data, if any given. [out]
Returns : | The message data, or `NULL` if it doesn't contain any (e.g. contains text instead). [transfer none]

### mm_sms_dup_data ()

    guint8 *            mm_sms_dup_data                     (MMSms *self,
                                                             gsize *data_len);

Gets the message data.

`self` : | A MMSms.
`data_len` : | (out) Size of the output data, if any given.
Returns : | The message data, or `NULL` if it doesn't contain any (e.g. contains text instead). The returned value should be freed with `g_free()`. [transfer full]

### mm_sms_get_number ()

    const gchar *       mm_sms_get_number                   (MMSms *self);

Gets the number to which the message is addressed.

### 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_sms_dup_number()` if on another thread.

`self` : | A MMSms.
Returns : | The number, or `NULL` if it couldn't be retrieved. [transfer none]

### mm_sms_dup_number ()

    gchar *             mm_sms_dup_number                   (MMSms *self);

Gets the number to which the message is addressed.

`self` : | A MMSms.
Returns : | The number, or `NULL` if it couldn't be retrieved. The returned value should be freed with `g_free()`. [transfer full]

### mm_sms_get_smsc ()

    const gchar *       mm_sms_get_smsc                     (MMSms *self);

Gets the SMS service center number.

### 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_sms_dup_smsc()` if on another thread.

`self` : | A MMSms.
Returns : | The number of the SMSC, or `NULL` if it couldn't be retrieved. [transfer none]

### mm_sms_dup_smsc ()

    gchar *             mm_sms_dup_smsc                     (MMSms *self);

Gets the SMS service center number.

`self` : | A MMSms.
Returns : | The number of the SMSC, or `NULL` if it couldn't be retrieved. The returned value should be freed with `g_free()`. [transfer full]

### mm_sms_get_message_reference ()

    guint               mm_sms_get_message_reference        (MMSms *self);

Gets the message reference of the last PDU sent/received within this SMS.

If the PDU type is `MM_SMS_PDU_TYPE_STATUS_REPORT`, this field identifies the message reference of the PDU associated to the status report.

`self` : | A MMSms.
Returns : | The message reference.

### mm_sms_get_class ()

    gint                mm_sms_get_class                    (MMSms *self);

Gets the 3GPP message class of the SMS.

`self` : | A MMSms.
Returns : | the message class, or -1 for invalid/unset class.

### mm_sms_get_validity_type ()

    MMSmsValidityType   mm_sms_get_validity_type            (MMSms *self);

Gets the type of validity information in the SMS.

`self` : | A MMSms.
Returns : | the validity type or MM_SMS_VALIDITY_TYPE_UNKNOWN.

### mm_sms_get_validity_relative ()

    guint               mm_sms_get_validity_relative        (MMSms *self);

Gets the length of the validity period, in minutes.

Only applicable if the type of validity is MM_SMS_VALIDITY_TYPE_RELATIVE.

`self` : | A MMSms.
Returns : | the length of the validity period, or 0 if unknown.

### mm_sms_get_timestamp ()

    const gchar *       mm_sms_get_timestamp                (MMSms *self);

Gets the time when the first PDU of the SMS message arrived the SMSC, in ISO8601 format.

This field is only applicable if the PDU type is `MM_SMS_PDU_TYPE_DELIVER` or `MM_SMS_PDU_TYPE_STATUS_REPORT`.

### 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_sms_dup_timestamp()` if on another thread.

`self` : | A MMSms.
Returns : | The timestamp, or `NULL` if it couldn't be retrieved. [transfer none]

### mm_sms_dup_timestamp ()

    gchar *             mm_sms_dup_timestamp                (MMSms *self);

Gets the time when the first PDU of the SMS message arrived the SMSC, in ISO8601 format.

This field is only applicable if the PDU type is `MM_SMS_PDU_TYPE_DELIVER` or `MM_SMS_PDU_TYPE_STATUS_REPORT`.

`self` : | A MMSms.
Returns : | The timestamp, or `NULL` if it couldn't be retrieved. The returned value should be freed with `g_free()`. [transfer full]

### mm_sms_get_discharge_timestamp ()

    const gchar *       mm_sms_get_discharge_timestamp      (MMSms *self);

Gets the time when the first PDU of the SMS message left the SMSC, in ISO8601 format.

This field is only applicable if the PDU type is `MM_SMS_PDU_TYPE_STATUS_REPORT`.

### 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_sms_dup_discharge_timestamp()` if on another thread.

`self` : | A MMSms.
Returns : | The timestamp, or `NULL` if it couldn't be retrieved. [transfer none]

### mm_sms_dup_discharge_timestamp ()

    gchar *             mm_sms_dup_discharge_timestamp      (MMSms *self);

Gets the time when the first PDU of the SMS message left the SMSC, in ISO8601 format.

This field is only applicable if the PDU type is `MM_SMS_PDU_TYPE_STATUS_REPORT`.

`self` : | A MMSms.
Returns : | The timestamp, or `NULL` if it couldn't be retrieved. The returned value should be freed with `g_free()`. [transfer full]

### mm_sms_get_delivery_state ()

    guint               mm_sms_get_delivery_state           (MMSms *self);

Gets the delivery state of this SMS.

This field is only applicable if the PDU type is `MM_SMS_PDU_TYPE_STATUS_REPORT`.

`self` : | A MMSms.
Returns : | A MMSmsDeliveryState specifying the delivery state.

### mm_sms_get_delivery_report_request ()

    gboolean            mm_sms_get_delivery_report_request  (MMSms *self);

Checks whether delivery report is requested for this SMS.

`self` : | A MMSms.
Returns : | `TRUE` if delivery report is requested, `FALSE` otherwise.

### mm_sms_send ()

    void                mm_sms_send                         (MMSms *self,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);

Asynchronously requests to queue the message for delivery.

SMS objects can only be sent once.

When the operation is finished, `callback` will be invoked in the thread-default main loop of the thread you are calling this method from. You can then call `mm_sms_send_finish()` to get the result of the operation.

See `mm_sms_send_sync()` for the synchronous, blocking version of this method.

`self` : | A MMSms.
`cancellable` : | A GCancellable or `NULL`. [allow-none]
`callback` : | A GAsyncReadyCallback to call when the request is satisfied or `NULL`.
`user_data` : | User data to pass to `callback`.

### mm_sms_send_finish ()

    gboolean            mm_sms_send_finish                  (MMSms *self,
                                                             GAsyncResult *res,
                                                             GError **error);

Finishes an operation started with `mm_sms_send()`.

`self` : | A MMSms.
`res` : | The GAsyncResult obtained from the GAsyncReadyCallback passed to `mm_sms_send()`.
`error` : | Return location for error or `NULL`.
Returns : | `TRUE` if the operation succeded, `FALSE` if `error` is set.

### mm_sms_send_sync ()

    gboolean            mm_sms_send_sync                    (MMSms *self,
                                                             GCancellable *cancellable,
                                                             GError **error);

Synchronously requests to queue the message for delivery.

SMS objects can only be sent once.

The calling thread is blocked until a reply is received. See `mm_sms_send()` for the asynchronous version of this method.

`self` : | A MMSms.
`cancellable` : | A GCancellable or `NULL`. [allow-none]
`error` : | Return location for error or `NULL`.
Returns : | `TRUE` if the operation succeded, `FALSE` if `error` is set.

### mm_sms_store ()

    void                mm_sms_store                        (MMSms *self,
                                                             MMSmsStorage storage,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);

Asynchronoulsy requests to store the message in the device if not already done.

SMS objects can only be stored once.

When the operation is finished, `callback` will be invoked in the thread-default main loop of the thread you are calling this method from. You can then call `mm_sms_store_finish()` to get the result of the operation.

See `mm_sms_store_sync()` for the synchronous, blocking version of this method.

`self` : | A MMSms.
`storage` : | A MMSmsStorage specifying where to store the SMS, or MM_SMS_STORAGE_UNKNOWN to use the default.
`cancellable` : | A GCancellable or `NULL`. [allow-none]
`callback` : | A GAsyncReadyCallback to call when the request is satisfied or `NULL`.
`user_data` : | User data to pass to `callback`.

### mm_sms_store_finish ()

    gboolean            mm_sms_store_finish                 (MMSms *self,
                                                             GAsyncResult *res,
                                                             GError **error);

Finishes an operation started with `mm_sms_store()`.

`self` : | A MMSms.
`res` : | The GAsyncResult obtained from the GAsyncReadyCallback passed to `mm_sms_store()`.
`error` : | Return location for error or `NULL`.
Returns : | `TRUE` if the operation succeded, `FALSE` if `error` is set.

### mm_sms_store_sync ()

    gboolean            mm_sms_store_sync                   (MMSms *self,
                                                             MMSmsStorage storage,
                                                             GCancellable *cancellable,
                                                             GError **error);

Synchronoulsy requests to store the message in the device if not already done.

SMS objects can only be stored once.

The calling thread is blocked until a reply is received. See `mm_sms_store()` for the asynchronous version of this method.

`self` : | A MMSms.
`storage` : | A MMSmsStorage specifying where to store the SMS, or MM_SMS_STORAGE_UNKNOWN to use the default.
`cancellable` : | A GCancellable or `NULL`. [allow-none]
`error` : | Return location for error or `NULL`.
Returns : | `TRUE` if the operation succeded, `FALSE` if `error` is set.