CamelService

CamelService

Synopsis

struct              CamelService;
#define             CAMEL_SERVICE_ERROR
enum                CamelServiceError;
                    CamelServiceAuthType;
void                camel_service_migrate_files         (CamelService *service);
CamelURL *          camel_service_new_camel_url         (CamelService *service);
enum                CamelServiceConnectionStatus;
CamelServiceConnectionStatus camel_service_get_connection_status
                                                        (CamelService *service);
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_ref_session        (CamelService *service);
CamelSettings *     camel_service_ref_settings          (CamelService *service);
void                camel_service_set_settings          (CamelService *service,
                                                         CamelSettings *settings);
const gchar *       camel_service_get_uid               (CamelService *service);
gboolean            camel_service_connect_sync          (CamelService *service,
                                                         GCancellable *cancellable,
                                                         GError **error);
void                camel_service_connect               (CamelService *service,
                                                         gint io_priority,
                                                         GCancellable *cancellable,
                                                         GAsyncReadyCallback callback,
                                                         gpointer user_data);
gboolean            camel_service_connect_finish        (CamelService *service,
                                                         GAsyncResult *result,
                                                         GError **error);
gboolean            camel_service_disconnect_sync       (CamelService *service,
                                                         gboolean clean,
                                                         GCancellable *cancellable,
                                                         GError **error);
void                camel_service_disconnect            (CamelService *service,
                                                         gboolean clean,
                                                         gint io_priority,
                                                         GCancellable *cancellable,
                                                         GAsyncReadyCallback callback,
                                                         gpointer user_data);
gboolean            camel_service_disconnect_finish     (CamelService *service,
                                                         GAsyncResult *result,
                                                         GError **error);
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);

struct _CamelSession * camel_service_get_session        (CamelService *service);

Object Hierarchy

  GObject
   +----CamelObject
         +----CamelService
               +----CamelStore
               +----CamelTransport

Known Derived Interfaces

CamelService is required by CamelNetworkService.

Implemented Interfaces

CamelService implements GInitable.

Properties

  "connection-status"        CamelServiceConnectionStatus  : Read
  "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

Description

Details

struct CamelService

struct CamelService;

CAMEL_SERVICE_ERROR

#define             CAMEL_SERVICE_ERROR

Since 2.32


enum CamelServiceError

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;

CAMEL_SERVICE_ERROR_INVALID

CAMEL_SERVICE_ERROR_URL_INVALID

CAMEL_SERVICE_ERROR_UNAVAILABLE

CAMEL_SERVICE_ERROR_CANT_AUTHENTICATE

CAMEL_SERVICE_ERROR_NOT_CONNECTED

Since 2.32


CamelServiceAuthType

typedef struct {
	const gchar *name;               /* user-friendly name */
	const gchar *description;
	const gchar *authproto;

	gboolean need_password;   /* needs a password to authenticate */
} CamelServiceAuthType;

camel_service_migrate_files ()

void                camel_service_migrate_files         (CamelService *service);

Performs any necessary file migrations for service. This should be called after installing or configuring the service's CamelSettings, since it requires building a URL string for service.

service :

a CamelService

Since 3.4


camel_service_new_camel_url ()

CamelURL *          camel_service_new_camel_url         (CamelService *service);

Returns a new CamelURL representing service. Free the returned CamelURL with camel_url_free().

service :

a CamelService

Returns :

a new CamelURL

Since 3.2


enum CamelServiceConnectionStatus

typedef enum {
	CAMEL_SERVICE_DISCONNECTED,
	CAMEL_SERVICE_CONNECTING,
	CAMEL_SERVICE_CONNECTED,
	CAMEL_SERVICE_DISCONNECTING
} CamelServiceConnectionStatus;

Connection status returned by camel_service_get_connection_status().

CAMEL_SERVICE_DISCONNECTED

CamelService is disconnected from a remote server.

CAMEL_SERVICE_CONNECTING

CamelService is connecting to a remote server.

CAMEL_SERVICE_CONNECTED

CamelService is connected to a remote server.

CAMEL_SERVICE_DISCONNECTING

CamelService is disconnecting from a remote server.

Since 3.6


camel_service_get_connection_status ()

CamelServiceConnectionStatus camel_service_get_connection_status
                                                        (CamelService *service);

Returns the connection status for service.

service :

a CamelService

Returns :

the connection status

Since 3.2


camel_service_get_display_name ()

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.).

service :

a CamelService

Returns :

the display name for service, or NULL

