![]() |
![]() |
![]() |
Reference Manual of the tinymail framework | ![]() |
---|---|---|---|---|
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);
TnyAccount is implemented by TnyCamelAccount, TnyCamelNNTPStoreAccount, TnyCamelIMAPStoreAccount, TnyCamelStoreAccount, TnyCamelTransportAccount, TnyCombinedAccount and TnyCamelPOPStoreAccount.
A abstract type that contains shared functionality of the TnyStoreAccount and the TnyTransportAccount types.
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;
GType tny_account_type_get_type (void);
GType system helper function
Returns : | a GType |
TnyConnectionStatus tny_account_get_connection_status (TnyAccount *self);
Get the connection status of self
self : |
a TnyAccount object |
Returns : | the status of the connection |
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 |
void tny_account_set_name (TnyAccount *self, const gchar *name);
Set the account's human readable name
self : |
a TnyAccount object |
name : |
the name |
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 |
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") |
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 |
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 |
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 |
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 |
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) |
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 |
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 |
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 |
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 |
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 |
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 |
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 |
guint tny_account_get_port (TnyAccount *self);
Get the port of self
.
self : |
a TnyAccount object |
Returns : | the port |
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. |
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 |
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 |
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 |
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 |
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 .
|
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
|
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 |
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
|
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. |
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. |