Connection MailNotification interface

## Connection MailNotification interface Connection MailNotification interface — client-side wrappers for the MailNotification interface |

## Synopsis

    #include <telepathy-glib/telepathy-glib-dbus.h>

    TpProxyPendingCall * tp_cli_connection_interface_mail_notification_call_request_inbox_url
                                                            (TpConnection *proxy,
                                                             gint timeout_ms,
                                                             tp_cli_connection_interface_mail_notification_callback_for_request_inbox_url callback,
                                                             gpointer user_data,
                                                             GDestroyNotify destroy,
                                                             GObject *weak_object);
    TpProxyPendingCall * tp_cli_connection_interface_mail_notification_call_request_mail_url
                                                            (TpConnection *proxy,
                                                             gint timeout_ms,
                                                             const gchar *in_ID,
                                                             const GValue *in_URL_Data,
                                                             tp_cli_connection_interface_mail_notification_callback_for_request_mail_url callback,
                                                             gpointer user_data,
                                                             GDestroyNotify destroy,
                                                             GObject *weak_object);
    void                (*tp_cli_connection_interface_mail_notification_callback_for_request_inbox_url)
                                                            (TpConnection *proxy,
                                                             const GValueArray *out_URL,
                                                             const GError *error,
                                                             gpointer user_data,
                                                             GObject *weak_object);
    void                (*tp_cli_connection_interface_mail_notification_callback_for_request_mail_url)
                                                            (TpConnection *proxy,
                                                             const GValueArray *out_URL,
                                                             const GError *error,
                                                             gpointer user_data,
                                                             GObject *weak_object);
    TpProxySignalConnection * tp_cli_connection_interface_mail_notification_connect_to_mails_received
                                                            (TpConnection *proxy,
                                                             tp_cli_connection_interface_mail_notification_signal_callback_mails_received callback,
                                                             gpointer user_data,
                                                             GDestroyNotify destroy,
                                                             GObject *weak_object,
                                                             GError **error);
    TpProxySignalConnection * tp_cli_connection_interface_mail_notification_connect_to_unread_mails_changed
                                                            (TpConnection *proxy,
                                                             tp_cli_connection_interface_mail_notification_signal_callback_unread_mails_changed callback,
                                                             gpointer user_data,
                                                             GDestroyNotify destroy,
                                                             GObject *weak_object,
                                                             GError **error);
    void                (*tp_cli_connection_interface_mail_notification_signal_callback_mails_received)
                                                            (TpConnection *proxy,
                                                             const GPtrArray *arg_Mails,
                                                             gpointer user_data,
                                                             GObject *weak_object);
    void                (*tp_cli_connection_interface_mail_notification_signal_callback_unread_mails_changed)
                                                            (TpConnection *proxy,
                                                             guint arg_Count,
                                                             const GPtrArray *arg_Mails_Added,
                                                             const gchar **arg_Mails_Removed,
                                                             gpointer user_data,
                                                             GObject *weak_object);

## Description

Some service providers offer both real-time communications and e-mail, and integrate them by providing "new mail" notifications over the real-time communication protocol.

This section documents the auto-generated C wrappers for the MailNotification interface, used with TpConnection objects.

## Details

### tp_cli_connection_interface_mail_notification_call_request_inbox_url ()

    TpProxyPendingCall * tp_cli_connection_interface_mail_notification_call_request_inbox_url
                                                            (TpConnection *proxy,
                                                             gint timeout_ms,
                                                             tp_cli_connection_interface_mail_notification_callback_for_request_inbox_url callback,
                                                             gpointer user_data,
                                                             GDestroyNotify destroy,
                                                             GObject *weak_object);

Start a RequestInboxURL method call.

This method creates and returns a URL and an optional POST data that allow opening the Inbox folder of a webmail account. This URL MAY contain tokens with a short lifetime, so clients SHOULD request a new URL for each visit to the webmail interface. This method is implemented only if the <tt>Supports_Request_Inbox_URL</tt> flag is set in <tp:member-ref>MailNotificationFlags</tp:member-ref>. <tp:rationale> We are not using properties here because the tokens are unsuitable for sharing between clients, and network round-trips may be required to obtain the information that leads to authentication free webmail access. </tp:rationale>

`proxy` : | the TpProxy
`timeout_ms` : | the timeout in milliseconds, or -1 to use the default
`callback` : | called when the method call succeeds or fails; may be `NULL` to make a "fire and forget" call with no reply tracking
`user_data` : | user-supplied data passed to the callback; must be `NULL` if `callback` is `NULL`
`destroy` : | called with the user_data as argument, after the call has succeeded, failed or been cancelled; must be `NULL` if `callback` is `NULL`
`weak_object` : | If not `NULL`, a GObject which will be weakly referenced; if it is destroyed, this call will automatically be cancelled. Must be `NULL` if `callback` is `NULL`
Returns : | a TpProxyPendingCall representing the call in progress. It is borrowed from the object, and will become invalid when the callback is called, the call is cancelled or the TpProxy becomes invalid.

