![]() |
![]() |
![]() |
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, 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 _TnyAccountStore TnyAccountStore;
A account store, holding a list of accounts
free-function: g_object_unref
typedef struct { GTypeInterface parent; /* Methods */ void (*get_accounts) (TnyAccountStore *self, TnyList *list, TnyGetAccountsRequestType types); const gchar* (*get_cache_dir) (TnyAccountStore *self); TnyDevice* (*get_device) (TnyAccountStore *self); gboolean (*alert) (TnyAccountStore *self, TnyAccount *account, TnyAlertType type, gboolean question, GError *error); TnyAccount* (*find_account) (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 |
Since 1.0
GType tny_alert_type_get_type (void);
GType system helper function
Returns : | a GType |
Since 1.0
void tny_account_store_get_accounts (TnyAccountStore *self, TnyList *list, TnyGetAccountsRequestType types);
Get a list of accounts in the account store self
.
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 (iter); g_object_unref (list);
When implementing this API it is allowed but not required to cache the list. If you are implementing an account store for TnyCamelAccount account instances, register the created accounts with a TnySessionCamel instance using the API tny_session_camel_set_current_accounts right after creating the accounts for the first time.
If you use the TnySessionCamel to register accounts, register each account using tny_camel_account_set_session and after registering your last account use the API tny_session_camel_set_initialized
The method must fill up list
with available accounts. Note that if
you cache the list, you must add a reference to each account added to the
list.
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.
Example (that uses a cache):
static TnyCamelSession *session = NULL; static TnyList *accounts = NULL; static gchar* account_get_pass(TnyAccount *account, const gchar *prompt, gboolean *cancel) { return g_strdup ("the password"); } static void account_forget_pass(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); tny_account_set_pass_func (account, account_get_pass); 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 (iter); tny_session_camel_set_initialized (session); }
self : |
a TnyAccountStore |
list : |
a TnyList that will be filled with TnyAccount instances |
types : |
a TnyGetAccountsRequestType that indicates which account types are wanted |
Since 1.0 audience: platform-developer, application-developer, type-implementer
const gchar* tny_account_store_get_cache_dir (TnyAccountStore *self);
Returns the path that will be used for storing cache. Note that the callers
of this method will not free up the result. The implementation of
TnyAccountStore self
is responsible for freeing up.
self : |
a TnyAccountStore |
Returns : | cache's path |
Since 1.0 audience: platform-developer, type-implementer
TnyDevice* tny_account_store_get_device (TnyAccountStore *self);
This method returns the TnyDevice instance used by TnyAccountStore self
. You
must unreference the return value after use.
self : |
a TnyAccountStore |
Returns : | (caller-owns): the device used by self
|
Since 1.0 audience: application-developer
gboolean tny_account_store_alert (TnyAccountStore *self, TnyAccount *account, TnyAlertType type, gboolean question, GError *error);
This callback method must 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.
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 to 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 |
account : |
(null-ok): The account or NULL |
type : |
alert type |
question : |
whether or not this is a question |
error : |
(null-ok): A GError with the alert |
Returns : | Affirmative = TRUE, Negative = FALSE |
Since 1.0 audience: platform-developer, application-developer, type-implementer
TnyAccount* tny_account_store_find_account (TnyAccountStore *self, const gchar *url_string);
Try to find the first account in account store self
that corresponds to
url_string
. If found, the returned value must be unreferenced.
self : |
a TnyAccountStore |
url_string : |
the url-string of the account to find |
Returns : | (null-ok) (caller-owns): the found account or NULL |
Since 1.0 audience: application-developer complexity: high
void user_function (TnyAccountStore *self, gpointer user_data) : Run First
Emitted when the store starts trying to connect the accounts. Usage of this signal is not recommended as it's a candidate for API changes.
@:
self : |
the object on which the signal is emitted |
user_data : |
(null-ok): user data set when the signal handler was connected. |
user_data : |
user data set when the signal handler was connected. |
Since 1.0