aboutsummaryrefslogtreecommitdiffstats
path: root/calendar/idl/evolution-calendar.idl
blob: 89926386e2152c2029130422a83439a0b71e3f64 (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
/* 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 ADDED = 1 << 0;
    const CalObjChangeType MODIFIED = 1 << 0;
    const CalObjChangeType DELETED = 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 {
        CalObj calobj;
        CalObjChangeType type;
    };

    typedef sequence<CalObjChange> CalObjChangeSeq;

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

    typedef sequence<CalAlarmInstance> CalAlarmInstanceSeq;

    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 objects that changed based on object type */
        CalObjChangeSeq getChanges (in CalObjType type, in string change_id);

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