TnyAccount

TnyAccount — A type that defines an account

Synopsis




                    TnyAccount;
                    TnyAccountIface;
#define             TNY_TYPE_CONNECTION_STATUS
#define             TNY_TYPE_ACCOUNT_TYPE
#define             TNY_TYPE_ACCOUNT_SIGNAL
GType               tny_account_type_get_type           (void);
TnyConnectionStatus tny_account_get_connection_status   (TnyAccount *self);
void                tny_account_set_id                  (TnyAccount *self,
                                                         const gchar *id);
void                tny_account_set_name                (TnyAccount *self,
                                                         const gchar *name);
void                tny_account_set_secure_auth_mech    (TnyAccount *self,
                                                         const gchar *mech);
void                tny_account_set_proto               (TnyAccount *self,
                                                         const gchar *proto);
void                tny_account_set_user                (TnyAccount *self,
                                                         const gchar *user);
void                tny_account_set_hostname            (TnyAccount *self,
                                                         const gchar *host);
void                tny_account_set_port                (TnyAccount *self,
                                                         guint port);
void                tny_account_set_pass_func           (TnyAccount *self,
                                                         TnyGetPassFunc get_pass_func);
void                tny_account_set_url_string          (TnyAccount *self,
                                                         const gchar *url_string);
TnyAccountType      tny_account_get_account_type        (TnyAccount *self);
const gchar*        tny_account_get_id                  (TnyAccount *self);
const gchar*        tny_account_get_name                (TnyAccount *self);
const gchar*        tny_account_get_secure_auth_mech    (TnyAccount *self);
const gchar*        tny_account_get_proto               (TnyAccount *self);
const gchar*        tny_account_get_user                (TnyAccount *self);
const gchar*        tny_account_get_hostname            (TnyAccount *self);
guint               tny_account_get_port                (TnyAccount *self);
gchar*              tny_account_get_url_string          (TnyAccount *self);
TnyGetPassFunc      tny_account_get_pass_func           (TnyAccount *self);
void                tny_account_set_forget_pass_func    (TnyAccount *self,
                                                         TnyForgetPassFunc forget_pass_func);
TnyForgetPassFunc   tny_account_get_forget_pass_func    (TnyAccount *self);
void                tny_account_cancel                  (TnyAccount *self);
gboolean            tny_account_matches_url_string      (TnyAccount *self,
                                                         const gchar *url_string);
void                tny_account_start_operation         (TnyAccount *self,
                                                         TnyStatusDomain domain,
                                                         TnyStatusCode code,
                                                         TnyStatusCallback status_callback,
                                                         gpointer status_user_data);
void                tny_account_stop_operation          (TnyAccount *self,
                                                         gboolean *canceled);
gboolean            tny_account_is_ready                (TnyAccount *self);

Object Hierarchy


  GInterface
   +----TnyAccount

Prerequisites

TnyAccount requires GObject.

Known Derived Interfaces

TnyAccount is required by TnyStoreAccount and TnyTransportAccount.

Known Implementations

TnyAccount is implemented by TnyCamelAccount, TnyCamelNNTPStoreAccount, TnyCamelIMAPStoreAccount, TnyCamelStoreAccount, TnyCamelTransportAccount, TnyCombinedAccount and TnyCamelPOPStoreAccount.

Signals


  "changed"                                        : Run First
  "connection-status-changed"                      : Run First

Description

A abstract type that contains shared functionality of the TnyStoreAccount and the TnyTransportAccount types.

Details

TnyAccount

typedef struct _TnyAccount TnyAccount;


TnyAccountIface

