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
Generated by GTK-Doc V1.19