aboutsummaryrefslogtreecommitdiffstats
path: root/calendar/idl/evolution-calendar.idl
blob: 3e64e07888ae017c1832a6ebfcf570ca5e7f6fda (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
/* 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