aboutsummaryrefslogtreecommitdiffstats
path: root/calendar/idl/evolution-calendar.idl
blob: e21f77fe2ec83c8793dd20a618fa3932c410244e (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
/* Evolution calendar interface
 *
 * Copyright (C) 2000 Eskil Heyn Olsen
 * Copyright (C) 2000 Helix Code, 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;

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

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

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

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

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

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

    /* Interface to the alarm notification service */
    interface AlarmNotify : Bonobo::Unknown {
        exception InvalidURI {};
        exception BackendContactError {};
        exception NotFound {};

        /* Adds a calendar to the alarm notification system */
        void addCalendar (in string uri)
            raises (InvalidURI, BackendContactError);

        /* Removes a calendar from the alarm notification system */
        void removeCalendar (in string uri)
            raises (InvalidURI, NotFound);

        /* Makes the alarm notification daemon unconditionally exit */
        void die ();
    };
};

};
};

#endif