aboutsummaryrefslogtreecommitdiffstats
path: root/calendar/idl/evolution-calendar.idl
blob: f38bc9b47aa30aa3dd5ded74fb4b4d8835587d87 (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
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
/* 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;

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

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

    interface Query;

    interface Listener;

    interface QueryListener;

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

        /* For going online/offline */
        void setMode (in CalMode mode);
        
        /* 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);

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

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


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

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

        /* Initiates a live query of the calendar.  Returns a handle
         * to the live query itself; changes to components that are
         * present in the query are notified to the listener.
         */
        Query getQuery (in string sexp, in QueryListener ql)
            raises (CouldNotCreate);
    };

    /* Listener for changes in a calendar */
    interface Listener : Bonobo::Unknown {
        /* Return status when opening a calendar */
        enum OpenStatus {
            SUCCESS,        /* All OK */
            ERROR,          /* Generic error */
            NOT_FOUND,      /* Requested opening in only_if_exists mode
                         * when the URI did not exist.
                         */
            METHOD_NOT_SUPPORTED    /* A method handler is not registered */
        };

        /* Return status when setting calendar mode */
        enum SetModeStatus {
            MODE_SET,                    /* All OK */
            MODE_NOT_SET,                /* Generic error */
            MODE_NOT_SUPPORTED           /* Mode not supported */
        };

        /* Called from a CalFactory when a calendar is initially opened.
         * The listener must remember the cal object.  
         */
        void notifyCalOpened (in OpenStatus status, in Cal cal);

                /* Called from a Calendar when the mode is changed */
        void notifyCalSetMode (in SetModeStatus status, in CalMode mode);
        
        /* 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);

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

    /* Handle to a live query on a calendar */
    interface Query : Bonobo::Unknown {
    };

    /* Listener for changes in a query of a calendar */
    interface QueryListener : Bonobo::Unknown {
        /* Called when a component is added or changed.  If
         * query_in_progress is true, then the initial query results are
         * being populated and the other arguments indicate the
         * percentage of completion Otherwise, the percent value is
         * unspecified.  */
        void notifyObjUpdated (in CalObjUID uid, 
                       in boolean query_in_progress, 
                       in long n_scanned,
                       in long total);

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

        /* Reported when a query ends */
        enum QueryDoneStatus {
            SUCCESS,
            PARSE_ERROR
        };

        /* Called when the query finishes populating itself some time
         * after it is created.  Before this is called,
         * notifyObjUpdated() may have been called several times to
         * indicate which objects are actually in the query, unless the
         * status result is a parse error.  
         */
        void notifyQueryDone (in QueryDoneStatus status, in string error_str);

        /* Called when an evaluation error occurs while performing a query */
        void notifyEvalError (in string error_str);
    };

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

        /* Open a calendar from an URI */
        void open (in string uri, in boolean only_if_exists, in Listener listener)
            raises (NilListener, InvalidURI, UnsupportedMethod);

        /* List of open URI's */
        StringSeq uriList (in CalMode mode);
    };

    /* 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_MEETING      = 1 << 1;
        const CompEditorMode EDITOR_MODE_TODO         = 1 << 2;

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