Fix handling of notification calls w/ the dialing api
[asterisk/asterisk.git] / include / asterisk / calendar.h
1 /*
2  * Asterisk -- An open source telephony toolkit.
3  *
4  * Copyright (C) 2008 - 2009, Digium, Inc.
5  *
6  * Terry Wilson <twilson@digium.com>
7  *
8  * See http://www.asterisk.org for more information about
9  * the Asterisk project. Please do not directly contact
10  * any of the maintainers of this project for assistance;
11  * the project provides a web site, mailing lists and IRC
12  * channels for your use.
13  *
14  * This program is free software, distributed under the terms of
15  * the GNU General Public License Version 2. See the LICENSE file
16  * at the top of the source tree.
17  */
18
19 #ifndef _ASTERISK_CALENDAR_H
20 #define _ASTERISK_CALENDAR_H
21
22 #include "asterisk.h"
23 #include "asterisk/stringfields.h"
24 #include "asterisk/config.h"
25 #include "asterisk/linkedlists.h"
26 #include "asterisk/lock.h"
27 #include "asterisk/dial.h"
28
29 /*! \file calendar.h
30  * \brief A general API for managing calendar events with Asterisk
31  *
32  * \author Terry Wilson <twilson@digium.com>
33  *
34  * \note This API implements an abstraction for handling different calendaring
35  * technologies in Asterisk. The services provided by the API are a dialplan
36  * function to query whether or not a calendar is busy at the present time, a
37  * adialplan function to query specific information about events in a time range,
38  * a devicestate provider, and notification of calendar events through execution
39  * of dialplan apps or dialplan logic at a specific context and extension.  The
40  * information available through the CALENDAR_EVENT() dialplan function are:
41  *
42  *   SUMMARY, DESCRIPTION, ORGANIZER, LOCATION
43  *   CALENDAR, UID, START, END, and BUSYSTATE
44  *
45  * BUSYSTATE can have the values 0 (free), 1 (tentatively busy), or 2 (busy)
46  *
47  * Usage
48  * All calendaring configuration data is located in calendar.conf and is only read
49  * directly by the Calendaring API. Each calendar technology resource must register
50  * a load_calendar callback which will be passed an ast_calendar_load_data structure.
51  * The load_calendar callback function should then set the values it needs from this
52  * cfg, load the calendar data, and then loop updating the calendar data and events
53  * baesd on the refresh interval in the ast_calendar object.  Each call to
54  * the load_calendar callback will be will run in its own thread.
55  *
56  * Updating events involves creating an astobj2 container of new events and passing
57  * it to the API through ast_calendar_merge_events.
58  *
59  * Calendar technology resource modules must also register an unref_calendar callback
60  * which will only be called when the resource module calls ast_calendar_unregister()
61  * to unregister that module's calendar type (usually done in module_unload())
62  */
63
64 struct ast_calendar;
65 struct ast_calendar_event;
66
67 /*! \brief Individual calendaring technology data */
68 struct ast_calendar_tech {
69         const char *type;
70         const char *description;
71         const char *module;
72         int (* is_busy)(struct ast_calendar *calendar); /*!< Override default busy determination */
73         void *(* load_calendar)(void *data);   /*!< Create private structure, add calendar events, etc. */
74         void *(* unref_calendar)(void *obj);   /*!< Function to be called to free the private structure */
75         int (* write_event)(struct ast_calendar_event *event);  /*!< Function for writing an event to the calendar */
76         AST_LIST_ENTRY(ast_calendar_tech) list;
77 };
78
79 enum ast_calendar_busy_state {
80         AST_CALENDAR_BS_FREE = 0,
81         AST_CALENDAR_BS_BUSY_TENTATIVE,
82         AST_CALENDAR_BS_BUSY,
83 };
84
85 struct ast_calendar_attendee {
86         char *data;
87         AST_LIST_ENTRY(ast_calendar_attendee) next;
88 };
89
90 /* \brief Calendar events */
91 struct ast_calendar_event {
92         AST_DECLARE_STRING_FIELDS(
93                 AST_STRING_FIELD(summary);
94                 AST_STRING_FIELD(description);
95                 AST_STRING_FIELD(organizer);
96                 AST_STRING_FIELD(location);
97                 AST_STRING_FIELD(uid);
98         );
99         struct ast_calendar *owner;   /*!< The calendar that owns this event */
100         time_t start;        /*!< Start of event (UTC) */
101         time_t end;          /*!< End of event (UTC) */
102         time_t alarm;        /*!< Time for event notification */
103         enum ast_calendar_busy_state busy_state;  /*!< The busy status of the event */
104         int notify_sched;    /*!< The sched for event notification */
105         int bs_start_sched;  /*!< The sched for changing the device state at the start of an event */
106         int bs_end_sched;    /*!< The sched for changing the device state at the end of an event */
107         struct ast_dial *dial;
108         struct ast_channel *notify_chan;
109         AST_LIST_HEAD_NOLOCK(attendees, ast_calendar_attendee) attendees;
110 };
111
112 /*! \brief Asterisk calendar structure */
113 struct ast_calendar {
114         const struct ast_calendar_tech *tech;
115         void *tech_pvt;
116         AST_DECLARE_STRING_FIELDS(
117                 AST_STRING_FIELD(name);                         /*!< Name from config file [name] */
118                 AST_STRING_FIELD(notify_channel);       /*!< Channel to use for notification */
119                 AST_STRING_FIELD(notify_context);       /*!< Optional context to execute from for notification */
120                 AST_STRING_FIELD(notify_extension);     /*!< Optional extension to execute from for notification */
121                 AST_STRING_FIELD(notify_app);           /*!< Optional dialplan app to execute for notification */
122                 AST_STRING_FIELD(notify_appdata);       /*!< Optional arguments for dialplan app */
123         );
124         int autoreminder;    /*!< If set, override any calendar_tech specific notification times and use this time (in mins) */
125         int notify_waittime; /*!< Maxiumum time to allow for a notification attempt */
126         int refresh;         /*!< When to refresh the calendar events */
127         int timeframe;       /*!< Span (in mins) of calendar data to pull with each request */
128         pthread_t thread;    /*!< The thread that the calendar is loaded/updated in */
129         ast_cond_t unload;
130         int unloading:1;
131         int pending_deletion:1;
132         struct ao2_container *events;  /*!< The events that are known at this time */
133 };
134
135 /*! \brief Register a new calendar technology
136  *
137  * \param tech calendar technology to register
138  *
139  * \retval 0 success
140  * \retval -1 failure
141  */
142 int ast_calendar_register(struct ast_calendar_tech *tech);
143
144 /*! \brief Unregister a new calendar technology
145  *
146  * \param tech calendar technology to unregister
147  *
148  * \retval 0 success
149  * \retva -1 failure
150  */
151 void ast_calendar_unregister(struct ast_calendar_tech *tech);
152
153 /*! \brief Allocate an astobj2 ast_calendar_event object
154  *
155  * \param cal calendar to allocate an event for
156  *
157  * \return a new, initialized calendar event
158  */
159 struct ast_calendar_event *ast_calendar_event_alloc(struct ast_calendar *cal);
160
161 /*! \brief Allocate an astobj2 container for ast_calendar_event objects
162  *
163  * \return a new event container
164  */
165 struct ao2_container *ast_calendar_event_container_alloc(void);
166
167 /*! \brief Add an event to the list of events for a calendar
168  *
169  * \param cal calendar containing the events to be merged
170  * \param new_events an oa2 container of events to be merged into cal->events
171  */
172 void ast_calendar_merge_events(struct ast_calendar *cal, struct ao2_container *new_events);
173
174 /*! \brief Unreference an ast_calendar_event 
175  *
176  * \param event event to unref
177  *
178  * \return NULL
179  */
180 struct ast_calendar_event *ast_calendar_unref_event(struct ast_calendar_event *event);
181
182 /*! \brief Remove all events from calendar 
183  *
184  * \param cal calendar whose events need to be cleared
185  */
186 void ast_calendar_clear_events(struct ast_calendar *cal);
187
188 /*! \brief Grab and lock pointer to the calendar config (read only)
189  *
190  * \note ast_calendar_config_release must be called when finished with the pointer
191  *
192  * \return the parsed calendar config
193  */
194 const struct ast_config *ast_calendar_config_acquire(void);
195
196 /*! \brief Release the calendar config
197  */
198 void ast_calendar_config_release(void);
199
200 #endif /* _ASTERISK_CALENDAR_H */