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 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);

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