CamelService

## CamelService CamelService |

## Synopsis

    struct              CamelService;
    #define             CAMEL_SERVICE_ERROR
    enum                CamelServiceError;
    enum                CamelServiceConnectionStatus;
                        CamelServiceAuthType;
    void                camel_service_migrate_files         (CamelService *service);
    CamelURL *          camel_service_new_camel_url         (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_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);
    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);

## Object Hierarchy

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

## Known Derived Interfaces

CamelService is required by CamelNetworkService.

## Implemented Interfaces

CamelService implements GInitable.

## Properties

      "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;

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_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

### 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_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_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

### 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

## Property Details

### 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