/* -*- Mode: C; tab-width: 8; indent-tabs-mode: t; c-basic-offset: 8 -*- */
/*
 *
 * Author:
 *   Nat Friedman (nat@helixcode.com)
 *
 * Copyright 2000, Helix Code, 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 {
		void notifyCardAdded        (in VCardList cards);
		void notifyCardRemoved      (in CardId id);
		void notifyCardChanged      (in VCardList cards);
		void notifySequenceComplete ();
		void notifyStatusMessage    (in string message);
	};
	
	interface BookView : Bonobo::Unknown {
	};

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

		/*
		 * Permissions.  the first form is general write
		 * permission (whether or not the user can add or
		 * remove or modify any entry in the addressbook.)
		 *
		 * if can_write returns TRUE, can_write_card can still
		 * return FALSE if the user doesn't have permission to
		 * modify/remove that specific card.
		 */
		boolean isWriteable     ();
		boolean isCardWriteable (in CardId Id);

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

		/*
		 * 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.  The syntax for the query
		 * string is not yet defined.
		 */
		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);

		void checkConnection ();

		void getSupportedFields ();

		string getStaticCapabilities ();

		string getName ();
	};

	interface BookListener : Bonobo::Unknown {

		enum CallStatus {
			Success,
			RepositoryOffline,
			PermissionDenied,
			CardNotFound,
			ProtocolNotSupported,
			AuthenticationFailed,
			AuthenticationRequired,
			UnsupportedField,
			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 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);

		/**
		 * 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);
	};

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

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