CamelService

CamelService

Synopsis

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_user_data_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);
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);

Object Hierarchy

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

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;

Since 2.32


enum CamelServiceConnectionStatus

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


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_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_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_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_get_session ()

struct _CamelSession * camel_service_get_session        (CamelService *service);

Gets the CamelSession associated with the service.

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.

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.

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

CamelURL *          camel_service_get_camel_url         (CamelService *service);

Returns the CamelURL representing service.

service :

a CamelService

Returns :

the CamelURL representing service

Since 3.2


camel_service_get_url ()

gchar *             camel_service_get_url               (CamelService *service);

Gets the URL representing service. The returned URL must be freed when it is no longer needed. For security reasons, this routine does not return the password.

service :

a CamelService

Returns :

the URL representing service

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.

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.

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.

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.

service :

a CamelService

Returns :

the connection status

Since 3.2


enum CamelServiceLock

typedef enum {
	CAMEL_SERVICE_REC_CONNECT_LOCK,
	CAMEL_SERVICE_CONNECT_OP_LOCK
} CamelServiceLock;

Since 2.32


camel_service_lock ()

void                camel_service_lock                  (CamelService *service,
                                                         CamelServiceLock lock);

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

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

service :

a CamelService

lock :

lock type to unlock

Since 2.32


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