### tp_cli_connection_interface_mail_notification_call_request_mail_url ()

    TpProxyPendingCall * tp_cli_connection_interface_mail_notification_call_request_mail_url
                                                            (TpConnection *proxy,
                                                             gint timeout_ms,
                                                             const gchar *in_ID,
                                                             const GValue *in_URL_Data,
                                                             tp_cli_connection_interface_mail_notification_callback_for_request_mail_url callback,
                                                             gpointer user_data,
                                                             GDestroyNotify destroy,
                                                             GObject *weak_object);

Start a RequestMailURL method call.

This method creates and returns a URL and optional POST data that allow opening a specific mail in a webmail interface. This method is implemented only if <tt>Supports_Request_Mail_URL</tt> flag is set in <tp:member-ref>MailNotificationFlags</tp:member-ref>. <tp:rationale> See <tp:member-ref>RequestInboxURL</tp:member-ref> for design rationale. </tp:rationale>

`proxy` : | the TpProxy
`timeout_ms` : | the timeout in milliseconds, or -1 to use the default
`in_ID` : | Used to pass an 'in' argument: The mail's <tt>id</tt> as found in the <tp:type>Mail</tp:type> structure, or the empty string if no <tt>id</tt> key was provided.
`in_URL_Data` : | Used to pass an 'in' argument: Whatever <tt>url-data</tt> was found in the <tp:type>Mail</tp:type> structure, or the boolean value False (D-Bus type 'b') if no <tt>url-data</tt> was provided in the Mail.
`callback` : | called when the method call succeeds or fails; may be `NULL` to make a "fire and forget" call with no reply tracking
`user_data` : | user-supplied data passed to the callback; must be `NULL` if `callback` is `NULL`
`destroy` : | called with the user_data as argument, after the call has succeeded, failed or been cancelled; must be `NULL` if `callback` is `NULL`
`weak_object` : | If not `NULL`, a GObject which will be weakly referenced; if it is destroyed, this call will automatically be cancelled. Must be `NULL` if `callback` is `NULL`
Returns : | a TpProxyPendingCall representing the call in progress. It is borrowed from the object, and will become invalid when the callback is called, the call is cancelled or the TpProxy becomes invalid.

### tp_cli_connection_interface_mail_notification_callback_for_request_inbox_url ()

    void                (*tp_cli_connection_interface_mail_notification_callback_for_request_inbox_url)
                                                            (TpConnection *proxy,
                                                             const GValueArray *out_URL,
                                                             const GError *error,
                                                             gpointer user_data,
                                                             GObject *weak_object);

Signature of the callback called when a RequestInboxURL method call succeeds or fails.

`proxy` : | the proxy on which the call was made
`out_URL` : | Used to return an 'out' argument if `error` is `NULL`: A struture containing a URL and optional additional data to open a webmail client, without re-authentication if possible.
`error` : | `NULL` on success, or an error on failure
`user_data` : | user-supplied data
`weak_object` : | user-supplied object

### tp_cli_connection_interface_mail_notification_callback_for_request_mail_url ()

    void                (*tp_cli_connection_interface_mail_notification_callback_for_request_mail_url)
                                                            (TpConnection *proxy,
                                                             const GValueArray *out_URL,
                                                             const GError *error,
                                                             gpointer user_data,
                                                             GObject *weak_object);

Signature of the callback called when a RequestMailURL method call succeeds or fails.

`proxy` : | the proxy on which the call was made
`out_URL` : | Used to return an 'out' argument if `error` is `NULL`: A struture that contains a URL and optional additional data to open a webmail client, without re-authentication if possible.
`error` : | `NULL` on success, or an error on failure
`user_data` : | user-supplied data
`weak_object` : | user-supplied object

### tp_cli_connection_interface_mail_notification_connect_to_mails_received ()

    TpProxySignalConnection * tp_cli_connection_interface_mail_notification_connect_to_mails_received
                                                            (TpConnection *proxy,
                                                             tp_cli_connection_interface_mail_notification_signal_callback_mails_received callback,
                                                             gpointer user_data,
                                                             GDestroyNotify destroy,
                                                             GObject *weak_object,
                                                             GError **error);

Connect a handler to the signal MailsReceived.

Emitted when new e-mails messages arrive to the inbox associated with this connection. This signal is used for protocols that are not able to maintain the <tp:member-ref>UnreadMails</tp:member-ref> list, but do provide real-time notification about newly arrived e-mails. It MUST NOT be emitted unless <tt>Emits_Mails_Received</tt> is set in <tp:member-ref>MailNotificationFlags</tp:member-ref>.

