calendar.h

Go to the documentation of this file.
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    struct ast_variable *vars; /*!< Channel variables to pass to notification channel */
00129    int autoreminder;    /*!< If set, override any calendar_tech specific notification times and use this time (in mins) */
00130    int notify_waittime; /*!< Maxiumum time to allow for a notification attempt */
00131    int refresh;         /*!< When to refresh the calendar events */
00132    int timeframe;       /*!< Span (in mins) of calendar data to pull with each request */
00133    pthread_t thread;    /*!< The thread that the calendar is loaded/updated in */
00134    ast_cond_t unload;
00135    int unloading:1;
00136    int pending_deletion:1;
00137    struct ao2_container *events;  /*!< The events that are known at this time */
00138 };
00139 
00140 /*! \brief Register a new calendar technology
00141  *
00142  * \param tech calendar technology to register
00143  *
00144  * \retval 0 success
00145  * \retval -1 failure
00146  */
00147 int ast_calendar_register(struct ast_calendar_tech *tech);
00148 
00149 /*! \brief Unregister a new calendar technology
00150  *
00151  * \param tech calendar technology to unregister
00152  *
00153  * \retval 0 success
00154  * \retval -1 failure
00155  */
00156 void ast_calendar_unregister(struct ast_calendar_tech *tech);
00157 
00158 /*! \brief Allocate an astobj2 ast_calendar_event object
00159  *
00160  * \param cal calendar to allocate an event for
00161  *
00162  * \return a new, initialized calendar event
00163  */
00164 struct ast_calendar_event *ast_calendar_event_alloc(struct ast_calendar *cal);
00165 
00166 /*! \brief Allocate an astobj2 container for ast_calendar_event objects
00167  *
00168  * \return a new event container
00169  */
00170 struct ao2_container *ast_calendar_event_container_alloc(void);
00171 
00172 /*! \brief Add an event to the list of events for a calendar
00173  *
00174  * \param cal calendar containing the events to be merged
00175  * \param new_events an oa2 container of events to be merged into cal->events
00176  */
00177 void ast_calendar_merge_events(struct ast_calendar *cal, struct ao2_container *new_events);
00178 
00179 /*! \brief Unreference an ast_calendar_event 
00180  *
00181  * \param event event to unref
00182  *
00183  * \return NULL
00184  */
00185 struct ast_calendar_event *ast_calendar_unref_event(struct ast_calendar_event *event);
00186 
00187 /*! \brief Remove all events from calendar 
00188  *
00189  * \param cal calendar whose events need to be cleared
00190  */
00191 void ast_calendar_clear_events(struct ast_calendar *cal);
00192 
00193 /*! \brief Grab and lock pointer to the calendar config (read only)
00194  *
00195  * \note ast_calendar_config_release must be called when finished with the pointer
00196  *
00197  * \return the parsed calendar config
00198  */
00199 const struct ast_config *ast_calendar_config_acquire(void);
00200 
00201 /*! \brief Release the calendar config
00202  */
00203 void ast_calendar_config_release(void);
00204 
00205 #endif /* _ASTERISK_CALENDAR_H */

Generated on Thu Apr 16 06:27:16 2015 for Asterisk - The Open Source Telephony Project by  doxygen 1.5.6