## 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);
    gchar *             camel_service_dup_display_name      (CamelService *service);
    void                camel_service_set_display_name      (CamelService *service,
                                                             const gchar *display_name);
    const gchar *       camel_service_get_password          (CamelService *service);
    gchar *             camel_service_dup_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);
    GProxyResolver *    camel_service_ref_proxy_resolver    (CamelService *service);
    void                camel_service_set_proxy_resolver    (CamelService *service,
                                                             GProxyResolver *proxy_resolver);
    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);
    void                camel_service_queue_task            (CamelService *service,
                                                             GTask *task,
                                                             GTaskThreadFunc task_func);
    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);

## 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
      "proxy-resolver"           GProxyResolver*       : Read / Write
      "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_dup_display_name ()

    gchar *             camel_service_dup_display_name      (CamelService *service);

Thread-safe variation of `camel_service_get_display_name()`. Use this function when accessing `service` from multiple threads.

The returned string should be freed with `g_free()` when no longer needed.

`service` : | a CamelService
Returns : | a newly-allocated copy of "display-name"

Since 3.12

### 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_dup_password ()

    gchar *             camel_service_dup_password          (CamelService *service);

Thread-safe variation of `camel_service_get_password()`. Use this function when accessing `service` from multiple threads.

The returned string should be freed with `g_free()` when no longer needed.

`service` : | a CamelService
Returns : | a newly-allocated copy of "password"

Since 3.12

### 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_proxy_resolver ()

    GProxyResolver *    camel_service_ref_proxy_resolver    (CamelService *service);

Returns the GProxyResolver for `service`. If an application needs to override this, it should do so prior to calling functions on `service` that may require a network connection.

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

`service` : | a CamelService
Returns : | a GProxyResolver, or `NULL`

Since 3.12

### camel_service_set_proxy_resolver ()

    void                camel_service_set_proxy_resolver    (CamelService *service,
                                                             GProxyResolver *proxy_resolver);

Sets the GProxyResolver for `service`. If an application needs to override this, it should do so prior to calling functions on `service` that may require a network connection.

`service` : | a CamelService
`proxy_resolver` : | a GProxyResolver, or `NULL` for the default

Since 3.12

### 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_queue_task ()

    void                camel_service_queue_task            (CamelService *service,
                                                             GTask *task,
                                                             GTaskThreadFunc task_func);

Adds `task` to a queue of waiting tasks with the same source object. Queued tasks execute one at a time in the order they were added. When `task` reaches the front of the queue, it will be dispatched by invoking `task_func` in a separate thread. If `task` is cancelled while queued, it will complete immediately with an appropriate error.

This is primarily intended for use by CamelStore, CamelTransport and CamelFolder to achieve ordered invocation of synchronous class methods.

`service` : | a CamelService
`task` : | a GTask
`task_func` : | function to call when `task` is dispatched

Since 3.12

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

## 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 `"proxy-resolver"` property

      "proxy-resolver"           GProxyResolver*       : Read / Write

The proxy resolver 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