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

/* Evolution calendar interface
 *
 * Copyright (C) 2000 Eskil Heyn Olsen
 * Copyright (C) 2000 Helix Code, Inc.
 *
 * Authors: Eskil Heyn Olsen <deity@eskil.dk>
 *          Federico Mena-Quintero <federico@helixcode.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;

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

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

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

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

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

    interface Listener;

    /* Calendar client interface */
    interface Cal : Bonobo::Unknown {
        exception NotFound {};
        exception InvalidRange {};
        exception InvalidObject {};

        /* A calendar is identified by its URI */
        readonly attribute string uri;

        /* Gets the number of components of the specified types */
        long countObjects (in CalObjType type);

        /* Gets a component based on its URI */
        CalObj getObject (in CalObjUID uid)
            raises (NotFound);

        /* Gets a list of UIDs based on component type */
        CalObjUIDSeq getUIds (in CalObjType type);

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

        /* Gets a list of components that occur or recur in the specified time range */
        CalObjUIDSeq getObjectsInRange (in CalObjType type, 
                        in Time_t start, in Time_t end)
            raises (InvalidRange);

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


        /* Updates a component by adding it if it does not exist or by
         * changing an existing one.  
         */
        void updateObject (in CalObjUID uid, in CalObj calobj)
            raises (InvalidObject);

        /* Removes a component */
        void removeObject (in CalObjUID uid)
            raises (NotFound);
    };

    /* Listener for changes in a calendar */
    interface Listener : Bonobo::Unknown {
        /* Return status when loading a calendar; we need better error reporting */
        enum LoadStatus {
            SUCCESS,        /* All OK */
            ERROR,          /* Generic error */
            IN_USE,         /* Requested create while a calendar
                         * with the same URI was in use.
                         */
            METHOD_NOT_SUPPORTED    /* A method handler is not registered */
        };

        /* Called from a CalFactory when a calendar is initially loaded
         * or created.  The listener must remember the cal object.
         */
        void notifyCalLoaded (in LoadStatus status, in Cal cal);

        /* Called from a Calendar when a component is added or changed */
        void notifyObjUpdated (in CalObjUID uid);

        /* Called from a Calendar when a component is removed */
        void notifyObjRemoved (in CalObjUID uid);
    };

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

        /* Load a calendar from an URI */
        void load (in string uri, in Listener listener)
            raises (NilListener);

        /* Create a new calendar at the specified URI */
        void create (in string uri, in Listener listener)
            raises (NilListener);
    };
};

};
};

#endif