CamelService

## CamelService CamelService |

## Synopsis

    struct              CamelService;
    #define             CAMEL_SERVICE_USERNAME
    #define             CAMEL_SERVICE_AUTH
    #define             CAMEL_SERVICE_HOSTNAME
    #define             CAMEL_SERVICE_PORT
    #define             CAMEL_SERVICE_PATH
    enum                CamelServiceConnectionStatus;
                        CamelServiceAuthType;
    void                camel_service_construct             (CamelService *service,
                                                             CamelSession *session,
                                                             CamelProvider *provider,
                                                             CamelURL *url,
                                                             CamelException *ex);
    gboolean            camel_service_connect               (CamelService *service,
                                                             CamelException *ex);
    gboolean            camel_service_disconnect            (CamelService *service,
                                                             gboolean clean,
                                                             CamelException *ex);
    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);
    CamelSession *      camel_service_get_session           (CamelService *service);
    CamelProvider *     camel_service_get_provider          (CamelService *service);
    GList *             camel_service_query_auth_types      (CamelService *service,
                                                             CamelException *ex);

## Description

## Details

### struct CamelService

    struct CamelService {
    	CamelObject parent_object;
    	struct _CamelServicePrivate *priv;

    	CamelSession *session;
    	CamelProvider *provider;
    	CamelServiceConnectionStatus status;
    	CamelOperation *connect_op;
    	CamelURL *url;
    };

### CAMEL_SERVICE_USERNAME

    #define CAMEL_SERVICE_USERNAME     (CAMEL_SERVICE_ARG_USERNAME | CAMEL_ARG_STR)

### CAMEL_SERVICE_AUTH

    #define CAMEL_SERVICE_AUTH         (CAMEL_SERVICE_ARG_AUTH | CAMEL_ARG_STR)

### CAMEL_SERVICE_HOSTNAME

    #define CAMEL_SERVICE_HOSTNAME     (CAMEL_SERVICE_ARG_HOSTNAME | CAMEL_ARG_STR)

### CAMEL_SERVICE_PORT

    #define CAMEL_SERVICE_PORT         (CAMEL_SERVICE_ARG_PORT | CAMEL_ARG_INT)

### CAMEL_SERVICE_PATH

    #define CAMEL_SERVICE_PATH         (CAMEL_SERVICE_ARG_PATH | CAMEL_ARG_STR)

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

    void                camel_service_construct             (CamelService *service,
                                                             CamelSession *session,
                                                             CamelProvider *provider,
                                                             CamelURL *url,
                                                             CamelException *ex);

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`)
`ex` : | a CamelException

### camel_service_connect ()

    gboolean            camel_service_connect               (CamelService *service,
                                                             CamelException *ex);

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

`service` : | a CamelService object
`ex` : | a CamelException
Returns : | `TRUE` if the connection is made or `FALSE` otherwise

### camel_service_disconnect ()

    gboolean            camel_service_disconnect            (CamelService *service,
                                                             gboolean clean,
                                                             CamelException *ex);

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
`ex` : | a CamelException
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 ()

    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,
                                                             CamelException *ex);

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
`ex` : | a CamelException
Returns : | a list of CamelServiceAuthType records. The caller must free the list with g_list_free when it is done with it.