Since 3.2


camel_service_set_display_name ()

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.).

service :

a CamelService

display_name :

a valid UTF-8 string, or NULL

Since 3.2


camel_service_get_password ()

const gchar *       camel_service_get_password          (CamelService *service);

Returns the password for service. Some SASL mechanisms use this when attempting to authenticate.

service :

a CamelService

Returns :

the password for service

Since 3.4


camel_service_set_password ()

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.

service :

a CamelService

password :

the password for service

Since 3.4


camel_service_get_user_data_dir ()

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.

service :

a CamelService

Returns :

the base directory for service

Since 3.2


camel_service_get_user_cache_dir ()

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.

service :

a CamelService

Returns :

the base cache directory for service

Since 3.4


camel_service_get_name ()

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.

service :

a CamelService

brief :

whether or not to use a briefer form

Returns :

a description of the service which the caller must free

camel_service_get_provider ()

CamelProvider *     camel_service_get_provider          (CamelService *service);

Gets the CamelProvider associated with the service.

service :

a CamelService

Returns :

the CamelProvider

camel_service_ref_session ()

struct _CamelSession * camel_service_ref_session        (CamelService *service);

Returns the CamelSession associated with the service.

The returned CamelSession is referenced for thread-safety. Unreference the CamelSession with g_object_unref() when finished with it.

service :

a CamelService

Returns :

the CamelSession

Since 3.8


camel_service_ref_settings ()

CamelSettings *     camel_service_ref_settings          (CamelService *service);

Returns the CamelSettings instance associated with the service.

The returned CamelSettings is referenced for thread-safety and must be unreferenced with g_object_unref() when finished with it.

service :

a CamelService

Returns :

the CamelSettings

Since 3.6


camel_service_set_settings ()

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.

service :

a CamelService

settings :

an instance derviced from CamelSettings, or NULL

Since 3.2


camel_service_get_uid ()

const gchar *       camel_service_get_uid               (CamelService *service);

Gets the unique identifier string associated with the service.

service :

a CamelService

Returns :

the UID string

Since 3.2


camel_service_connect_sync ()

gboolean            camel_service_connect_sync          (CamelService *service,
                                                         GCancellable *cancellable,
                                                         GError **error);

Connects service to a remote server using the information in its "settings" instance.

If a connect operation is already in progress when this function is called, its results will be reflected in this connect operation.

service :

a CamelService

cancellable :

optional GCancellable object, or NULL

error :

return location for a GError, or NULL

Returns :

TRUE if the connection is made or FALSE otherwise

Since 3.6


camel_service_connect ()

void                camel_service_connect               (CamelService *service,
                                                         gint io_priority,
                                                         GCancellable *cancellable,
                                                         GAsyncReadyCallback callback,
                                                         gpointer user_data);

Asynchronously connects service to a remote server using the information in its "settings" instance.

If a connect operation is already in progress when this function is called, its results will be reflected in this connect operation.

If any disconnect operations are in progress when this function is called, they will be cancelled.

When the operation is finished, callback will be called. You can then call camel_service_connect_finish() to get the result of the operation.

service :

a CamelService

io_priority :

the I/O priority of the request

cancellable :

optional GCancellable object, or NULL

callback :

a GAsyncReadyCallback to call when the request is satisfied

user_data :

data to pass to the callback function

Since 3.6


camel_service_connect_finish ()

gboolean            camel_service_connect_finish        (CamelService *service,
                                                         GAsyncResult *result,
                                                         GError **error);

Finishes the operation started with camel_service_connect().

service :

a CamelService

result :

a GAsyncResult

error :

return location for a GError, or NULL

Returns :

TRUE if the connection was made or FALSE otherwise

Since 3.6


camel_service_disconnect_sync ()

gboolean            camel_service_disconnect_sync       (CamelService *service,
                                                         gboolean clean,
                                                         GCancellable *cancellable,
                                                         GError **error);

Disconnect from the service. If clean is FALSE, it should not try to do any synchronizing or other cleanup of the connection.

If a disconnect operation is already in progress when this function is called, its results will be reflected in this disconnect operation.

If any connect operations are in progress when this function is called, they will be cancelled.

service :

a CamelService

clean :

whether or not to try to disconnect cleanly

cancellable :

optional GCancellable object, or NULL

error :

return location for a GError, or NULL

Returns :

TRUE if the connection was severed or FALSE otherwise

Since 3.6


camel_service_disconnect ()

