CamelService

CamelService

Functions

Properties

gchar * display-name Read / Write / Construct
gchar * password Read / Write / Construct
gpointer provider Read / Write / Construct Only
CamelSession * session Read / Write / Construct Only
CamelSettings * settings Read / Write / Construct
gchar * uid Read / Write / Construct Only

Types and Values

Object Hierarchy

    GObject
    ╰── CamelObject
        ╰── CamelService
            ├── CamelStore
            ╰── CamelTransport

Known Derived Interfaces

CamelService is required by CamelNetworkService.

Implemented Interfaces

CamelService implements GInitable.

Description

Functions

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 .

Parameters

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

Parameters

service

a CamelService

 

Returns

a new CamelURL

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

Parameters

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

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

service

a CamelService

 

Returns

the CamelProvider


camel_service_get_session ()

struct _CamelSession *
camel_service_get_session (CamelService *service);

Gets the CamelSession associated with the service.

Parameters

service

a CamelService

 

Returns

the CamelSession


camel_service_get_settings ()

CamelSettings *
camel_service_get_settings (CamelService *service);

Returns the CamelSettings instance associated with the service.

Parameters

service

a CamelService

 

Returns

the CamelSettings

Since 3.2


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.

Parameters

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.

Parameters

service

a CamelService

 

Returns

the UID string

Since 3.2


camel_service_cancel_connect ()

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.

Parameters

service

a CamelService

 

camel_service_connect_sync ()

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

Connect to the service using the parameters it was initialized with.

Parameters

service

a CamelService

 

error

return location for a GError, or NULL

 

Returns

TRUE if the connection is made or FALSE otherwise


camel_service_disconnect_sync ()

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.

Parameters

service

a CamelService

 

clean

whether or not to try to disconnect cleanly

 

error

return location for a GError, or NULL

 

Returns

TRUE if the disconnect was successful or FALSE otherwise


camel_service_get_connection_status ()

CamelServiceConnectionStatus
camel_service_get_connection_status (CamelService *service);

Returns the connection status for service .

Parameters

service

a CamelService

 

Returns

the connection status

Since 3.2


camel_service_lock ()

void
camel_service_lock (CamelService *service,
                    CamelServiceLock lock);

Locks service 's lock . Unlock it with camel_service_unlock().

Parameters

service

a CamelService

 

lock

lock type to lock

 

Since 2.32


camel_service_unlock ()

void
camel_service_unlock (CamelService *service,
                      CamelServiceLock lock);

Unlocks service 's lock , previously locked with camel_service_lock().

Parameters

service

a CamelService

 

lock

lock type to unlock

 

Since 2.32


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.

Parameters

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.

Parameters

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.

Parameters

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

Parameters

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.

Parameters

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

Parameters

service

a CamelService

 

result

a GAsyncResult

 

error

return location for a GError, or NULL

 

Returns

a list of CamelServiceAuthType structs

Since 3.2

Types and Values

struct CamelService

struct CamelService;

CAMEL_SERVICE_ERROR

#define             CAMEL_SERVICE_ERROR

Since 2.32


enum CamelServiceError

Members

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


enum CamelServiceConnectionStatus

Members

CAMEL_SERVICE_DISCONNECTED

   

CAMEL_SERVICE_CONNECTING

   

CAMEL_SERVICE_CONNECTED

   

CAMEL_SERVICE_DISCONNECTING

   

CamelServiceAuthType

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

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

enum CamelServiceLock

Members

CAMEL_SERVICE_REC_CONNECT_LOCK

   

CAMEL_SERVICE_CONNECT_OP_LOCK

   

Since 2.32


enum CamelAuthenticationResult

Authentication result codes used by CamelService.

Members

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

Property Details

The “display-name” property

  “display-name”             gchar *

The display name for the service.

Flags: Read / Write / Construct

Default value: NULL


The “password” property

  “password”                 gchar *

The password for the service.

Flags: Read / Write / Construct

Default value: NULL


The “provider” property

  “provider”                 gpointer

The CamelProvider for the service.

Flags: Read / Write / Construct Only


The “session” property

  “session”                  CamelSession *

A CamelSession instance.

Flags: Read / Write / Construct Only


The “settings” property

  “settings”                 CamelSettings *

A CamelSettings instance.

Flags: Read / Write / Construct


The “uid” property

  “uid”                      gchar *

The unique identity of the service.

Flags: Read / Write / Construct Only

Default value: NULL