TnyAccountStore

TnyAccountStore — A type that defines a store for accounts

Synopsis




#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);

Object Hierarchy


  GInterface
   +----TnyAccountStore

Prerequisites

TnyAccountStore requires GObject.

Signals


  "connecting-started"                             : Run First

Description

A abstract type that defines a store for accounts

Details

TNY_TYPE_ACCOUNT_STORE_SIGNAL

#define TNY_TYPE_ACCOUNT_STORE_SIGNAL (tny_account_store_signal_get_type())


TNY_TYPE_ALERT_TYPE

#define TNY_TYPE_ALERT_TYPE (tny_alert_type_get_type())


TNY_TYPE_GET_ACCOUNTS_REQUEST_TYPE

#define TNY_TYPE_GET_ACCOUNTS_REQUEST_TYPE (tny_get_accounts_request_type_get_type())


TnyAccountStore

typedef struct _TnyAccountStore TnyAccountStore;

A account store, holding a list of accounts

free-function: g_object_unref


TnyAccountStoreIface

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;


tny_get_accounts_request_type_get_type ()

GType               tny_get_accounts_request_type_get_type
                                                        (void);

GType system helper function

Returns : a GType

Since 1.0


tny_alert_type_get_type ()

GType               tny_alert_type_get_type             (void);

GType system helper function

Returns : a GType

Since 1.0


tny_account_store_get_accounts ()

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


tny_account_store_get_cache_dir ()

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


tny_account_store_get_device ()

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


tny_account_store_alert ()

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


tny_account_store_find_account ()

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

Signal Details

The "connecting-started" signal

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

See Also

TnyAccount, TnyStoreAccount, TnyTransportAccount, TnyAccountStoreSignal, TnyGetAccountsRequestType