typedef struct {
	GTypeInterface parent;

	/* Methods */
	TnyConnectionStatus (*get_connection_status_func)(TnyAccount *self);
	void (*set_id_func) (TnyAccount *self, const gchar *id);
	void (*set_name_func) (TnyAccount *self, const gchar *name);
	void (*set_secure_auth_mech_func) (TnyAccount *self, const gchar *mech);
	void (*set_proto_func) (TnyAccount *self, const gchar *proto);
	void (*set_user_func) (TnyAccount *self, const gchar *user);
	void (*set_hostname_func) (TnyAccount *self, const gchar *host);
	void (*set_port_func) (TnyAccount *self, guint port);
	void (*set_url_string_func) (TnyAccount *self, const gchar *url_string);
	void (*set_pass_func_func) (TnyAccount *self, TnyGetPassFunc get_pass_func);
	void (*set_forget_pass_func_func) (TnyAccount *self, TnyForgetPassFunc get_forget_pass_func);
	TnyGetPassFunc (*get_pass_func_func) (TnyAccount *self);
	TnyForgetPassFunc (*get_forget_pass_func_func) (TnyAccount *self);
	const gchar* (*get_id_func) (TnyAccount *self);
	const gchar* (*get_name_func) (TnyAccount *self);
	const gchar* (*get_secure_auth_mech_func) (TnyAccount *self);
	const gchar* (*get_proto_func) (TnyAccount *self);
	const gchar* (*get_user_func) (TnyAccount *self);
	const gchar* (*get_hostname_func) (TnyAccount *self);
	guint (*get_port_func) (TnyAccount *self);
	gchar* (*get_url_string_func) (TnyAccount *self);
	TnyAccountType (*get_account_type_func) (TnyAccount *self);
	void (*cancel_func) (TnyAccount *self);
	gboolean (*matches_url_string_func) (TnyAccount *self, const gchar *url_string);
	void (*start_operation_func) (TnyAccount *self, TnyStatusDomain domain, TnyStatusCode code, TnyStatusCallback status_callback, gpointer status_user_data);
	void (*stop_operation_func) (TnyAccount *self, gboolean *canceled);
	gboolean (*is_ready_func) (TnyAccount *self);

	/* Signals*/
	void (*connection_status_changed) (TnyAccount *self, TnyConnectionStatus status);
	void (*changed) (TnyAccount *self);
} TnyAccountIface;


TNY_TYPE_CONNECTION_STATUS

#define TNY_TYPE_CONNECTION_STATUS (tny_connection_status_get_type())


TNY_TYPE_ACCOUNT_TYPE

#define TNY_TYPE_ACCOUNT_TYPE (tny_account_type_get_type())


TNY_TYPE_ACCOUNT_SIGNAL

#define TNY_TYPE_ACCOUNT_SIGNAL (tny_account_signal_type_get_type())


tny_account_type_get_type ()

GType               tny_account_type_get_type           (void);

GType system helper function

Returns : a GType

tny_account_get_connection_status ()

TnyConnectionStatus tny_account_get_connection_status   (TnyAccount *self);

Get the connection status of self

self : a TnyAccount object
Returns : the status of the connection

tny_account_set_id ()

void                tny_account_set_id                  (TnyAccount *self,
                                                         const gchar *id);

Set the unique id of the account. You need to set this property before you can start using the account. The id must be unique in a TnyAccountStore and is typically set in the implementation of a TnyAccountStore.

self : a TnyAccount object
id : the id

tny_account_set_name ()

void                tny_account_set_name                (TnyAccount *self,
                                                         const gchar *name);

Set the account's human readable name

self : a TnyAccount object
name : the name

tny_account_set_secure_auth_mech ()

void                tny_account_set_secure_auth_mech    (TnyAccount *self,
                                                         const gchar *mech);

Set the account's secure authentication mechanism. The possible values depend on the capabilities of the server, but here are some possible values: - "ANONYMOUS": Results in an AUTHENTICATE ANONYMOUS request, as specified in RFC 2245. - "CRAM-MD5": Challenge-Response Authentication Mechanism, as specified in RFC 2195. - "DIGEST-MD5": Digest Authentication, as specified in RFC 2831. - GSSAPI: Generic Security Service Application Program Interface, as specified in RFC 2222 and RFC 2078. - Kerberos 4: as specified in RFC 2222. - "NTLM / SPA": Secure Password Authentication, as used by Outlook Express. - "Login" - "PLAIN" - "POP before SMTP".

Other relevant standards: - RFC 1731 - IMAP4 Authentication Mechanisms

self : a TnyAccount object
mech : the authentication mechanism

tny_account_set_proto ()

void                tny_account_set_proto               (TnyAccount *self,
                                                         const gchar *proto);

Set the protocol of self. You need to set this property before you can start using the account. This property is typically set in the implementation of a TnyAccountStore.

self : a TnyAccount object
proto : the protocol (ex. "imap")

tny_account_set_user ()

void                tny_account_set_user                (TnyAccount *self,
                                                         const gchar *user);

Set the user or login of self. You need to set this property before you can start using the account. This property is typically set in the implementation of a TnyAccountStore.

self : a TnyAccount object
user : the username

tny_account_set_hostname ()

void                tny_account_set_hostname            (TnyAccount *self,
                                                         const gchar *host);

Set the hostname of self. You need to set this property before you can start using the account. This property is typically set in the implementation of a TnyAccountStore.

self : a TnyAccount object
host : the hostname

tny_account_set_port ()

void                tny_account_set_port                (TnyAccount *self,
                                                         guint port);

Set the port of self. If you don't set this property, the default port for the protocol will be used (for example 143 and 993 for IMAP and 110 for POP3).

self : a TnyAccount object
port : the port to connect to on the hostname

