/* -*- 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 CardId;
	typedef string VCard;
	typedef sequence<VCard> VCardList;
	typedef sequence<string> stringlist;

	interface CardCursor : Bonobo::Unknown {
		long   count  ();
		string getNth (in long n);
	};

	/* 
	 * A book view is a live view of a book.  It's either a view
	 * of all the cards in the book or a view of a query.  When
	 * created, it will get a series of signal_card_added 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 cards.)
	 */
	interface BookViewListener : Bonobo::Unknown {
		enum CallStatus {
			Success,
			/* These are still successful searches, but
			   the result set was truncated */
			SearchSizeLimitExceeded,
			SearchTimeLimitExceeded,

			/* These are failures */
			InvalidQuery,
			QueryRefused,
			OtherError
		};
		void notifyCardAdded        (in VCardList cards);
		void notifyCardRemoved      (in CardId id);
		void notifyCardChanged      (in VCardList cards);
		void notifySequenceComplete (in CallStatus status);
		void notifyStatusMessage    (in string message);
	};
	
	interface BookView : Bonobo::Unknown {
	};

	interface Book : Bonobo::Unknown {
		/*
		 * Fetching cards in the addresbook.
		 */
		void getVCard (in CardId id);

		void authenticateUser (in string user, in string passwd,
				       in string authMethod);

		/*
		 * Adding and deleting cards in the book.
		 */
		void addCard    (in VCard vcard);
		void removeCard (in CardId Id);
	        
		/*
		 * Modifying cards in the addressbook.
		 */
		void modifyCard (in VCard vcard);
		
		/*
		 * This function returns a cursor to the book
		 * listener.  This is for people who want a snapshot
		 * of the addressbook.
		 */
		void getCursor (in string query);
		
		/*
		 * These two functions return a book view to the book
		 * listener.  This is for people who want a live view
		 * of the addressbook.
		 */
		void getBookView (in BookViewListener listener, in string query);

		void getChanges  (in BookViewListener listener, in string change_id);

		/*
		 * This function returns a book view that is identical
		 * to a normal book view, except in one way - The only
		 * values reflected in the cards that are transfered
		 * back are: File As, family name, given name, email
		 * addresses, and nickname.  It is intended for use in
		 * completion searches.
		 */
		void getCompletionView (in BookViewListener listener, in string query);

		void checkConnection ();

		void getSupportedFields ();

		/*
		 * 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)
		 */
		void getSupportedAuthMethods ();

		string getStaticCapabilities ();

		string getName ();
	};

	interface BookListener : Bonobo::Unknown {

		enum CallStatus {
			Success,
			RepositoryOffline,
			PermissionDenied,
			CardNotFound,
			CardIdAlreadyExists,
			ProtocolNotSupported,
			AuthenticationFailed,
			AuthenticationRequired,
			UnsupportedField,
			UnsupportedAuthenticationMethod,
			TLSNotAvailable,
			NoSuchBook,

			OtherError
		};

		void notifyCardCreated  (in CallStatus status, in CardId Id);

		void notifyCardRemoved  (in CallStatus status);

		void notifyCardModified (in CallStatus status);
		
		void notifyOpenBookProgress (in string status_message, in short percent);

		void notifyBookOpened       (in CallStatus status, in Book book);

		void notifyCardRequested    (in CallStatus status, in VCard card);

		void notifyCursorRequested  (in CallStatus status, in CardCursor cursor);

		void notifyViewRequested    (in CallStatus status, in BookView view);

		void notifyChangesRequested (in CallStatus status, in BookView view);

		void notifyAuthenticationResult (in CallStatus status);

		void notifySupportedFields (in CallStatus status, in stringlist fields);

		void notifySupportedAuthMethods (in CallStatus status, in stringlist fields);

		/**
		 * notifyConnectionStatus:
		 *
		 * Used to report changes in the connection to the
		 * contact repository.  This is often a response to a
		 * call to check_connection() on the Book, but wombat
		 * is free to report the connection status without
		 * being asked.
		 */
		void notifyConnectionStatus (in boolean connected);

		/**
		 * notifyWritable:
		 *
		 * Used to report whether or not a backend can write
		 * to a given addressbook.  All books default to
		 * read-only, so unless you receive a notification
		 * saying otherwise, treat the book as read-only.  It
		 * is presumed that this notification will be sent
		 * early (just after a connection is opened, usually),
		 * but it may also be sent later, if/when the backend
		 * notices a change.
		 */
		void notifyWritable (in boolean writable);
	};

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

		void openBook (in string uri, in BookListener listener)
			raises (ProtocolNotSupported);
	};
};
};
};