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.