![]() |
![]() |
![]() |
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); GType tny_connection_status_get_type (void); GType tny_account_signal_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); 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 *cancelled); gboolean tny_account_is_ready (TnyAccount *self); TnyConnectionPolicy* tny_account_get_connection_policy (TnyAccount *self); void tny_account_set_connection_policy (TnyAccount *self, TnyConnectionPolicy *policy);
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 _TnyAccount TnyAccount;
A abstract account type with API shared between TnyStoreAccount and TnyTransportAccount.
free-function: g_object_unref
typedef struct { GTypeInterface parent; /* Methods */ TnyConnectionStatus (*get_connection_status)(TnyAccount *self); void (*set_id) (TnyAccount *self, const gchar *id); void (*set_name) (TnyAccount *self, const gchar *name); void (*set_secure_auth_mech) (TnyAccount *self, const gchar *mech); void (*set_proto) (TnyAccount *self, const gchar *proto); void (*set_user) (TnyAccount *self, const gchar *user); void (*set_hostname) (TnyAccount *self, const gchar *host); void (*set_port) (TnyAccount *self, guint port); void (*set_url_string) (TnyAccount *self, const gchar *url_string); void (*set_pass_func) (TnyAccount *self, TnyGetPassFunc get_pass_func); void (*set_forget_pass_func) (TnyAccount *self, TnyForgetPassFunc get_forget_pass_func); TnyGetPassFunc (*get_pass_func) (TnyAccount *self); TnyForgetPassFunc (*get_forget_pass_func) (TnyAccount *self); const gchar* (*get_id) (TnyAccount *self); const gchar* (*get_name) (TnyAccount *self); const gchar* (*get_secure_auth_mech) (TnyAccount *self); const gchar* (*get_proto) (TnyAccount *self); const gchar* (*get_user) (TnyAccount *self); const gchar* (*get_hostname) (TnyAccount *self); guint (*get_port) (TnyAccount *self); gchar* (*get_url_string) (TnyAccount *self); TnyAccountType (*get_account_type) (TnyAccount *self); void (*cancel) (TnyAccount *self); gboolean (*matches_url_string) (TnyAccount *self, const gchar *url_string); void (*start_operation) (TnyAccount *self, TnyStatusDomain domain, TnyStatusCode code, TnyStatusCallback status_callback, gpointer status_user_data); void (*stop_operation) (TnyAccount *self, gboolean *cancelled); gboolean (*is_ready) (TnyAccount *self); TnyConnectionPolicy* (*get_connection_policy) (TnyAccount *self); void (*set_connection_policy) (TnyAccount *self, TnyConnectionPolicy *policy); /* 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 |
GType tny_connection_status_get_type (void);
GType system helper function
Returns : | a GType |
GType tny_account_signal_type_get_type (void);
GType system helper function
Returns : | a GType |
TnyConnectionStatus tny_account_get_connection_status (TnyAccount *self);
Get the status of the connection for account self
.
self : |
a TnyAccount |
Returns : | the status of the connection |
Since 1.0 complexity: low audience: application-developer
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 |
id : |
the id |
Since 1.0 audience: platform-developer
void tny_account_set_name (TnyAccount *self, const gchar *name);
Set the account's human readable name
self : |
a TnyAccount |
name : |
the name |
Since 1.0 audience: platform-developer
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 |
mech : |
the authentication mechanism |
Since 1.0 audience: platform-developer
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 |
proto : |
the protocol (ex. "imap") |
Since 1.0 audience: platform-developer
void tny_account_set_user (TnyAccount *self, const gchar *user);
Set the user or login of account 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 |
user : |
the username |
Since 1.0 complexity: high audience: platform-developer
void tny_account_set_hostname (TnyAccount *self, const gchar *host);
Set the hostname of account 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 |
host : |
the hostname |
Since 1.0 audience: platform-developer
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, 993 for IMAP and 110, 995 for POP3).
self : |
a TnyAccount |
port : |
the port to connect to on the hostname of self
|
Since 1.0 audience: platform-developer
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.
If possible, use the mlock()
syscall on this memory.
Also see TnyGetPassFunc for more information about the function itself.
Example:
static GHashTable *passwords; static gchar* per_account_get_pass(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); mlock (retval, strlen (retval)); g_object_unref (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); tny_account_set_pass_func (account, per_account_get_pass); tny_list_prepend (list, (GObject*)account); g_object_unref (account); ... }
self : |
a TnyAccount |
get_pass_func : |
a pointer to the function |
Since 1.0 audience: platform-developer
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 (tny_account_set_proto()
,
tny_account_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 protocol setting of the account too.
self : |
a TnyAccount |
url_string : |
the url string (ex. mbox://path) |
Since 1.0 audience: platform-developer
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 layer the account uses. For example SMTP.
self : |
a TnyAccount |
Returns : | The account type |
Since 1.0 audience: application-developer
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 that contains self
. It doesn't have to be unique in the
entire application if you have multiple TnyAccountStore instances (which
is unlikely).
The format of the id isn't specified. The implementer of the TnyAccountStore must set this id using tny_account_set_id.
self : |
a TnyAccount |
Returns : | unique id |
Since 1.0 audience: application-developer
const gchar* tny_account_get_name (TnyAccount *self);
Get the human readable name of accountself
. The returned value should not
be freed. The returned value can be NULL.
self : |
a TnyAccount |
Returns : | the human readable name as a read-only string |
Since 1.0 audience: application-developer
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. The returned value should not be freed.
self : |
a TnyAccount |
Returns : | the authentication mechanism as a read-only string |
Since 1.0 audience: application-developer
const gchar* tny_account_get_proto (TnyAccount *self);
Get the protocol of self
. The returned value should not be freed.
self : |
a TnyAccount |
Returns : | the protocol as a read-only string |
Since 1.0 audience: application-developer
const gchar* tny_account_get_user (TnyAccount *self);
Get the user or login of account self
. The returned value should
not be freed. The returned value can be NULL.
self : |
a TnyAccount |
Returns : | the user as a read-only string |
Since 1.0 audience: application-developer
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 |
Since 1.0 audience: application-developer
guint tny_account_get_port (TnyAccount *self);
Get the port of self
.
self : |
a TnyAccount |
Returns : | the port |
Since 1.0 audience: application-developer
gchar* tny_account_get_url_string (TnyAccount *self);
Get the url-string of account 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 account.
self : |
a TnyAccount |
Returns : | (null-ok) (caller-owns): the url-string or NULL. |
Since 1.0 audience: application-developer
TnyGetPassFunc tny_account_get_pass_func (TnyAccount *self);
Get a pointer to the get-password function
self : |
a TnyAccount |
Returns : | A pointer to the get-password function |
Since 1.0 audience: application-developer
void tny_account_set_forget_pass_func (TnyAccount *self, TnyForgetPassFunc forget_pass);
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(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); tny_account_set_pass_func (account, per_account_get_pass); tny_list_prepend (list, (GObject*)account); g_object_unref (G_OBJECT (account)); ... }
self : |
a TnyAccount |
forget_pass : |
Since 1.0 audience: platform-developer
TnyForgetPassFunc tny_account_get_forget_pass_func (TnyAccount *self);
Get a pointer to the forget-password function for self
.
self : |
a TnyAccount |
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, makes no guarantees about any cancellations taking place (it's a try).
Since relatively few guarantees can be made, using this API is not recommended.
self : |
a TnyAccount |
Since 1.0 audience: application-developer
gboolean tny_account_matches_url_string (TnyAccount *self, const gchar *url_string);
Returns whether the account's url-string matches url_string
.
When implementing 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 will be used by tny_account_store_find_account()
.
self : |
a TnyAccount |
url_string : |
the url-string of the account to find |
Returns : | TRUE if self matches with url_string , else FALSE
|
Since 1.0 audience: application-developer, platform-developer
void tny_account_start_operation (TnyAccount *self, TnyStatusDomain domain, TnyStatusCode code, TnyStatusCallback status_callback, gpointer status_user_data);
Starts an operation. This only works for methods that don't end with _async.
self : |
a TnyAccount |
domain : |
the domain of the TnyStatus that will happen in status_callback
|
code : |
the code of the TnyStatus that will happen in status_callback
|
status_callback : |
(null-ok): status callback handler or NULL |
status_user_data : |
(null-ok): the user-data to give to the status_callback or NULL
|
Since 1.0 audience: application-developer
void tny_account_stop_operation (TnyAccount *self, gboolean *cancelled);
Stop the current operation. This only works for methods that don't end with _async.
self : |
a TnyAccount |
cancelled : |
(out): NULL or byref whether the operation got canceled |
Since 1.0 audience: application-developer
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 |
Returns : | TRUE if self is ready for use, else FALSE
|
Since 1.0 audience: platform-developer
TnyConnectionPolicy* tny_account_get_connection_policy (TnyAccount *self);
Get the connection policy for self
. You must unreference the returned
value when you are finished with used it.
self : |
a TnyAccount |
Returns : | (caller-owns): connection policy |
Since 1.0 audience: application-developer, platform-developer
void tny_account_set_connection_policy (TnyAccount *self, TnyConnectionPolicy *policy);
Set the connection strategy for self
.
self : |
a TnyAccount |
policy : |
a TnyConnectionStrategy |
Since 1.0 audience: application-developer, platform-developer
void user_function (TnyAccount *self, gpointer user_data) : Run First
Emitted when one of the account's properties 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 audience: application-developer
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 : |
(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 audience: application-developer