Connection MailNotification interface: telepathy-glib API Reference Manual

Connection MailNotification interface

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

Functions

TpProxyPendingCall *	tp_cli_connection_interface_mail_notification_call_request_inbox_url ()
TpProxyPendingCall *	tp_cli_connection_interface_mail_notification_call_request_mail_url ()
void	(*tp_cli_connection_interface_mail_notification_callback_for_request_inbox_url) ()
void	(*tp_cli_connection_interface_mail_notification_callback_for_request_mail_url) ()
TpProxySignalConnection *	tp_cli_connection_interface_mail_notification_connect_to_mails_received ()
TpProxySignalConnection *	tp_cli_connection_interface_mail_notification_connect_to_unread_mails_changed ()
void	(*tp_cli_connection_interface_mail_notification_signal_callback_mails_received) ()
void	(*tp_cli_connection_interface_mail_notification_signal_callback_unread_mails_changed) ()

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 "id" 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 "id" 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