tny_account_set_pass_func ()

void                tny_account_set_pass_func           (TnyAccount *self,
                                                         TnyGetPassFunc get_pass_func);

Set the function that will be called when the password is needed. The function should return the password for a specific account. The password itself is usually stored in a secured password store.

You need to set this property before you can start using the account. This property is typically set in the implementation of a TnyAccountStore. Set this property as the last of all properties that you will set to an account in the TnyAccountStore.

Also see TnyGetPassFunc for more information about the function itself.

Example:

static GHashTable *passwords;
static gchar* 
per_account_get_pass_func (TnyAccount *account, const gchar *prompt, gboolean *cancel)
{
   TnyPlatformFactory *platfact = tny_my_platform_factory_get_instance ();
   TnyPasswordGetter *pwdgetter;
   gchar *retval;
   pwdgetter = tny_platform_factory_new_password_getter (platfact);
   retval = (gchar*) tny_password_getter_get_password (pwdgetter, 
      tny_account_get_id (account), prompt, cancel);
   g_object_unref (G_OBJECT (pwdgetter));
   return retval;
}
static void
tny_my_account_store_get_accounts (TnyAccountStore *self, TnyList *list, TnyGetAccountsRequestType types)
{
    TnyAccount *account = ...
    ...
    tny_account_set_forget_pass_func (account, per_account_forget_pass_func);
    tny_account_set_pass_func (account, per_account_get_pass_func);
    tny_list_prepend (list, (GObject*)account);
    g_object_unref (G_OBJECT (account));
    ...
}

self : a TnyAccount object
get_pass_func : a pointer to the function

tny_account_set_url_string ()

void                tny_account_set_url_string          (TnyAccount *self,
                                                         const gchar *url_string);

Set the url string of self (RFC 1808). You don't need to use this for imap and pop where you can use the simplified API (set_proto, set_hostname, etc). This property is typically set in the implementation of a TnyAccountStore.

For example the url_string for an SMTP account that uses SSL with authentication type PLAIN: smtp://user;auth=PLAINsmtp.server.com/;use_ssl=wrapped

Don't forget to set the name, type and proto setting of the account too.

