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;
    
    /* Types of alarms */
    enum AlarmType {
        MAIL,
        PROGRAM,
        DISPLAY,
        AUDIO
    };

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

    /* An alarm trigger instance */
    struct CalAlarmInstance {
        CalAlarmUID auid;
        Time_t trigger;
        Time_t occur_start;
        Time_t occur_end;
    };

    /* Used to represent a list of alarm triggers for a single component */
    typedef sequence<CalAlarmInstance> CalAlarmInstanceSeq;

    /* Alarms for a component */
    struct CalComponentAlarms {
        CalObj calobj;
        CalAlarmInstanceSeq alarms;
    };

    /* Used to represent a list of components plus their triggers */
    typedef sequence<CalComponentAlarms> CalComponentAlarmsSeq;

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

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

        /* 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 {};
        exception InvalidObject {};
        exception InvalidURI {};
        exception CouldNotCreate {};
        exception PermissionDenied {};
        exception Busy {string errorMsg;};
        
        /* A calendar is identified by its URI */
        readonly attribute string uri;

        oneway void open (in boolean only_if_exists)
            raises (InvalidURI, PermissionDenied);

        oneway void remove ()
            raises (InvalidURI, PermissionDenied);

        /* 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 ()
            raises (NotFound);

        oneway void getAlarmEmailAddress ()
            raises (NotFound);

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

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

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

        oneway void getObjectList (in string query);
        
        /* Sets the default timezone to be used for resolving DATE
           and floating DATE-TIME values. */
        void setDefaultTimezone (in CalTimezoneObjUID tzid)
            raises (NotFound);

        /* Gets a VTIMEZONE component based on its TZID */
        CalTimezoneObj getTimezoneObject (in CalTimezoneObjUID tzid)
            raises (NotFound);

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


        /* Gets a list of the components that have alarms that trigger
         * in the specified range of time, and the trigger/occurrence
         * structures themselves.  
         */
        CalComponentAlarmsSeq getAlarmsInRange (in Time_t start, in Time_t end)
            raises (NotFound, InvalidRange);

        /* Returns free/busy objects for the given interval */
        CalObjSeq getFreeBusy (in UserList users, in Time_t start, in Time_t end)
            raises (NotFound, InvalidRange);

        /* Gets the alarms for the specified component that trigger in
         * the specified time range.  
         */
        CalComponentAlarms getAlarmsForObject (in CalObjUID uid,
                               in Time_t start, in Time_t end)
            raises (NotFound, InvalidRange);


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

        /* Adds or updates one or more VEVENT/VTODO/VTIMEZONE
         * components. The calobj should be a string representation of
         * a complete VCALENDAR object (we also support single
         * VEVENT/VTODO strings, but that is deprecated).
         *
         * The VTIMEZONE data will be merged into the calendar,
         * possibly by renaming TZIDs (though not for builtin
         * VTIMEZONEs, which have unique TZIDs), so don't rely on the
         * TZIDs being the same in the new object on the server.
         *
         * The client should probably immediately free its copy of the
         * object after this call, and call getObject to get the
         * updated version.
         */
        void updateObjects (in CalObj calobj, in CalObjModType mod)
            raises (NotFound, InvalidObject, PermissionDenied);

        /* Removes a component */
        oneway void createObject (in CalObj calobj);
        oneway void modifyObject (in CalObj calobj, in CalObjModType mod);
        oneway void removeObject (in CalObjUID uid, in CalObjModType mod);

        /* Sends a component */
        CalObj sendObject (in CalObj calobj, out UserList users)
            raises (InvalidObject, PermissionDenied, Busy);

        oneway void getQuery (in string sexp, in QueryListener ql)
            raises (CouldNotCreate);
    };

    /* 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 notifyObjectListRequested (in CallStatus status, in stringlist objects);
        oneway void notifyQuery (in CallStatus status, in Query query);

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