path: root/calendar/idl/evolution-calendar.idl

/* Evolution calendar interface
 *
 * Copyright (C) 2000 Eskil Heyn Olsen
 * Copyright (C) 2000 Ximian, Inc.
 * Copyright (C) 2000 Ximian, Inc.
 *
 * Authors: Eskil Heyn Olsen <deity@eskil.dk>
 *          Federico Mena-Quintero <federico@ximian.com>
 */

#ifndef _EVOLUTION_CALENDAR_IDL_
#define _EVOLUTION_CALENDAR_IDL_

#include <Bonobo.idl>

module GNOME {
module Evolution {

module Calendar {
    /* A calendar component (event/todo/journal/etc), represented as an
     * iCalendar string.
     */
    typedef string CalObj;
    typedef sequence<CalObj> CalObjSeq;

    typedef sequence<string> stringlist;

    /* A unique identifier for a calendar component */
    typedef string CalObjUID;

    /* A unique identified for an event recurrence */
    typedef string CalRecurID;

    /* Simple sequence of strings */
    typedef sequence<string> StringSeq;

    /* Sequence of unique identifiers */
    typedef sequence<CalObjUID> CalObjUIDSeq;

    /* A VTIMEZONE component, represented as an iCalendar string. */
    typedef string CalTimezoneObj;

    /* A unique identifier for a VTIMEZONE component, i.e. its TZID. */
    typedef string CalTimezoneObjUID;

    /* A unique identifier for an alarm subcomponent */
    typedef string CalAlarmUID;

    /* Flags for getting UID sequences */
    typedef long CalObjType;
    const CalObjType TYPE_EVENT   = 1 << 0;
    const CalObjType TYPE_TODO    = 1 << 1;
    const CalObjType TYPE_JOURNAL = 1 << 2;
    const CalObjType TYPE_ANY     = 0x07;

    /* Flags for getting UID sequences */
    typedef long CalObjModType;
    const CalObjModType MOD_THIS          = 1 << 0;
    const CalObjModType MOD_THISANDPRIOR  = 1 << 1;
    const CalObjModType MOD_THISANDFUTURE = 1 << 2;
    const CalObjModType MOD_ALL           = 0x07;

    /* Flags for getting URI sequences */
    typedef long CalMode;
    const CalMode MODE_LOCAL   = 1 << 0;
    const CalMode MODE_REMOTE  = 1 << 1;
    const CalMode MODE_ANY     = 0x07;

    /* Types of object changes made */
    typedef long CalObjChangeType;
    const CalObjChangeType ADDED = 1 << 0;
    const CalObjChangeType MODIFIED = 1 << 1;
    const CalObjChangeType DELETED = 1 << 2;

    /* Used to store a time_t */
    typedef unsigned long Time_t;
    
    /* An instance of a calendar component that actually occurs.  These are
     * "virtual" objects in that they are used to represent instances of
     * recurring events and alarms.  "Real" objects just contain the
     * information required to figure out the times at which they recur or
     * trigger.  
     */
    struct CalObjInstance {
        CalObjUID uid;
        Time_t start;
        Time_t end;
    };

    /* Used to transfer a list of component occurrences */
    typedef sequence<CalObjInstance> CalObjInstanceSeq;

    /* An object change */
    struct CalObjChange {
        CalObj calobj;
        CalObjChangeType type;
    };

    /* Used to transfer a list of changed components */
    typedef sequence<CalObjChange> CalObjChangeSeq;

    /* Used to represent users and lists of users */
    typedef string User;
    typedef sequence<User> UserList;

    enum CallStatus {
        Success,
        RepositoryOffline,
        PermissionDenied,
        InvalidRange,
        ObjectNotFound,
        InvalidObject,
        CardIdAlreadyExists,
        AuthenticationFailed,
        AuthenticationRequired,
        UnsupportedField,
        UnsupportedMethod,
        UnsupportedAuthenticationMethod,
        TLSNotAvailable,
        NoSuchCal,

        /* These can be returned for successful searches, but
           indicate the result set was truncated */
        SearchSizeLimitExceeded,
        SearchTimeLimitExceeded,

        InvalidQuery,
        QueryRefused,

        CouldNotCancel,
        
        OtherError
    };

    interface Query;

    interface Listener;

    interface QueryListener;

    /* Calendar client interface */
    interface Cal : Bonobo::Unknown {
        exception NotFound {};
        exception InvalidRange {};
        
        /* A calendar is identified by its URI */
        readonly attribute string uri;

        oneway void open (in boolean only_if_exists);
        oneway void remove ();

        /* Check write permissions for calendar */
        oneway void isReadOnly ();
        
        /* Information on the backend's capabilities */
        oneway void getStaticCapabilities ();

        /* Return the cal address associated with this calendar, if any. */
        oneway void getCalAddress ();       

        oneway void getAlarmEmailAddress ();

        /* Returns the LDAP attribute to get attendees from */
        oneway void getLdapAttribute ();

        /* For going online/offline */
        void setMode (in CalMode mode);

        /* Get a default object of a given type */
        oneway void getDefaultObject (in CalObjType type);
        
        /* Gets a component based on its URI */
        oneway void getObject (in CalObjUID uid, in CalRecurID rid);

        oneway void getObjectList (in string query);        

        /* Methods for manipulating timezones */
        oneway void getTimezone (in CalTimezoneObjUID tzid);
        oneway void addTimezone (in CalTimezoneObj tz);
        /* The timezone used to resolve DATE and floating DATE-TIME values. */
        oneway void setDefaultTimezone (in CalTimezoneObjUID tzid);

        /* Gets a list of components that changed based on object type */
        oneway void getChanges (in CalObjType type, in string change_id);

