![]() |
![]() |
![]() |
Reference Manual of the tinymail framework | ![]() |
---|---|---|---|---|
#define TNY_TYPE_ACCOUNT_STORE_SIGNAL #define TNY_TYPE_ALERT_TYPE #define TNY_TYPE_GET_ACCOUNTS_REQUEST_TYPE TnyAccountStore; TnyAccountStoreIface; GType tny_get_accounts_request_type_get_type (void); GType tny_alert_type_get_type (void); void tny_account_store_get_accounts (TnyAccountStore *self, TnyList *list, TnyGetAccountsRequestType types); const gchar* tny_account_store_get_cache_dir (TnyAccountStore *self); TnyDevice* tny_account_store_get_device (TnyAccountStore *self); gboolean tny_account_store_alert (TnyAccountStore *self, TnyAccount *account, TnyAlertType type, gboolean question, const GError *error); TnyAccount* tny_account_store_find_account (TnyAccountStore *self, const gchar *url_string);
#define TNY_TYPE_ACCOUNT_STORE_SIGNAL (tny_account_store_signal_get_type())
#define TNY_TYPE_GET_ACCOUNTS_REQUEST_TYPE (tny_get_accounts_request_type_get_type())
typedef struct { GTypeInterface parent; /* Methods */ void (*get_accounts_func) (TnyAccountStore *self, TnyList *list, TnyGetAccountsRequestType types); const gchar* (*get_cache_dir_func) (TnyAccountStore *self); TnyDevice* (*get_device_func) (TnyAccountStore *self); gboolean (*alert_func) (TnyAccountStore *self, TnyAccount *account, TnyAlertType type, gboolean question, const GError *error); TnyAccount* (*find_account_func) (TnyAccountStore *self, const gchar *url_string); /* Signals */ void (*connecting_started) (TnyAccountStore *self); } TnyAccountStoreIface;
GType tny_get_accounts_request_type_get_type (void);
GType system helper function
Returns : | a GType |
GType tny_alert_type_get_type (void);
GType system helper function
Returns : | a GType |
void tny_account_store_get_accounts (TnyAccountStore *self, TnyList *list, TnyGetAccountsRequestType types);
Get a read-only list of accounts in the store. You must not change list
except for referencing and unreferencing.
Example:
TnyList *list = tny_simple_list_new (); tny_account_store_get_accounts (astore, list, TNY_ACCOUNT_STORE_STORE_ACCOUNTS); TnyIterator *iter = tny_list_create_iterator (list); while (!tny_iterator_is_done (iter)) { TnyStoreAccount *cur = TNY_STORE_ACCOUNT (tny_iterator_get_current (iter)); printf ("%s\n", tny_store_account_get_name (cur)); g_object_unref (G_OBJECT (cur)); tny_iterator_next (iter); } g_object_unref (G_OBJECT (iter)); g_object_unref (G_OBJECT (list));
Implementors: when implementing a platform-specific library, you must implement this method.
It is allowed to cache the list (but not required). If you are implementing an account store for account implementations from libtinymail-camel, you must register the created accounts with a TnySessionCamel instance using the libtinymail-camel specific tny_session_camel_set_current_accounts API.
If you use the TnySessionCamel to register accounts, you must after registering your last initial account call the tny_session_camel_set_initialized API.
The implementation must fillup list
with available accounts. Note that if
you cache the list, you must add a reference to each account added to the
list (else they will be unreferenced and if the reference count would reach
zero, an account would no longer be correctly cached).
With libtinymail-camel each created account must also be informed about the TnySessionCamel instance being used. Read more about this at tny_camel_account_set_session of the libtinymail-camel specific TnyCamelAccount.
There are multiple samples of TnyAccountStore implementations in libtinymail-gnome-desktop, libtinymail-olpc, libtinymail-gpe, libtinymail-maemo and tests/shared/account-store.c which is being used by the unit tests and the normal tests.
The get_pass and forget_pass functionality of the example below is usually implemented by utilizing a TnyPasswordGetter that is returned by the TnyPlatformFactory, that is usually available from the TnyAccountStore.
Example (that uses a cache):
static TnyCamelSession *session = NULL; static TnyList *accounts = NULL; static gchar* account_get_pass_func (TnyAccount *account, const gchar *prompt, gboolean *cancel) { return g_strdup ("the password"); } static void account_forget_pass_func (TnyAccount *account) { g_print ("Password was incorrect\n"); } static void tny_my_account_store_get_accounts (TnyAccountStore *self, TnyList *list, TnyGetAccountsRequestType types) { TnyIterator *iter; if (session == NULL) session = tny_session_camel_new (TNY_ACCOUNT_STORE (self)); if (accounts == NULL) { accounts = tny_simple_list_new (); for (... each account ... ) { TnyAccount *account = TNY_ACCOUNT (tny_camel_store_account_new ()); tny_camel_account_set_session (TNY_CAMEL_ACCOUNT (account), session); tny_account_set_proto (account, "imap"); tny_account_set_name (account, "account i"); tny_account_set_user (account, "user of account i"); tny_account_set_hostname (account, "server.domain of account i"); tny_account_set_id (account, "i"); tny_account_set_forget_pass_func (account, account_forget_pass_func); tny_account_set_pass_func (account, account_get_pass_func); tny_list_prepend (accounts, account); g_object_unref (G_OBJECT (account)); } } iter = tny_list_create_iterator (accounts); while (tny_iterator_is_done (iter)) { GObject *cur = tny_iterator_get_current (iter); tny_list_prepend (list, cur); g_object_unref (cur); tny_iterator_next (iter); } g_object_unref (G_OBJECT (iter)); tny_session_camel_set_initialized (session); }
self : |
a TnyAccountStore object |
list : |
a TnyList instance that will be filled with TnyAccount instances |
types : |
a TnyGetAccountsRequestType that describes which account types are needed |
const gchar* tny_account_store_get_cache_dir (TnyAccountStore *self);
Get the local path that will be used for storing the disk cache
Implementors: when implementing a platform-specific library, you must implement this method. You can for example let it return the path to some folder in $HOME on the file system.
Note that the callers of this method will not free the result. The
implementor of a TnyAccountStore is responsible for freeing it up. For
example when destroying self
(in its finalize method).
self : |
a TnyAccountStore object |
Returns : | the local path that will be used for storing the disk cache |
TnyDevice* tny_account_store_get_device (TnyAccountStore *self);
This method returns a TnyDevice instance. You must unreference the return value after use.
Implementors: when implementing a platform-specific library, you must implement this method by letting it return a TnyDevice instance. You must add a reference count before returning.
self : |
a TnyAccountStore object |
Returns : | the device attached to this account store |
gboolean tny_account_store_alert (TnyAccountStore *self, TnyAccount *account, TnyAlertType type, gboolean question, const GError *error);
This jump-to-the-ui method implements showing a message dialog appropriate
for the error
and type
as message type. It will return TRUE if the reply
was affirmative or FALSE if not.
You must not try reconnecting in the implementation of this method.
Implementors: when implementing a platform-specific library, you must implement this method. For example in GTK+ by using the GtkDialog API. The implementation will, for example, be used to ask the user about accepting SSL certificates. The two possible answers that must be supported are "Yes" and "No" which must result in a TRUE or a FALSE return value, though your implementation should attempt to use explicit button names such as "Accept Certificate" and "Reject Certificate". Likewise, the dialog should be arranged according the the user interface guidelines of your target platform.
Although there is a question
parameter, there is not always certainty about
whether or not the warning actually is a question. It's save to say, however
that in case question
is FALSE, that the return value of the function's
implementation is not considered. In case of TRUE, it usually is.
Example implementation for GTK+:
static gboolean tny_gnome_account_store_alert (TnyAccountStore *self, TnyAccount *account, TnyAlertType type, const GError *error) { GtkMessageType gtktype; GtkWidget *dialog; switch (type) { case TNY_ALERT_TYPE_INFO: gtktype = GTK_MESSAGE_INFO; break; case TNY_ALERT_TYPE_WARNING: gtktype = GTK_MESSAGE_WARNING; break; case TNY_ALERT_TYPE_ERROR: default: gtktype = GTK_MESSAGE_ERROR; break; } const gchar *prompt = NULL; switch (error->code) { case TNY_ACCOUNT_ERROR_TRY_CONNECT: prompt = _("Account not yet fully configured"); break; default: g_warning ("%s: Unhandled GError code.", __FUNCTION__); prompt = NULL; break; } if (!prompt) return FALSE; gboolean retval = FALSE; dialog = gtk_message_dialog_new (NULL, GTK_DIALOG_MODAL, gtktype, GTK_BUTTONS_YES_NO, prompt); if (gtk_dialog_run (GTK_DIALOG (dialog)) == GTK_RESPONSE_YES) retval = TRUE; gtk_widget_destroy (dialog); return retval; }
self : |
a TnyAccountStore object |
account : |
The account (This is NULL sometimes for some current implementations). |
type : |
the message type (severity) |
question : |
whether or not this is a question |
error : |
A GError, of domain TNY_ACCOUNT_ERROR or TNY_ACCOUNT_STORE_ERROR, which should be used to determine what to show to the user. |
Returns : | Whether the user pressed Ok/Yes (TRUE) or Cancel/No (FALSE) |
TnyAccount* tny_account_store_find_account (TnyAccountStore *self, const gchar *url_string);
Try to find the account in self
that corresponds to url_string
. If this
method does not return NULL, the returned value is the found account and
must be unreferenced after use.
Implementors: when implementing a platform-specific library, you must
implement this method. Let it return the account that corresponds to
url_string
or let it return NULL. Also see tny_account_matches_url_string
at TnyAccount.
This method can be used to resolve url-strings to TnyAccount instances.
self : |
a TnyAccountStore object |
url_string : |
the url-string of the account to find |
Returns : | the found account or NULL. |
void user_function (TnyAccountStore *self, gpointer user_data) : Run First
Emitted when the store starts trying to connect the accounts
self : |
the object on which the signal is emitted |
user_data : |
user data set when the signal handler was connected. |
user_data : |
user data set when the signal handler was connected. |