`proxy` : | A TpConnection or subclass
`callback` : | Callback to be called when the signal is received
`user_data` : | User-supplied data for the callback
`destroy` : | Destructor for the user-supplied data, which will be called when this signal is disconnected, or before this function returns `NULL`
`weak_object` : | A GObject which will be weakly referenced; if it is destroyed, this callback will automatically be disconnected
`error` : | If not `NULL`, used to raise an error if `NULL` is returned
Returns : | a TpProxySignalConnection containing all of the above, which can be used to disconnect the signal; or `NULL` if the proxy does not have the desired interface or has become invalid.

### tp_cli_connection_interface_mail_notification_connect_to_unread_mails_changed ()

    TpProxySignalConnection * tp_cli_connection_interface_mail_notification_connect_to_unread_mails_changed
                                                            (TpConnection *proxy,
                                                             tp_cli_connection_interface_mail_notification_signal_callback_unread_mails_changed callback,
                                                             gpointer user_data,
                                                             GDestroyNotify destroy,
                                                             GObject *weak_object,
                                                             GError **error);

Connect a handler to the signal UnreadMailsChanged.

<tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>Emitted when <tp:member-ref>UnreadMails</tp:member-ref> or <tp:member-ref>UnreadMailCount</tp:member-ref> have changed. It MUST NOT be emited if <tt>Supports_Unread_Mail_Count</tt> flag is not set in <tp:member-ref>MailNotificationFlags</tp:member-ref>.</p> <p><tt>Mails_Added</tt> and <tt>Mails_Removed</tt> MUST be empty if the <tt>Supports_Unread_Mails</tt> flag is not set.</p>

`proxy` : | A TpConnection or subclass
`callback` : | Callback to be called when the signal is received
`user_data` : | User-supplied data for the callback
`destroy` : | Destructor for the user-supplied data, which will be called when this signal is disconnected, or before this function returns `NULL`
`weak_object` : | A GObject which will be weakly referenced; if it is destroyed, this callback will automatically be disconnected
`error` : | If not `NULL`, used to raise an error if `NULL` is returned
Returns : | a TpProxySignalConnection containing all of the above, which can be used to disconnect the signal; or `NULL` if the proxy does not have the desired interface or has become invalid.

### tp_cli_connection_interface_mail_notification_signal_callback_mails_received ()

    void                (*tp_cli_connection_interface_mail_notification_signal_callback_mails_received)
                                                            (TpConnection *proxy,
                                                             const GPtrArray *arg_Mails,
                                                             gpointer user_data,
                                                             GObject *weak_object);

Represents the signature of a callback for the signal MailsReceived.

`proxy` : | The proxy on which `tp_cli_connection_interface_mail_notification_connect_to_mails_received()` was called
`arg_Mails` : | <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>An array of <tp:type>Mail</tp:type>s. Those e-mail MUST NOT have the &quot;id&quot; key.</p> <tp:rationale> <p>On connections that emit this signal, it's impossible to tell when a mail has been removed, and hence when &quot;id&quot; has become invalid.</p> </tp:rationale>
`user_data` : | User-supplied data
`weak_object` : | User-supplied weakly referenced object

### tp_cli_connection_interface_mail_notification_signal_callback_unread_mails_changed ()

    void                (*tp_cli_connection_interface_mail_notification_signal_callback_unread_mails_changed)
                                                            (TpConnection *proxy,
                                                             guint arg_Count,
                                                             const GPtrArray *arg_Mails_Added,
                                                             const gchar **arg_Mails_Removed,
                                                             gpointer user_data,
                                                             GObject *weak_object);

Represents the signature of a callback for the signal UnreadMailsChanged.

`proxy` : | The proxy on which `tp_cli_connection_interface_mail_notification_connect_to_unread_mails_changed()` was called
`arg_Count` : | Number of unread messages in the inbox (the new value of <tp:member-ref>UnreadMailCount</tp:member-ref>).
`arg_Mails_Added` : | <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>A list of <tp:type>Mail</tp:type> that are being added or updated in <tp:member-ref>UnreadMails</tp:member-ref>.</p> <tp:rationale> <p>Mails may be updated when the URL information (URL and POST data) have changed, or senders were added or removed from an e-mail thread.</p> </tp:rationale> <p>If the <tt>Supports_Unread_Mails</tt> flag is not set, this list MUST be empty, even if Count has increased.</p>
`arg_Mails_Removed` : | A list of e-mail IDs that are being removed from <tp:member-ref>UnreadMails</tp:member-ref>. If the <tt>Supports_Unread_Mails</tt> flag is not set, this list MUST be empty, even if Count has decreased.
`user_data` : | User-supplied data
`weak_object` : | User-supplied weakly referenced object