## CamelService

CamelService

## Synopsis

                        CamelService;
    #define             CAMEL_SERVICE_ERROR
    enum                CamelServiceError;
    enum                CamelServiceConnectionStatus;
                        CamelServiceAuthType;
    gboolean            camel_service_construct             (CamelService *service,
                                                             struct _CamelSession *session,
                                                             CamelProvider *provider,
                                                             CamelURL *url,
                                                             GError **error);
    gboolean            camel_service_connect               (CamelService *service,
                                                             GError **error);
    gboolean            camel_service_disconnect            (CamelService *service,
                                                             gboolean clean,
                                                             GError **error);
    void                camel_service_cancel_connect        (CamelService *service);
    gchar *             camel_service_get_url               (CamelService *service);
    gchar *             camel_service_get_name              (CamelService *service,
                                                             gboolean brief);
    gchar *             camel_service_get_path              (CamelService *service);
    struct _CamelSession * camel_service_get_session        (CamelService *service);
    CamelProvider *     camel_service_get_provider          (CamelService *service);
    GList *             camel_service_query_auth_types      (CamelService *service,
                                                             GError **error);
    enum                CamelServiceLock;
    void                camel_service_lock                  (CamelService *service,
                                                             CamelServiceLock lock);
    void                camel_service_unlock                (CamelService *service,
                                                             CamelServiceLock lock);

## Object Hierarchy

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

## Description

## Details

### CamelService

    typedef struct _CamelService 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_construct ()

    gboolean            camel_service_construct             (CamelService *service,
                                                             struct _CamelSession *session,
                                                             CamelProvider *provider,
                                                             CamelURL *url,
                                                             GError **error);

Constructs a CamelService initialized with the given parameters.

`service` : | a CamelService object
`session` : | the CamelSession for `service`
`provider` : | the CamelProvider associated with `service`
`url` : | the default URL for the service (may be `NULL`)
`error` : | return location for a GError, or `NULL`
Returns : | `TRUE` on success, `FALSE` on failure

### camel_service_connect ()

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

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

`service` : | a CamelService object
`error` : | return location for a GError, or `NULL`
Returns : | `TRUE` if the connection is made or `FALSE` otherwise

### camel_service_disconnect ()

    gboolean            camel_service_disconnect            (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 object
`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_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 object

### 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 object
Returns : | the URL representing `service`

### 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 object
`brief` : | whether or not to use a briefer form
Returns : | a description of the service which the caller must free

### camel_service_get_path ()

    gchar *             camel_service_get_path              (CamelService *service);

This gets a valid UNIX relative path describing `service`, which is guaranteed to be different from the path returned for any different service. This path MUST start with the name of the provider, followed by a "/", but after that, it is up to the provider.

`service` : | a CamelService object
Returns : | the path, which the caller must free

### camel_service_get_session ()

    struct _CamelSession * camel_service_get_session        (CamelService *service);

Gets the CamelSession associated with the service.

`service` : | a CamelService object
Returns : | the session

### camel_service_get_provider ()

    CamelProvider *     camel_service_get_provider          (CamelService *service);

Gets the CamelProvider associated with the service.

`service` : | a CamelService object
Returns : | the provider

### camel_service_query_auth_types ()

    GList *             camel_service_query_auth_types      (CamelService *service,
                                                             GError **error);

This is used by the mail source wizard to get the list of authentication types supported by the protocol, and information about them.

`service` : | a CamelService object
`error` : | return location for a GError, or `NULL`
Returns : | a list of CamelServiceAuthType records. The caller must free the list with g_list_free when it is done with it.

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