evolution/addressbook/backend/idl/addressbook.idl

/* -*- 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 Evolution {

	typedef string CardId;
	typedef string VCard;
	typedef sequence<VCard> VCardList;

	interface CardCursor : Bonobo::Unknown {
		long   get_length ();
		string get_nth    (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 signal_card_added (in VCardList cards);
		void signal_card_removed (in CardId id);
		void signal_card_changed (in VCardList cards);
		void signal_sequence_complete ();
	};
	
	interface BookView : Bonobo::Unknown {
	};

	interface Book : Bonobo::Unknown {
		/*
		 * Fetching cards in the addresbook.
		 */
		VCard get_vcard (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 can_write ();
		boolean can_write_card (in CardId Id);

		/*
		 * Adding and deleting cards in the book.
		 */
		void create_card (in VCard vcard);
		void remove_card (in CardId Id);
	        
		/*
		 * Modifying cards in the addressbook.
		 */
		void modify_card (in VCard vcard);
		
		/*
		 * These two functions return 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 get_cursor (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 get_book_view(in BookViewListener listener, in string query);

		void check_connection ();

		string get_name ();
	};

	interface BookListener : Bonobo::Unknown {

		enum CallStatus {
			Success,
			RepositoryOffline,
			PermissionDenied,
			CardNotFound,
			ProtocolNotSupported,
			OtherError
		};

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

		void respond_remove_card (in CallStatus status);

		void respond_modify_card (in CallStatus status);
		
		void report_open_book_progress (in string status_message, in short percent);

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

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

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

		/**
		 * report_connection_status:
		 *
		 * 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 report_connection_status (in boolean connected);
	};

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

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