Wed Jan 8 2020 09:49:42

Asterisk developer's documentation


calendar.h
Go to the documentation of this file.
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 #include "asterisk/module.h"
29 
30 /*! \file calendar.h
31  * \brief A general API for managing calendar events with Asterisk
32  *
33  * \author Terry Wilson <twilson@digium.com>
34  *
35  * \note This API implements an abstraction for handling different calendaring
36  * technologies in Asterisk. The services provided by the API are a dialplan
37  * function to query whether or not a calendar is busy at the present time, a
38  * adialplan function to query specific information about events in a time range,
39  * a devicestate provider, and notification of calendar events through execution
40  * of dialplan apps or dialplan logic at a specific context and extension. The
41  * information available through the CALENDAR_EVENT() dialplan function are:
42  *
43  * SUMMARY, DESCRIPTION, ORGANIZER, LOCATION
44  * CALENDAR, UID, START, END, and BUSYSTATE
45  *
46  * BUSYSTATE can have the values 0 (free), 1 (tentatively busy), or 2 (busy)
47  *
48  * Usage
49  * All calendaring configuration data is located in calendar.conf and is only read
50  * directly by the Calendaring API. Each calendar technology resource must register
51  * a load_calendar callback which will be passed an ast_calendar_load_data structure.
52  * The load_calendar callback function should then set the values it needs from this
53  * cfg, load the calendar data, and then loop updating the calendar data and events
54  * baesd on the refresh interval in the ast_calendar object. Each call to
55  * the load_calendar callback will be will run in its own thread.
56  *
57  * Updating events involves creating an astobj2 container of new events and passing
58  * it to the API through ast_calendar_merge_events.
59  *
60  * Calendar technology resource modules must also register an unref_calendar callback
61  * which will only be called when the resource module calls ast_calendar_unregister()
62  * to unregister that module's calendar type (usually done in module_unload())
63  */
64 
65 struct ast_calendar;
66 struct ast_calendar_event;
67 
68 /*! \brief Individual calendaring technology data */
70  const char *type;
71  const char *description;
72  const char *module;
74  int (* is_busy)(struct ast_calendar *calendar); /*!< Override default busy determination */
75  void *(* load_calendar)(void *data); /*!< Create private structure, add calendar events, etc. */
76  void *(* unref_calendar)(void *obj); /*!< Function to be called to free the private structure */
77  int (* write_event)(struct ast_calendar_event *event); /*!< Function for writing an event to the calendar */
79 };
80 
85 };
86 
88  char *data;
90 };
91 
92 /* \brief Calendar events */
95  AST_STRING_FIELD(summary);
97  AST_STRING_FIELD(organizer);
98  AST_STRING_FIELD(location);
99  AST_STRING_FIELD(uid);
100  AST_STRING_FIELD(categories);
101  );
102  int priority; /*!< Priority of event */
103  struct ast_calendar *owner; /*!< The calendar that owns this event */
104  time_t start; /*!< Start of event (UTC) */
105  time_t end; /*!< End of event (UTC) */
106  time_t alarm; /*!< Time for event notification */
107  enum ast_calendar_busy_state busy_state; /*!< The busy status of the event */
108  int notify_sched; /*!< The sched for event notification */
109  int bs_start_sched; /*!< The sched for changing the device state at the start of an event */
110  int bs_end_sched; /*!< The sched for changing the device state at the end of an event */
111  struct ast_dial *dial;
114 };
115 
116 /*! \brief Asterisk calendar structure */
117 struct ast_calendar {
118  const struct ast_calendar_tech *tech;
119  void *tech_pvt;
121  AST_STRING_FIELD(name); /*!< Name from config file [name] */
122  AST_STRING_FIELD(notify_channel); /*!< Channel to use for notification */
123  AST_STRING_FIELD(notify_context); /*!< Optional context to execute from for notification */
124  AST_STRING_FIELD(notify_extension); /*!< Optional extension to execute from for notification */
125  AST_STRING_FIELD(notify_app); /*!< Optional dialplan app to execute for notification */
126  AST_STRING_FIELD(notify_appdata); /*!< Optional arguments for dialplan app */
127  );
128  int autoreminder; /*!< If set, override any calendar_tech specific notification times and use this time (in mins) */
129  int notify_waittime; /*!< Maxiumum time to allow for a notification attempt */
130  int refresh; /*!< When to refresh the calendar events */
131  int timeframe; /*!< Span (in mins) of calendar data to pull with each request */
132  pthread_t thread; /*!< The thread that the calendar is loaded/updated in */
134  int unloading:1;
135  int pending_deletion:1;
136  struct ao2_container *events; /*!< The events that are known at this time */
137 };
138 
139 /*! \brief Register a new calendar technology
140  *
141  * \param tech calendar technology to register
142  *
143  * \retval 0 success
144  * \retval -1 failure
145  */
146 int ast_calendar_register(struct ast_calendar_tech *tech);
147 
148 /*! \brief Unregister a new calendar technology
149  *
150  * \param tech calendar technology to unregister
151  *
152  * \retval 0 success
153  * \retval -1 failure
154  */
155 void ast_calendar_unregister(struct ast_calendar_tech *tech);
156 
157 /*! \brief Allocate an astobj2 ast_calendar_event object
158  *
159  * \param cal calendar to allocate an event for
160  *
161  * \return a new, initialized calendar event
162  */
163 struct ast_calendar_event *ast_calendar_event_alloc(struct ast_calendar *cal);
164 
165 /*! \brief Allocate an astobj2 container for ast_calendar_event objects
166  *
167  * \return a new event container
168  */
170 
171 /*! \brief Add an event to the list of events for a calendar
172  *
173  * \param cal calendar containing the events to be merged
174  * \param new_events an oa2 container of events to be merged into cal->events
175  */
176 void ast_calendar_merge_events(struct ast_calendar *cal, struct ao2_container *new_events);
177 
178 /*! \brief Unreference an ast_calendar_event
179  *
180  * \param event event to unref
181  *
182  * \return NULL
183  */
184 struct ast_calendar_event *ast_calendar_unref_event(struct ast_calendar_event *event);
185 
186 /*! \brief Remove all events from calendar
187  *
188  * \param cal calendar whose events need to be cleared
189  */
190 void ast_calendar_clear_events(struct ast_calendar *cal);
191 
192 /*! \brief Grab and lock pointer to the calendar config (read only)
193  *
194  * \note ast_calendar_config_release must be called when finished with the pointer
195  *
196  * \return the parsed calendar config
197  */
198 const struct ast_config *ast_calendar_config_acquire(void);
199 
200 /*! \brief Release the calendar config
201  */
202 void ast_calendar_config_release(void);
203 
204 #endif /* _ASTERISK_CALENDAR_H */
struct ast_calendar_tech * next
Definition: calendar.h:78
Main Channel structure associated with a channel.
Definition: channel.h:742
ast_cond_t unload
Definition: calendar.h:133
Asterisk locking-related definitions:
int ast_calendar_register(struct ast_calendar_tech *tech)
Register a new calendar technology.
Definition: res_calendar.c:490
Asterisk main include file. File version handling, generic pbx functions.
static int unloading
Definition: func_lock.c:114
Main dialing structure. Contains global options, channels being dialed, and more! ...
Definition: dial.c:47
struct ast_calendar_tech::@145 list
Configuration File Parser.
Dialing API.
const char * module
Definition: calendar.h:72
struct ast_module_user * user
Definition: calendar.h:73
#define AST_DECLARE_STRING_FIELDS(field_list)
Declare the fields needed in a structure.
Definition: stringfields.h:235
int notify_waittime
Definition: calendar.h:129
const char * description
Definition: calendar.h:71
int timeframe
Definition: calendar.h:131
String fields in structures.
pthread_cond_t ast_cond_t
Definition: lock.h:144
struct ast_config * ast_calendar_config_acquire(void)
Grab and lock pointer to the calendar config (read only)
Definition: res_calendar.c:237
void ast_calendar_clear_events(struct ast_calendar *cal)
Remove all events from calendar.
Definition: res_calendar.c:596
struct ast_channel * notify_chan
Definition: calendar.h:112
void ast_calendar_merge_events(struct ast_calendar *cal, struct ao2_container *new_events)
Add an event to the list of events for a calendar.
Definition: res_calendar.c:961
void * tech_pvt
Definition: calendar.h:119
const char * type
Definition: calendar.h:70
struct ao2_container * ast_calendar_event_container_alloc(void)
Allocate an astobj2 container for ast_calendar_event objects.
Definition: res_calendar.c:625
#define AST_STRING_FIELD(name)
Declare a string field.
Definition: stringfields.h:220
A set of macros to manage forward-linked lists.
struct ast_calendar_tech * tech
Definition: calendar.h:118
struct ao2_container * events
Definition: calendar.h:136
#define AST_LIST_HEAD_NOLOCK(name, type)
Defines a structure to be used to hold a list of specified type (with no lock).
Definition: linkedlists.h:224
struct ast_calendar_event * ast_calendar_event_alloc(struct ast_calendar *cal)
Allocate an astobj2 ast_calendar_event object.
Definition: res_calendar.c:603
pthread_t thread
Definition: calendar.h:132
ast_calendar_busy_state
Definition: calendar.h:81
int(* write_event)(struct ast_calendar_event *event)
Definition: calendar.h:77
#define AST_LIST_ENTRY(type)
Declare a forward link structure inside a list entry.
Definition: linkedlists.h:409
static const char name[]
struct ast_calendar * owner
Definition: calendar.h:103
struct ast_calendar_event * ast_calendar_unref_event(struct ast_calendar_event *event)
Unreference an ast_calendar_event.
Definition: res_calendar.c:300
int(* is_busy)(struct ast_calendar *calendar)
Definition: calendar.h:74
void ast_calendar_unregister(struct ast_calendar_tech *tech)
Unregister a new calendar technology.
Definition: res_calendar.c:523
Individual calendaring technology data.
Definition: calendar.h:69
struct ast_dial * dial
Definition: calendar.h:111
Asterisk calendar structure.
Definition: calendar.h:117
int autoreminder
Definition: calendar.h:128
void ast_calendar_config_release(void)
Release the calendar config.
Definition: res_calendar.c:249
Asterisk module definitions.