00001 /* 00002 * Asterisk -- An open source telephony toolkit. 00003 * 00004 * Copyright (C) 2008 - 2009, Digium, Inc. 00005 * 00006 * Terry Wilson <twilson@digium.com> 00007 * 00008 * See http://www.asterisk.org for more information about 00009 * the Asterisk project. Please do not directly contact 00010 * any of the maintainers of this project for assistance; 00011 * the project provides a web site, mailing lists and IRC 00012 * channels for your use. 00013 * 00014 * This program is free software, distributed under the terms of 00015 * the GNU General Public License Version 2. See the LICENSE file 00016 * at the top of the source tree. 00017 */ 00018 00019 #ifndef _ASTERISK_CALENDAR_H 00020 #define _ASTERISK_CALENDAR_H 00021 00022 #include "asterisk.h" 00023 #include "asterisk/stringfields.h" 00024 #include "asterisk/config.h" 00025 #include "asterisk/linkedlists.h" 00026 #include "asterisk/lock.h" 00027 #include "asterisk/dial.h" 00028 #include "asterisk/module.h" 00029 00030 /*! \file calendar.h 00031 * \brief A general API for managing calendar events with Asterisk 00032 * 00033 * \author Terry Wilson <twilson@digium.com> 00034 * 00035 * \note This API implements an abstraction for handling different calendaring 00036 * technologies in Asterisk. The services provided by the API are a dialplan 00037 * function to query whether or not a calendar is busy at the present time, a 00038 * adialplan function to query specific information about events in a time range, 00039 * a devicestate provider, and notification of calendar events through execution 00040 * of dialplan apps or dialplan logic at a specific context and extension. The 00041 * information available through the CALENDAR_EVENT() dialplan function are: 00042 * 00043 * SUMMARY, DESCRIPTION, ORGANIZER, LOCATION 00044 * CALENDAR, UID, START, END, and BUSYSTATE 00045 * 00046 * BUSYSTATE can have the values 0 (free), 1 (tentatively busy), or 2 (busy) 00047 * 00048 * Usage 00049 * All calendaring configuration data is located in calendar.conf and is only read 00050 * directly by the Calendaring API. Each calendar technology resource must register 00051 * a load_calendar callback which will be passed an ast_calendar_load_data structure. 00052 * The load_calendar callback function should then set the values it needs from this 00053 * cfg, load the calendar data, and then loop updating the calendar data and events 00054 * baesd on the refresh interval in the ast_calendar object. Each call to 00055 * the load_calendar callback will be will run in its own thread. 00056 * 00057 * Updating events involves creating an astobj2 container of new events and passing 00058 * it to the API through ast_calendar_merge_events. 00059 * 00060 * Calendar technology resource modules must also register an unref_calendar callback 00061 * which will only be called when the resource module calls ast_calendar_unregister() 00062 * to unregister that module's calendar type (usually done in module_unload()) 00063 */ 00064 00065 struct ast_calendar; 00066 struct ast_calendar_event; 00067 00068 /*! \brief Individual calendaring technology data */ 00069 struct ast_calendar_tech { 00070 const char *type; 00071 const char *description; 00072 const char *module; 00073 struct ast_module_user *user; 00074 int (* is_busy)(struct ast_calendar *calendar); /*!< Override default busy determination */ 00075 void *(* load_calendar)(void *data); /*!< Create private structure, add calendar events, etc. */ 00076 void *(* unref_calendar)(void *obj); /*!< Function to be called to free the private structure */ 00077 int (* write_event)(struct ast_calendar_event *event); /*!< Function for writing an event to the calendar */ 00078 AST_LIST_ENTRY(ast_calendar_tech) list; 00079 }; 00080 00081 enum ast_calendar_busy_state { 00082 AST_CALENDAR_BS_FREE = 0, 00083 AST_CALENDAR_BS_BUSY_TENTATIVE, 00084 AST_CALENDAR_BS_BUSY, 00085 }; 00086 00087 struct ast_calendar_attendee { 00088 char *data; 00089 AST_LIST_ENTRY(ast_calendar_attendee) next; 00090 }; 00091 00092 /* \brief Calendar events */ 00093 struct ast_calendar_event { 00094 AST_DECLARE_STRING_FIELDS( 00095 AST_STRING_FIELD(summary); 00096 AST_STRING_FIELD(description); 00097 AST_STRING_FIELD(organizer); 00098 AST_STRING_FIELD(location); 00099 AST_STRING_FIELD(uid); 00100 AST_STRING_FIELD(categories); 00101 ); 00102 int priority; /*!< Priority of event */ 00103 struct ast_calendar *owner; /*!< The calendar that owns this event */ 00104 time_t start; /*!< Start of event (UTC) */ 00105 time_t end; /*!< End of event (UTC) */ 00106 time_t alarm; /*!< Time for event notification */ 00107 enum ast_calendar_busy_state busy_state; /*!< The busy status of the event */ 00108 int notify_sched; /*!< The sched for event notification */ 00109 int bs_start_sched; /*!< The sched for changing the device state at the start of an event */ 00110 int bs_end_sched; /*!< The sched for changing the device state at the end of an event */ 00111 struct ast_dial *dial; 00112 struct ast_channel *notify_chan; 00113 AST_LIST_HEAD_NOLOCK(attendees, ast_calendar_attendee) attendees; 00114 }; 00115 00116 /*! \brief Asterisk calendar structure */ 00117 struct ast_calendar { 00118 const struct ast_calendar_tech *tech; 00119 void *tech_pvt; 00120 AST_DECLARE_STRING_FIELDS( 00121 AST_STRING_FIELD(name); /*!< Name from config file [name] */ 00122 AST_STRING_FIELD(notify_channel); /*!< Channel to use for notification */ 00123 AST_STRING_FIELD(notify_context); /*!< Optional context to execute from for notification */ 00124 AST_STRING_FIELD(notify_extension); /*!< Optional extension to execute from for notification */ 00125 AST_STRING_FIELD(notify_app); /*!< Optional dialplan app to execute for notification */ 00126 AST_STRING_FIELD(notify_appdata); /*!< Optional arguments for dialplan app */ 00127 ); 00128 int autoreminder; /*!< If set, override any calendar_tech specific notification times and use this time (in mins) */ 00129 int notify_waittime; /*!< Maxiumum time to allow for a notification attempt */ 00130 int refresh; /*!< When to refresh the calendar events */ 00131 int timeframe; /*!< Span (in mins) of calendar data to pull with each request */ 00132 pthread_t thread; /*!< The thread that the calendar is loaded/updated in */ 00133 ast_cond_t unload; 00134 int unloading:1; 00135 int pending_deletion:1; 00136 struct ao2_container *events; /*!< The events that are known at this time */ 00137 }; 00138 00139 /*! \brief Register a new calendar technology 00140 * 00141 * \param tech calendar technology to register 00142 * 00143 * \retval 0 success 00144 * \retval -1 failure 00145 */ 00146 int ast_calendar_register(struct ast_calendar_tech *tech); 00147 00148 /*! \brief Unregister a new calendar technology 00149 * 00150 * \param tech calendar technology to unregister 00151 * 00152 * \retval 0 success 00153 * \retval -1 failure 00154 */ 00155 void ast_calendar_unregister(struct ast_calendar_tech *tech); 00156 00157 /*! \brief Allocate an astobj2 ast_calendar_event object 00158 * 00159 * \param cal calendar to allocate an event for 00160 * 00161 * \return a new, initialized calendar event 00162 */ 00163 struct ast_calendar_event *ast_calendar_event_alloc(struct ast_calendar *cal); 00164 00165 /*! \brief Allocate an astobj2 container for ast_calendar_event objects 00166 * 00167 * \return a new event container 00168 */ 00169 struct ao2_container *ast_calendar_event_container_alloc(void); 00170 00171 /*! \brief Add an event to the list of events for a calendar 00172 * 00173 * \param cal calendar containing the events to be merged 00174 * \param new_events an oa2 container of events to be merged into cal->events 00175 */ 00176 void ast_calendar_merge_events(struct ast_calendar *cal, struct ao2_container *new_events); 00177 00178 /*! \brief Unreference an ast_calendar_event 00179 * 00180 * \param event event to unref 00181 * 00182 * \return NULL 00183 */ 00184 struct ast_calendar_event *ast_calendar_unref_event(struct ast_calendar_event *event); 00185 00186 /*! \brief Remove all events from calendar 00187 * 00188 * \param cal calendar whose events need to be cleared 00189 */ 00190 void ast_calendar_clear_events(struct ast_calendar *cal); 00191 00192 /*! \brief Grab and lock pointer to the calendar config (read only) 00193 * 00194 * \note ast_calendar_config_release must be called when finished with the pointer 00195 * 00196 * \return the parsed calendar config 00197 */ 00198 const struct ast_config *ast_calendar_config_acquire(void); 00199 00200 /*! \brief Release the calendar config 00201 */ 00202 void ast_calendar_config_release(void); 00203 00204 #endif /* _ASTERISK_CALENDAR_H */