self : a TnyAccount object
url_string : the url string (ex. mbox://path)

tny_account_get_account_type ()

TnyAccountType      tny_account_get_account_type        (TnyAccount *self);

Get the account type of self. There are two account types: a store and transport account type.

A store account typically contains folders and messages. Examples are NNTP, IMAP and POP accounts.

A transport account has a send method for sending TnyMsg instances using the transport implemented by the account (for example SMTP).

self : a TnyAccount object
Returns : The account type

tny_account_get_id ()

const gchar*        tny_account_get_id                  (TnyAccount *self);

Get the unique id of self

A certainty you have about this property is that the id is unique in the TnyAccountStore. It doesn't have to be unique in the entire application.

The format of the id isn't specified. The implementor of the TnyAccountStore must set this id using tny_account_set_id.

self : a TnyAccount object
Returns : Unique id

tny_account_get_name ()

const gchar*        tny_account_get_name                (TnyAccount *self);

Get the human readable name of self. The returned value should not be freed. The returned value van be NULL in case of no human reabable name.

self : a TnyAccount object
Returns : the human readable name as a read-only string

tny_account_get_secure_auth_mech ()

const gchar*        tny_account_get_secure_auth_mech    (TnyAccount *self);

Get the secure authentication mechanism for this account. Default is "PLAIN". The returned value can be NULL, in which case a undefined default is used.

self : a TnyAccount object
Returns : the authentication mechanism as a read-only string

tny_account_get_proto ()

const gchar*        tny_account_get_proto               (TnyAccount *self);

Get the protocol of self. The returned value should not be freed.

self : a TnyAccount object
Returns : the protocol as a read-only string

tny_account_get_user ()

const gchar*        tny_account_get_user                (TnyAccount *self);

Get the user or login of self. The returned value should not be freed. The returned value van be NULL in case of no user.

self : a TnyAccount object
Returns : the user as a read-only string

tny_account_get_hostname ()

const gchar*        tny_account_get_hostname            (TnyAccount *self);

Get the hostname of self. The returned value should not be freed. The returned value can be NULL, in which case no hostname is set (for example for a local account).

self : a TnyAccount object
Returns : the hostname as a read-only string

tny_account_get_port ()

guint               tny_account_get_port                (TnyAccount *self);

Get the port of self.

self : a TnyAccount object
Returns : the port

tny_account_get_url_string ()

gchar*              tny_account_get_url_string          (TnyAccount *self);

Get the url string of self or NULL if it's impossible to determine the url string of self. If not NULL, the returned value must be freed.

The url string is specified in RFC 1808 and looks for example like this: imap://userhostname. Note that it doesn't necessarily contain the password of the IMAP account.

self : a TnyAccount object
Returns : the url string or NULL.

tny_account_get_pass_func ()

TnyGetPassFunc      tny_account_get_pass_func           (TnyAccount *self);

Get a pointer to the get-password function

self : a TnyAccount object
Returns : A pointer to the get-password function

tny_account_set_forget_pass_func ()

void                tny_account_set_forget_pass_func    (TnyAccount *self,
                                                         TnyForgetPassFunc forget_pass_func);

Set the function that will be called in case the password was wrong and therefore can, for example, be forgotten by a password store.

You need to set this property before you can start using the account. This property is typically set in the implementation of a TnyAccountStore.

Also see TnyForgetPassFunc for more information about the function itself.

Example:

static GHashTable *passwords;
static void
per_account_forget_pass_func (TnyAccount *account)
{
   TnyPlatformFactory *platfact = tny_my_platform_factory_get_instance ();
   TnyPasswordGetter *pwdgetter;
   pwdgetter = tny_platform_factory_new_password_getter (platfact);
   tny_password_getter_forget_password (pwdgetter, tny_account_get_id (account));
   g_object_unref (G_OBJECT (pwdgetter));
   return;
}
static void
tny_my_account_store_get_accounts (TnyAccountStore *self, TnyList *list, TnyGetAccountsRequestType types)
{
    TnyAccount *account = ...
    ...
    tny_account_set_forget_pass_func (account, per_account_forget_pass_func);
    tny_account_set_pass_func (account, per_account_get_pass_func);
    tny_list_prepend (list, (GObject*)account);
    g_object_unref (G_OBJECT (account));
    ...
}

self : a TnyAccount object
forget_pass_func : a pointer to the function

tny_account_get_forget_pass_func ()

TnyForgetPassFunc   tny_account_get_forget_pass_func    (TnyAccount *self);

Get a pointer to the forget-password function

self : a TnyAccount object
Returns : A pointer to the forget-password function

tny_account_cancel ()

void                tny_account_cancel                  (TnyAccount *self);

Try to cancel the current operation that is happening. This API, though, guarantees nothing about any cancelations.

self : a TnyAccount object

tny_account_matches_url_string ()

gboolean            tny_account_matches_url_string      (TnyAccount *self,
                                                         const gchar *url_string);

Find out whether the account matches a certain url_string.

Implementors: Be forgiving about things like passwords in the url_string: while matching the folder, password and message-id pieces are insignificant.

An example url_string can be imap://user:passwordserver/INBOX/005. Only "imap://userserver" is significant when searching. Also take a look at RFC 1808 and RFC 4467 for more information on url_string formatting.

This method must be usable with and will be used for tny_account_store_find_account.

self : a TnyAccount object
url_string : the url-string of the account to find
Returns : whether or not self matches with url_string.

tny_account_start_operation ()

void                tny_account_start_operation         (TnyAccount *self,
                                                         TnyStatusDomain domain,
                                                         TnyStatusCode code,
                                                         TnyStatusCallback status_callback,
                                                         gpointer status_user_data);

Start an operation. This only works with methods that don't end with _async.

self : a TnyAccount object
domain : the domain of the TnyStatus instances that will happen in status_callback
code : the code of the TnyStatus instances that will happen in status_callback
status_callback : status callback handler
status_user_data : the user-data to give to the status_callback

tny_account_stop_operation ()

void                tny_account_stop_operation          (TnyAccount *self,
                                                         gboolean *canceled);

Stop the current operation. This only works with methods that don't end with _async.

self : a TnyAccount object
canceled : NULL or byref whether the operation got canceled

tny_account_is_ready ()

gboolean            tny_account_is_ready                (TnyAccount *self);

Some implementations of TnyAccount need registration in a subsystem or factory before they are not only valid instances, but also ready to use. For example before their connection-status-changed signal emissions are accurate. This boolean property will tell you if self is ready for that.

self : a TnyAccount object
Returns : whether self is ready for use

Signal Details

The "changed" signal

void                user_function                      (TnyAccount *self,
                                                        gpointer    user_data)      : Run First

Emitted when the account changes.

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.

The "connection-status-changed" signal

void                user_function                      (TnyAccount *self,
                                                        gint        status,
                                                        gpointer    user_data)      : Run First

Emitted when the connection status of an account changes.

@:
self : the object on which the signal is emitted
status : the TnyConnectionStatus
user_data : user data set when the signal handler was connected.
user_data : user data set when the signal handler was connected.

See Also

TnyStoreAccount, TnyTransportAccount