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 object (event/todo/journal/etc), represented as an
     * iCalendar string.
     */
    typedef string CalObj;

    /* An unique identifier for a calendar object */
    typedef string CalObjUID;

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

    /* 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 UPDATED = 1 << 0;
    const CalObjChangeType REMOVED = 1 << 1;
    
    /* 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 object 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;
    };

    typedef sequence<CalObjInstance> CalObjInstanceSeq;

    /* An object change */
    struct CalObjChange {
        CalObjUID uid;
        CalObjChangeType type;
    };

    /* An alarm trigger instance */
    struct CalAlarmInstance {
        CalObjUID uid;
        AlarmType type;
        Time_t trigger;
        Time_t occur;
    };

    typedef sequence<CalAlarmInstance> CalAlarmInstanceSeq;

    typedef sequence<CalObjChange> CalObjChangeSeq;

    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 objects of the specified types */
        long countObjects (in CalObjType type);

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

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

        /* Gets a list of UIds that changed based on object type */
        CalObjChangeSeq getChangedUIds (in CalObjType type, in Time_t since);

        /* Gets a list of objects 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 the objects whose alarms trigger in the specified time
         * range.
         */
        CalAlarmInstanceSeq getAlarmsInRange (in Time_t start, in Time_t end)
            raises (InvalidRange);

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


        /*
         * Updates an object 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 an object */
        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 an object is added or changed */
        void notifyObjUpdated (in CalObjUID uid);

        /* Called from a Calendar when an object 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