        /* Returns free/busy objects for the given interval */
        oneway void getFreeBusy (in UserList users, in Time_t start, in Time_t end);

        /* Discards an alarm from a given component */
        oneway void discardAlarm (in CalObjUID uid, in CalAlarmUID auid);

        /* Methods for manipulating iCalendar objects */
        oneway void createObject (in CalObj calobj);
        oneway void modifyObject (in CalObj calobj, in CalObjModType mod);
        oneway void removeObject (in CalObjUID uid, in CalObjModType mod);

        /* Methods for getting/sending iCalendar VCALENDARS via iTip/iMip */
        oneway void receiveObjects (in CalObj calobj);
        oneway void sendObjects (in CalObj calobj);

        /* Query methods */
        oneway void getQuery (in string sexp, in QueryListener ql);
    };

    /* Listener for changes in a calendar */
    interface Listener : Bonobo::Unknown {
        /* Return status when setting calendar mode */
        enum SetModeStatus {
            MODE_SET,                    /* All OK */
            MODE_NOT_SET,                /* Generic error */
            MODE_NOT_SUPPORTED           /* Mode not supported */
        };

        oneway void notifyReadOnly (in CallStatus status, in boolean read_only);
        oneway void notifyCalAddress (in CallStatus status, in string address);
        oneway void notifyAlarmEmailAddress (in CallStatus status, in string address);
        oneway void notifyLDAPAttribute (in CallStatus status, in string ldap_attribute);
        oneway void notifyStaticCapabilities (in CallStatus status, in string capabilities);
        
        oneway void notifyCalOpened (in CallStatus status);
        oneway void notifyCalRemoved (in CallStatus status);

        oneway void notifyObjectCreated (in CallStatus status, in string uid);
        oneway void notifyObjectModified (in CallStatus status);
        oneway void notifyObjectRemoved (in CallStatus status);

        oneway void notifyAlarmDiscarded (in CallStatus status);
    
        oneway void notifyObjectsReceived (in CallStatus status);
        oneway void notifyObjectsSent (in CallStatus status);
        
        oneway void notifyDefaultObjectRequested (in CallStatus status, in CalObj object);
        oneway void notifyObjectRequested (in CallStatus status, in CalObj object);
        oneway void notifyObjectListRequested (in CallStatus status, in stringlist objects);
        oneway void notifyQuery (in CallStatus status, in Query query);

        oneway void notifyTimezoneRequested (in CallStatus status, in CalTimezoneObj tz);
        oneway void notifyTimezoneAdded (in CallStatus status, in CalTimezoneObjUID tzid);
        oneway void notifyDefaultTimezoneSet (in CallStatus status);

        oneway void notifyChanges (in CallStatus status, in CalObjChangeSeq changes);
        oneway void notifyFreeBusy (in CallStatus status, in CalObjSeq freebusy);

                /* Called from a Calendar when the mode is changed */
        oneway void notifyCalSetMode (in SetModeStatus status, in CalMode mode);        

        /* Called from a Calendar when the list of categories changes */
        oneway void notifyCategoriesChanged (in StringSeq categories);

        /* Called from a Calendar when there is an error not notified otherwise */
        oneway void notifyErrorOccurred (in string message);
    };

    /* Handle to a live query on a calendar */
    interface Query : Bonobo::Unknown {
        oneway void start ();
    };

    /* Listener for changes in a query of a calendar */
    interface QueryListener : Bonobo::Unknown {
        oneway void notifyObjectsAdded (in stringlist objects);     
        oneway void notifyObjectsModified (in stringlist objects);      
        oneway void notifyObjectsRemoved (in CalObjUIDSeq uids);
        oneway void notifyQueryProgress (in string message, in short percent);
        oneway void notifyQueryDone (in CallStatus status);
    };

    /* A calendar factory, can load and create calendars */
    interface CalFactory : Bonobo::Unknown {
        exception NilListener {};
        exception InvalidURI {};
        exception UnsupportedMethod {};

        Cal getCal (in string uri, in CalObjType type, in Listener listener)
            raises (NilListener, InvalidURI, UnsupportedMethod);
    };

    /* Interface to the alarm notification service */
    interface AlarmNotify : Bonobo::Unknown {
        exception InvalidURI {};
        exception BackendContactError {};
        exception NotFound {};

        /* Adds a calendar to the alarm notification system so that
         * alarms will be triggered for it.  The calendar will be loaded
         * automatically whenever the alarm daemon starts up.  
         */
        void addCalendar (in string uri)
            raises (InvalidURI, BackendContactError);

        /* Removes a calendar from the alarm notification system and
         * alarms will no longer be triggered for it.  The calendar will
         * no longer be loaded when the alarm daemon starts up. 
         */
        void removeCalendar (in string uri)
            raises (InvalidURI, NotFound);
    };

    /* Factory to centralize calendar component editor dialogs */
    interface CompEditorFactory : Bonobo::Unknown {
        exception InvalidURI {};
        exception BackendContactError {};
        exception UnsupportedType {};

        typedef long CompEditorMode;
        const CompEditorMode EDITOR_MODE_EVENT        = 1 << 0;
        const CompEditorMode EDITOR_MODE_ALLDAY_EVENT = 1 << 1;
        const CompEditorMode EDITOR_MODE_MEETING      = 1 << 2;
        const CompEditorMode EDITOR_MODE_TODO         = 1 << 3;

        /* Loads a calendar and opens an editor for the specified object */
        void editExisting (in string uri, in CalObjUID uid)
            raises (InvalidURI, BackendContactError);

        /* Loads a calendar and creates a new component of the specified type */
        void editNew (in string uri, in CompEditorMode mode)
            raises (InvalidURI, BackendContactError, UnsupportedType);
    };
};

};
};

#endif