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);
char*               camel_service_get_url               (CamelService *service);
char*               camel_service_get_name              (CamelService *service,
                                                         gboolean brief);
char*               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 {
	char *name;               /* user-friendly name */
	char *description;
	char *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 ()

char*               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 ()

char*               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 ()

char*               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.