void                camel_service_disconnect            (CamelService *service,
                                                         gboolean clean,
                                                         gint io_priority,
                                                         GCancellable *cancellable,
                                                         GAsyncReadyCallback callback,
                                                         gpointer user_data);

If a disconnect operation is already in progress when this function is called, its results will be reflected in this disconnect operation.

If any connect operations are in progress when this function is called, they will be cancelled.

When the operation is finished, callback will be called. You can then call camel_service_disconnect_finish() to get the result of the operation.

service :

a CamelService

clean :

whether or not to try to disconnect cleanly

io_priority :

the I/O priority of the request

cancellable :

optional GCancellable object, or NULL

callback :

a GAsyncReadyCallback to call when the request is satisfied

user_data :

data to pass to the callback function

Since 3.6


camel_service_disconnect_finish ()

gboolean            camel_service_disconnect_finish     (CamelService *service,
                                                         GAsyncResult *result,
                                                         GError **error);

Finishes the operation started with camel_service_disconnect().

service :

a CamelService

result :

a GAsyncResult

error :

return location for a GError, or NULL

Returns :

TRUE if the connection was severed or FALSE otherwise

Since 3.6


enum CamelAuthenticationResult

typedef enum {
	CAMEL_AUTHENTICATION_ERROR,
	CAMEL_AUTHENTICATION_ACCEPTED,
	CAMEL_AUTHENTICATION_REJECTED
} CamelAuthenticationResult;

Authentication result codes used by CamelService.

CAMEL_AUTHENTICATION_ERROR

An error occurred while authenticating.

CAMEL_AUTHENTICATION_ACCEPTED

Server accepted our authentication attempt.

CAMEL_AUTHENTICATION_REJECTED

Server rejected our authentication attempt.

Since 3.4


camel_service_authenticate_sync ()

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.

service :

a CamelService

mechanism :

a SASL mechanism name, or NULL

cancellable :

optional GCancellable object, or NULL

error :

return location for a GError, or NULL

Returns :

the authentication result

Since 3.4


camel_service_authenticate ()

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.

service :

a CamelService

mechanism :

a SASL mechanism name, or NULL

io_priority :

the I/O priority of the request

cancellable :

optional GCancellable object, or NULL

callback :

a GAsyncReadyCallback to call when the request is satisfied

user_data :

data to pass to the callback function

Since 3.4


camel_service_authenticate_finish ()

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.

service :

a CamelService

result :

a GAsyncResult

error :

return location for a GError, or NULL

Returns :

the authentication result

Since 3.4


camel_service_query_auth_types_sync ()

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().

service :

a CamelService

cancellable :

optional GCancellable object, or NULL

error :

return location for a GError, or NULL

Returns :

a list of CamelServiceAuthType structs

camel_service_query_auth_types ()

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.

service :

a CamelService

io_priority :

the I/O priority of the request

cancellable :

optional GCancellable object, or NULL

callback :

a GAsyncReadyCallback to call when the request is satisfied

user_data :

data to pass to the callback function

Since 3.2


camel_service_query_auth_types_finish ()

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().

service :

a CamelService

result :

a GAsyncResult

error :

return location for a GError, or NULL

Returns :

a list of CamelServiceAuthType structs

Since 3.2


camel_service_get_session ()

struct _CamelSession * camel_service_get_session        (CamelService *service);

Warning

camel_service_get_session has been deprecated since version 3.8 and should not be used in newly-written code. Use camel_service_ref_session() instead.

Returns the CamelSession associated with the service.

Note this function is not thread-safe. The returned CamelSession could be finalized by another thread while the caller is still using it.

service :

a CamelService

Returns :

the CamelSession

Property Details

The "connection-status" property

  "connection-status"        CamelServiceConnectionStatus  : Read

The connection status for the service.

Default value: CAMEL_SERVICE_DISCONNECTED


The "display-name" property

  "display-name"             gchar*                : Read / Write / Construct

The display name for the service.

Default value: NULL


The "password" property

  "password"                 gchar*                : Read / Write / Construct

The password for the service.

Default value: NULL


The "provider" property

  "provider"                 gpointer              : Read / Write / Construct Only

The CamelProvider for the service.


The "session" property

  "session"                  CamelSession*         : Read / Write / Construct Only

A CamelSession instance.


The "settings" property

  "settings"                 CamelSettings*        : Read / Write / Construct

A CamelSettings instance.


The "uid" property

  "uid"                      gchar*                : Read / Write / Construct Only

The unique identity of the service.

Default value: NULL