Connection MailNotification interface

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

Functions

Includes

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

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.

Functions

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>

Parameters

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>

Parameters

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.

Parameters

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.

Parameters

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>.

Parameters

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>

Parameters

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.

Parameters

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.

Parameters

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