add CamelExceptions to several functions. Use camel_session_new to

        * camel-session.h:
        * camel-session.c: add CamelExceptions to several functions. Use
        camel_session_new to initialize the session and URL fields of
        created CamelStores as appropriate.

        * camel-store.h:
        * camel-store.c
        * camel-service.h:
        * camel-service.c: Move the session and url (and associated
        functions) from CamelStore to CamelService. Add url_flags to
        CamelService so subclasses can specify which URL components
        are mandatory for them. Add camel_session_new for
        camel_session_get_store* to use.

        * providers/mbox/camel-mbox-folder.c:
        * providers/mbox/camel-mbox-store.c:
        * providers/mbox/camel-mbox-store.h: Update for above changes.

svn path=/trunk/; revision=1888

1 files changed, 140 insertions, 23 deletions

diff --git a/camel/camel-service.c b/camel/camel-service.c
index 0b4d2bf853..0bd2b42d01 100644
--- a/camel/camel-service.c
+++ b/camel/camel-service.c
@@ -26,6 +26,7 @@
 #include <config.h>
 #include "camel-service.h"
 #include "camel-log.h"
+#include "camel-exception.h"
 
 static GtkObjectClass *parent_class=NULL;
 
@@ -38,6 +39,8 @@ static gboolean _connect_with_url (CamelService *service, Gurl *url,
 static gboolean _disconnect(CamelService *service, CamelException *ex);
 static gboolean _is_connected (CamelService *service);
 static void _finalize (GtkObject *object);
+static gboolean _set_url (CamelService *service, Gurl *url,
+			  CamelException *ex);
 
 static void
 camel_service_class_init (CamelServiceClass *camel_service_class)
@@ -92,27 +95,67 @@ _finalize (GtkObject *object)
 
 	if (camel_service->url)
 		g_url_free (camel_service->url);
+	if (camel_service->session)
+		gtk_object_unref (GTK_OBJECT (camel_service->session));
 
 	GTK_OBJECT_CLASS (parent_class)->finalize (object);
 	CAMEL_LOG_FULL_DEBUG ("Leaving CamelService::finalize\n");
 }
 
 
+/**
+ * camel_service_new: create a new CamelService or subtype
+ * @type: the GtkType of the class to create
+ * @session: the session for the service
+ * @url: the default URL for the service (may be NULL)
+ * @ex: a CamelException
+ *
+ * Creates a new CamelService (or one of its subtypes), initialized
+ * with the given parameters.
+ *
+ * Return value: the CamelService, or NULL.
+ **/
+CamelService *
+camel_service_new (GtkType type, CamelSession *session, Gurl *url,
+		   CamelException *ex)
+{
+	CamelService *service;
+
+	g_assert(session);
+
+	service = CAMEL_SERVICE (gtk_object_new (type, NULL));
+	service->session = session;
+	gtk_object_ref (GTK_OBJECT (session));
+	if (url) {
+		if (!_set_url (service, url, ex))
+			return NULL;
+	}
+
+	return service;
+}
 
 /**
  * _connect : connect to a service 
+ * @service: object to connect
+ * @ex: a CamelException
  *
  * connect to the service using the parameters 
  * stored in the session it is initialized with
- * WARNING: session not implemented for the moment
  *
- * @service: object to connect
+ * Return value: whether or not the connection succeeded
  **/
 static gboolean
 _connect (CamelService *service, CamelException *ex)
 {
-#warning need to get default URL from somewhere
-	return CSERV_CLASS(service)->connect_with_url(service, NULL, ex);
+	g_assert (service->session);
+	/* XXX it's possible that this should be an exception
+	 * rather than an assertion... I'm not sure how the code
+	 * is supposed to be used.
+	 */
+	g_assert (service->url);
+
+	service->connected = TRUE;
+	return TRUE;
 }
 
 
@@ -120,11 +163,12 @@ _connect (CamelService *service, CamelException *ex)
 /**
  * camel_service_connect:connect to a service 
  * @service: CamelService object
+ * @ex: a CamelException
  * 
  * connect to the service using the parameters 
  * stored in the session it is initialized with
- * WARNING: session not implemented for the moment
- * 
+ *
+ * Return value: whether or not the connection succeeded
  **/
 gboolean
 camel_service_connect (CamelService *service, CamelException *ex)
