path: root/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);
    };
};