![]() |
![]() |
![]() |
Camel Reference Manual | ![]() |
---|---|---|---|---|
Top | Description | Object Hierarchy | Implemented Interfaces | Known Derived Interfaces | Properties |
struct CamelService; #define CAMEL_SERVICE_ERROR enum CamelServiceError; enum CamelServiceConnectionStatus; CamelServiceAuthType; const gchar * camel_service_get_display_name (CamelService *service
); void camel_service_set_display_name (CamelService *service
,const gchar *display_name
); const gchar * camel_service_get_password (CamelService *service
); void camel_service_set_password (CamelService *service
,const gchar *password
); const gchar * camel_service_get_user_data_dir (CamelService *service
); const gchar * camel_service_get_user_cache_dir (CamelService *service
); gchar * camel_service_get_name (CamelService *service
,gboolean brief
); CamelProvider * camel_service_get_provider (CamelService *service
); struct _CamelSession * camel_service_get_session (CamelService *service
); CamelSettings * camel_service_get_settings (CamelService *service
); void camel_service_set_settings (CamelService *service
,CamelSettings *settings
); const gchar * camel_service_get_uid (CamelService *service
); CamelURL * camel_service_get_camel_url (CamelService *service
); gchar * camel_service_get_url (CamelService *service
); void camel_service_cancel_connect (CamelService *service
); gboolean camel_service_connect_sync (CamelService *service
,GError **error
); gboolean camel_service_disconnect_sync (CamelService *service
,gboolean clean
,GError **error
); CamelServiceConnectionStatus camel_service_get_connection_status (CamelService *service
); enum CamelServiceLock; void camel_service_lock (CamelService *service
,CamelServiceLock lock
); void camel_service_unlock (CamelService *service
,CamelServiceLock lock
); enum CamelAuthenticationResult; CamelAuthenticationResult camel_service_authenticate_sync (CamelService *service
,const gchar *mechanism
,GCancellable *cancellable
,GError **error
); void camel_service_authenticate (CamelService *service
,const gchar *mechanism
,gint io_priority
,GCancellable *cancellable
,GAsyncReadyCallback callback
,gpointer user_data
); CamelAuthenticationResult camel_service_authenticate_finish (CamelService *service
,GAsyncResult *result
,GError **error
); GList * camel_service_query_auth_types_sync (CamelService *service
,GCancellable *cancellable
,GError **error
); void camel_service_query_auth_types (CamelService *service
,gint io_priority
,GCancellable *cancellable
,GAsyncReadyCallback callback
,gpointer user_data
); GList * camel_service_query_auth_types_finish (CamelService *service
,GAsyncResult *result
,GError **error
);
"display-name" gchar* : Read / Write / Construct "password" gchar* : Read / Write / Construct "provider" gpointer : Read / Write / Construct Only "session" CamelSession* : Read / Write / Construct Only "settings" CamelSettings* : Read / Write / Construct "uid" gchar* : Read / Write / Construct Only "url" CamelURL* : Read / Write / Construct Only
typedef enum { CAMEL_SERVICE_ERROR_INVALID, CAMEL_SERVICE_ERROR_URL_INVALID, CAMEL_SERVICE_ERROR_UNAVAILABLE, CAMEL_SERVICE_ERROR_CANT_AUTHENTICATE, CAMEL_SERVICE_ERROR_NOT_CONNECTED } CamelServiceError;
Since 2.32
typedef enum { CAMEL_SERVICE_DISCONNECTED, CAMEL_SERVICE_CONNECTING, CAMEL_SERVICE_CONNECTED, CAMEL_SERVICE_DISCONNECTING } CamelServiceConnectionStatus;
typedef struct { const gchar *name; /* user-friendly name */ const gchar *description; const gchar *authproto; gboolean need_password; /* needs a password to authenticate */ } CamelServiceAuthType;
const gchar * camel_service_get_display_name (CamelService *service
);
Returns the display name for service
, or NULL
if service
has not
been given a display name. The display name is intended for use in
a user interface and should generally be given a user-defined name.
Compare this with camel_service_get_name()
, which returns a built-in
description of the type of service (IMAP, SMTP, etc.).
|
a CamelService |
Returns : |
the display name for service , or NULL
|
Since 3.2
void camel_service_set_display_name (CamelService *service
,const gchar *display_name
);
Assigns a UTF-8 display name to service
. The display name is intended
for use in a user interface and should generally be given a user-defined
name.
Compare this with camel_service_get_name()
, which returns a built-in
description of the type of service (IMAP, SMTP, etc.).
|
a CamelService |
|
a valid UTF-8 string, or NULL
|
Since 3.2
const gchar * camel_service_get_password (CamelService *service
);
Returns the password for service
. Some SASL mechanisms use this
when attempting to authenticate.
|
a CamelService |
Returns : |
the password for service
|
Since 3.4
void camel_service_set_password (CamelService *service
,const gchar *password
);
Sets the password for service
. Use this function to cache the password
in memory after obtaining it through camel_session_get_password()
. Some
SASL mechanisms use this when attempting to authenticate.
|
a CamelService |
|
the password for service
|
Since 3.4
const gchar * camel_service_get_user_data_dir (CamelService *service
);
Returns the base directory under which to store user-specific data
for service
. The directory is formed by appending the directory
returned by camel_session_get_user_data_dir()
with the service's
"uid" value.
|
a CamelService |
Returns : |
the base directory for service
|
Since 3.2
const gchar * camel_service_get_user_cache_dir (CamelService *service
);
Returns the base directory under which to store cache data
for service
. The directory is formed by appending the directory
returned by camel_session_get_user_cache_dir()
with the service's
"uid" value.
|
a CamelService |
Returns : |
the base cache directory for service
|
Since 3.4
gchar * camel_service_get_name (CamelService *service
,gboolean brief
);
This gets the name of the service in a "friendly" (suitable for
humans) form. If brief
is TRUE
, this should be a brief description
such as for use in the folder tree. If brief
is FALSE
, it should
be a more complete and mostly unambiguous description.
|
a CamelService |
|
whether or not to use a briefer form |
Returns : |
a description of the service which the caller must free |
CamelProvider * camel_service_get_provider (CamelService *service
);
Gets the CamelProvider associated with the service.
|
a CamelService |
Returns : |
the CamelProvider |
struct _CamelSession * camel_service_get_session (CamelService *service
);
Gets the CamelSession associated with the service.
|
a CamelService |
Returns : |
the CamelSession |
CamelSettings * camel_service_get_settings (CamelService *service
);
Returns the CamelSettings instance associated with the service.
|
a CamelService |
Returns : |
the CamelSettings |
Since 3.2
void camel_service_set_settings (CamelService *service
,CamelSettings *settings
);
Associates a new CamelSettings instance with the service.
The settings
instance must match the settings type defined in
CamelServiceClass. If settings
is NULL
, a new CamelSettings
instance of the appropriate type is created with all properties
set to defaults.
|
a CamelService |
|
an instance derviced from CamelSettings, or NULL
|
Since 3.2
const gchar * camel_service_get_uid (CamelService *service
);
Gets the unique identifier string associated with the service.
|
a CamelService |
Returns : |
the UID string |
Since 3.2
CamelURL * camel_service_get_camel_url (CamelService *service
);
Returns the CamelURL representing service
.
|
a CamelService |
Returns : |
the CamelURL representing service
|
Since 3.2
gchar * camel_service_get_url (CamelService *service
);
Gets the URL representing service
. The returned URL must be
freed when it is no longer needed.
|
a CamelService |
Returns : |
the URL representing service
|
void camel_service_cancel_connect (CamelService *service
);
If service
is currently attempting to connect to or disconnect
from a server, this causes it to stop and fail. Otherwise it is a
no-op.
|
a CamelService |
gboolean camel_service_connect_sync (CamelService *service
,GError **error
);
Connect to the service using the parameters it was initialized with.
|
a CamelService |
|
return location for a GError, or NULL
|
Returns : |
TRUE if the connection is made or FALSE otherwise |
gboolean camel_service_disconnect_sync (CamelService *service
,gboolean clean
,GError **error
);
Disconnect from the service. If clean
is FALSE
, it should not
try to do any synchronizing or other cleanup of the connection.
|
a CamelService |
|
whether or not to try to disconnect cleanly |
|
return location for a GError, or NULL
|
Returns : |
TRUE if the disconnect was successful or FALSE otherwise |
CamelServiceConnectionStatus camel_service_get_connection_status
(CamelService *service
);
Returns the connection status for service
.
|
a CamelService |
Returns : |
the connection status |
Since 3.2
typedef enum { CAMEL_SERVICE_REC_CONNECT_LOCK, CAMEL_SERVICE_CONNECT_OP_LOCK } CamelServiceLock;
Since 2.32
void camel_service_lock (CamelService *service
,CamelServiceLock lock
);
Locks service
's lock
. Unlock it with camel_service_unlock()
.
|
a CamelService |
|
lock type to lock |
Since 2.32
void camel_service_unlock (CamelService *service
,CamelServiceLock lock
);
Unlocks service
's lock
, previously locked with camel_service_lock()
.
|
a CamelService |
|
lock type to unlock |
Since 2.32
typedef enum { CAMEL_AUTHENTICATION_ERROR, CAMEL_AUTHENTICATION_ACCEPTED, CAMEL_AUTHENTICATION_REJECTED } CamelAuthenticationResult;
Authentication result codes used by CamelService.
An error occurred while authenticating. | |
Server accepted our authentication attempt. | |
Server rejected our authentication attempt. |
Since 3.4
CamelAuthenticationResult camel_service_authenticate_sync (CamelService *service
,const gchar *mechanism
,GCancellable *cancellable
,GError **error
);
Attempts to authenticate service
using mechanism
and, if necessary,
service
's "password" property. The function makes only
ONE attempt at authentication and does not loop.
If the authentication attempt completed and the server accepted the credentials, the function returns CAMEL_AUTHENTICATION_ACCEPTED.
If the authentication attempt completed but the server rejected the credentials, the function returns CAMEL_AUTHENTICATION_REJECTED.
If the authentication attempt failed to complete due to a network
communication issue or some other mishap, the function sets error
and returns CAMEL_AUTHENTICATION_ERROR.
Generally this function should only be called from a CamelSession subclass in order to implement its own authentication loop.
|
a CamelService |
|
a SASL mechanism name, or NULL
|
|
optional GCancellable object, or NULL
|
|
return location for a GError, or NULL
|
Returns : |
the authentication result |
Since 3.4
void camel_service_authenticate (CamelService *service
,const gchar *mechanism
,gint io_priority
,GCancellable *cancellable
,GAsyncReadyCallback callback
,gpointer user_data
);
Asynchronously attempts to authenticate service
using mechanism
and,
if necessary, service
's "password" property. The function
makes only ONE attempt at authentication and does not loop.
Generally this function should only be called from a CamelSession subclass in order to implement its own authentication loop.
When the operation is finished, callback
will be called. You can
then call camel_service_authenticate_finish()
to get the result of
the operation.
|
a CamelService |
|
a SASL mechanism name, or NULL
|
|
the I/O priority of the request |
|
optional GCancellable object, or NULL
|
|
a GAsyncReadyCallback to call when the request is satisfied |
|
data to pass to the callback function |
Since 3.4
CamelAuthenticationResult camel_service_authenticate_finish (CamelService *service
,GAsyncResult *result
,GError **error
);
Finishes the operation started with camel_service_authenticate()
.
If the authentication attempt completed and the server accepted the credentials, the function returns CAMEL_AUTHENTICATION_ACCEPTED.
If the authentication attempt completed but the server rejected the credentials, the function returns CAMEL_AUTHENTICATION_REJECTED.
If the authentication attempt failed to complete due to a network
communication issue or some other mishap, the function sets error
and returns CAMEL_AUTHENTICATION_ERROR.
|
a CamelService |
|
a GAsyncResult |
|
return location for a GError, or NULL
|
Returns : |
the authentication result |
Since 3.4
GList * camel_service_query_auth_types_sync (CamelService *service
,GCancellable *cancellable
,GError **error
);
Obtains a list of authentication types supported by service
.
Free the returned list with g_list_free()
.
|
a CamelService |
|
optional GCancellable object, or NULL
|
|
return location for a GError, or NULL
|
Returns : |
a list of CamelServiceAuthType structs |
void camel_service_query_auth_types (CamelService *service
,gint io_priority
,GCancellable *cancellable
,GAsyncReadyCallback callback
,gpointer user_data
);
Asynchronously obtains a list of authentication types supported by
service
.
When the operation is finished, callback
will be called. You can
then call camel_service_query_auth_types_finish()
to get the result
of the operation.
|
a CamelService |
|
the I/O priority of the request |
|
optional GCancellable object, or NULL
|
|
a GAsyncReadyCallback to call when the request is satisfied |
|
data to pass to the callback function |
Since 3.2
GList * camel_service_query_auth_types_finish (CamelService *service
,GAsyncResult *result
,GError **error
);
Finishes the operation started with camel_service_query_auth_types()
.
Free the returned list with g_list_free()
.
|
a CamelService |
|
a GAsyncResult |
|
return location for a GError, or NULL
|
Returns : |
a list of CamelServiceAuthType structs |
Since 3.2
"display-name"
property"display-name" gchar* : Read / Write / Construct
The display name for the service.
Default value: NULL
"password"
property"password" gchar* : Read / Write / Construct
The password for the service.
Default value: NULL
"provider"
property"provider" gpointer : Read / Write / Construct Only
The CamelProvider for the service.
"session"
property"session" CamelSession* : Read / Write / Construct Only
A CamelSession instance.
"settings"
property"settings" CamelSettings* : Read / Write / Construct
A CamelSettings instance.
"uid"
property"uid" gchar* : Read / Write / Construct Only
The unique identity of the service.
Default value: NULL