@@ -136,30 +180,36 @@ camel_service_connect (CamelService *service, CamelException *ex)
 
 /**
  * _connect_with_url: connect to the specified address
- * 
+ * @service: object to connect
+ * @url: URL describing service to connect to
+ * @ex: a CamelException
+ *
  * Connect to the service, but do not use the session
  * default parameters to retrieve server's address
  *
- * @service: object to connect
- * @url: URL describing service to connect to
+ * Return value: whether or not the connection succeeded
  **/
 static gboolean
 _connect_with_url (CamelService *service, Gurl *url, CamelException *ex)
 {
-	service->connected = TRUE;
-	service->url = url;
+	g_assert (service->session);
 
-	return TRUE;
+	if (!_set_url (service, url, ex))
+		return FALSE;
+
+	return CSERV_CLASS(service)->connect (service, ex);
 }
 
 /**
  * camel_service_connect_with_url: connect a service 
  * @service:  the service to connect
  * @url:  URL describing the service to connect to
+ * @ex: a CamelException
  * 
  * Connect to a service, but do not use the session
  * default parameters to retrieve server's address
- * 
+ *
+ * Return value: whether or not the connection succeeded
  **/
 gboolean
 camel_service_connect_with_url (CamelService *service, char *url,
@@ -173,19 +223,18 @@ camel_service_connect_with_url (CamelService *service, char *url,
 
 /**
  * _disconnect : disconnect from a service 
+ * @service: object to disconnect
+ * @ex: a CamelException
  *
  * disconnect from the service
  *
- * @service: object to disconnect
+ * Return value: whether or not the disconnection succeeded without
+ * errors. (Consult @ex if FALSE.)
  **/
 static gboolean
 _disconnect (CamelService *service, CamelException *ex)
 {
 	service->connected = FALSE;
-	if (service->url) {
-		g_url_free(service->url);
-		service->url = NULL;
-	}
 
 	return TRUE;
 }
@@ -195,6 +244,12 @@ _disconnect (CamelService *service, CamelException *ex)
 /**
  * camel_service_disconnect: disconnect from a service 
  * @service: CamelService object
+ * @ex: a CamelException
+ *
+ * disconnect from the service
+ *
+ * Return value: whether or not the disconnection succeeded without
+ * errors. (Consult @ex if FALSE.)
  **/
 gboolean
 camel_service_disconnect (CamelService *service, CamelException *ex)
@@ -208,7 +263,7 @@ camel_service_disconnect (CamelService *service, CamelException *ex)
  * _is_connected: test if the service object is connected
  * @service: object to test
  * 
- * Return value: 
+ * Return value: whether or not the service is connected
  **/
 static gboolean
 _is_connected (CamelService *service)
@@ -221,7 +276,7 @@ _is_connected (CamelService *service)
  * camel_service_is_connected: test if the service object is connected
  * @service: object to test
  * 
- * Return value: 
+ * Return value: whether or not the service is connected
  **/
 gboolean
 camel_service_is_connected (CamelService *service)
@@ -231,18 +286,80 @@ camel_service_is_connected (CamelService *service)
 
 
 /**
+ * _set_url: Validate a URL and set it as the default for a service
+ * @service: the CamelService
+ * @url_string: the URL
+ * @ex: a CamelException
+ *
+ * This converts the URL to a Gurl, validates it for the service,
+ * and sets it as the default URL for the service.
+ *
+ * Return value: success or failure
+ **/
+static gboolean
+_set_url (CamelService *service, Gurl *url, CamelException *ex)
+{
+	char *url_string;
+
+	if (service->url_flags & CAMEL_SERVICE_URL_NEED_USER &&
+	    (url->user == NULL || url->user[0] == '\0')) {
+		url_string = g_url_to_string (url, FALSE);
+		camel_exception_setv (ex, CAMEL_EXCEPTION_SERVICE_URL_INVALID,
+				      "URL '%s' needs a username component",
+				      url_string);
+		g_free (url_string);
+		return FALSE;
+	} else if (service->url_flags & CAMEL_SERVICE_URL_NEED_HOST &&
+		   (url->host == NULL || url->host[0] == '\0')) {
+		url_string = g_url_to_string (url, FALSE);
+		camel_exception_setv (ex, CAMEL_EXCEPTION_SERVICE_URL_INVALID,
+				      "URL '%s' needs a host component",
+				      url_string);
+		g_free (url_string);
+		return FALSE;
+	} else if (service->url_flags & CAMEL_SERVICE_URL_NEED_PATH &&
+		   (url->path == NULL || url->path[0] == '\0')) {
+		url_string = g_url_to_string (url, FALSE);
+		camel_exception_setv (ex, CAMEL_EXCEPTION_SERVICE_URL_INVALID,
+				      "URL '%s' needs a path component",
+				      url_string);
+		g_free (url_string);
+		return FALSE;
+	}
+
+	if (service->url)
+		g_url_free (service->url);
+	service->url = url;
+	return TRUE;
+}
+
+/**
  * camel_service_get_url: get the url representing a service
  * @service: the service
  * 
- * returns the URL representing a service. For security reasons 
- * This routine does not return the password. 
+ * returns the URL representing a service. The returned URL must be
+ * freed when it is no longer needed. For security reasons, this
+ * routine does not return the password.
  * 
  * Return value: the url name
  **/
-gchar *
+char *
 camel_service_get_url (CamelService *service)
 {
 	return g_url_to_string(service->url, FALSE);
 }
 
 
+/**
+ * camel_service_get_session: return the session associated with a service
+ * @service: the service
+ *
+ * returns the CamelSession associated with the service.
+ *
+ * Return value: the session
+ **/
+CamelSession *
+camel_service_get_session (CamelService *service)
+{
+	return service->session;
+}