/* -*- Mode: C; tab-width: 8; indent-tabs-mode: t; c-basic-offset: 8 -*- */
/*
 *
 * Author:
 *   Nat Friedman (nat@ximian.com)
 *
 * Copyright 2000, Ximian, Inc.
 */

#include <Bonobo.idl>

module GNOME {
module Evolution {
module Addressbook {
	typedef string ContactId;
	typedef string VCard;
	typedef sequence<VCard> VCardList;
	typedef sequence<ContactId> ContactIdList;
	typedef sequence<string> stringlist;

	enum BookChangeType {
		ContactAdded,
		ContactModified,
		ContactDeleted
	};

	struct BookChangeItem {
		BookChangeType changeType;
		VCard vcard;
	};

	typedef sequence<BookChangeItem> BookChangeList;

	enum CallStatus {
		Success,
		RepositoryOffline,
		PermissionDenied,
		ContactNotFound,
		ContactIdAlreadyExists,
		AuthenticationFailed,
		AuthenticationRequired,
		UnsupportedField,
		UnsupportedAuthenticationMethod,
		TLSNotAvailable,
		NoSuchBook,
		BookRemoved,
		OfflineUnavailable,
		
		/* These can be returned for successful searches, but
		   indicate the result set was truncated */
		SearchSizeLimitExceeded,
		SearchTimeLimitExceeded,

		InvalidQuery,
		QueryRefused,

		CouldNotCancel,

		OtherError,
		InvalidServerVersion	

	};

	typedef long BookMode;
	const BookMode MODE_LOCAL   = 1 << 0;
	const BookMode MODE_REMOTE  = 1 << 1;
	const BookMode MODE_ANY     = 0x07;

	/* 
	 * A book view is a live view of a book.  It's either a view
	 * of all the contacts in the book or a view of a query.  When
	 * created, it will get a series of notifyContactsAdded calls
	 * for all objects in the initial set.  After that, it will
	 * get added, removed, or changed signals whenever the book
	 * changes (if it affects the set of viewed contacts.)
	 */
	interface BookViewListener : Bonobo::Unknown {
		oneway void notifyContactsAdded    (in VCardList vcards);
		oneway void notifyContactsRemoved  (in ContactIdList ids);
		oneway void notifyContactsChanged  (in VCardList vcards);
		oneway void notifySequenceComplete (in CallStatus status);
		oneway void notifyProgress         (in string message, in short percent);
	};
	
	interface BookView : Bonobo::Unknown {
		oneway void start ();
		oneway void stop ();

		oneway void dispose ();
	};

	interface Book : Bonobo::Unknown {

		/*
		 * Opening/creating addressbooks.
		 */
		oneway void open (in long opid, in boolean only_if_exists);

		/*
		 * Removing addressbooks.
		 */
		oneway void remove (in long opid);

		/*
		 * Fetching contacts in the addresbook.
		 */
		oneway void getContact (in long opid, in ContactId id);

		oneway void authenticateUser (in long opid,
					      in string user, in string passwd,
					      in string authMethod);

		/*
		 * Adding and deleting contacts in the book.
		 */
		oneway void addContact     (in long opid, in VCard vcard);
		oneway void removeContacts (in long opid, in ContactIdList Id);
	        
		/*
		 * Modifying contacts in the addressbook.
		 */
		oneway void modifyContact (in long opid, in VCard vcard);
		
		/*
		 * These two functions return a book view to the book
		 * listener.  This is for people who want a live view
		 * of the addressbook.
		 */
		oneway void getBookView (in long opid,
					 in BookViewListener listener, in string query,
					 in stringlist requested_fields, in long max_results);

		oneway void getChanges  (in long opid, in string change_id);

		oneway void getContactList (in long opid, in string query);

		oneway void getSupportedFields (in long opid);
		oneway void getRequiredFields (in long pid);

		/*
		 * This function returns a list of strings
		 * representing the auth methods (e.g. SASL mechs)
		 * that a backend/server supports.
		 *
		 * Some examples are:
		 *
		 * "ldap/simple-email|By email Address"
		 * "sasl/CRAM-MD5|CRAM-MD5(SASL)"
		 *
		 * The format should be:
		 *
		 * <class>/<type>|<i18nized string>
		 *
		 * "i18nized string" is shown in the UI, and should be
		 * a user friendly representation of the auth method.
		 *
		 * in the case of SASL auth mechs, the text trailing
		 * the '/' should be the proper name of the mechanism,
		 * as it will be passed unchanged to the backend auth
		 * function (eg. ldap_sasl_bind)
		 */
		oneway void getSupportedAuthMethods (in long opid);

		string getStaticCapabilities ();

		string getName ();
		/* cancels the currently running operation, whatever
		   it is. */
		CallStatus cancelOperation ();
	};

	interface BookListener : Bonobo::Unknown {
		
		oneway void notifyContactCreated       (in long opid, in CallStatus status, in ContactId Id);
		oneway void notifyContactsRemoved      (in long opid, in CallStatus status);
		oneway void notifyContactModified      (in long opid, in CallStatus status);
		oneway void notifyProgress             (in string status_message, in short precent);
		oneway void notifyBookOpened           (in long opid, in CallStatus status);
		oneway void notifyBookRemoved          (in long opid, in CallStatus status);
		oneway void notifyViewRequested        (in long opid, in CallStatus status, in BookView view);
		oneway void notifyChangesRequested     (in long opid, in CallStatus status, in BookChangeList changes);
		oneway void notifyContactRequested     (in long opid, in CallStatus status, in VCard vcard);
		oneway void notifyContactListRequested (in long opid, in CallStatus status, in stringlist contacts);
		oneway void notifySupportedFields      (in long opid, in CallStatus status, in stringlist fields);
		oneway void notifyRequiredFields       (in long opid, in CallStatus status, in stringlist fields);
		oneway void notifyAuthenticationResult (in long opid, in CallStatus status);
		oneway void notifySupportedAuthMethods (in long opid, in CallStatus status, in stringlist auth_methods);
		
		oneway void notifyWritable (in boolean writable);
		oneway void notifyConnectionStatus (in boolean is_online);
		oneway void notifyAuthRequired ();
	};

	interface BookFactory : Bonobo::Unknown {
		exception ProtocolNotSupported {};

		Book getBook (in string source, in BookListener listener)
			raises (ProtocolNotSupported);
	};
};
};
};