Wed Jan 8 2020 09:49:58

Asterisk developer's documentation


calendar.h File Reference

A general API for managing calendar events with Asterisk. More...

#include "asterisk.h"
#include "asterisk/stringfields.h"
#include "asterisk/config.h"
#include "asterisk/linkedlists.h"
#include "asterisk/lock.h"
#include "asterisk/dial.h"
#include "asterisk/module.h"

Go to the source code of this file.

Data Structures

struct  ast_calendar
 Asterisk calendar structure. More...
 
struct  ast_calendar_attendee
 
struct  ast_calendar_event
 
struct  ast_calendar_tech
 Individual calendaring technology data. More...
 
struct  ast_calendar_event::attendees
 

Enumerations

enum  ast_calendar_busy_state { AST_CALENDAR_BS_FREE = 0, AST_CALENDAR_BS_BUSY_TENTATIVE, AST_CALENDAR_BS_BUSY }
 

Functions

void ast_calendar_clear_events (struct ast_calendar *cal)
 Remove all events from calendar. More...
 
struct ast_configast_calendar_config_acquire (void)
 Grab and lock pointer to the calendar config (read only) More...
 
void ast_calendar_config_release (void)
 Release the calendar config. More...
 
struct ast_calendar_eventast_calendar_event_alloc (struct ast_calendar *cal)
 Allocate an astobj2 ast_calendar_event object. More...
 
struct ao2_containerast_calendar_event_container_alloc (void)
 Allocate an astobj2 container for ast_calendar_event objects. More...
 
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. More...
 
int ast_calendar_register (struct ast_calendar_tech *tech)
 Register a new calendar technology. More...
 
struct ast_calendar_eventast_calendar_unref_event (struct ast_calendar_event *event)
 Unreference an ast_calendar_event. More...
 
void ast_calendar_unregister (struct ast_calendar_tech *tech)
 Unregister a new calendar technology. More...
 

Detailed Description

A general API for managing calendar events with Asterisk.

Author
Terry Wilson twils.nosp@m.on@d.nosp@m.igium.nosp@m..com
Note
This API implements an abstraction for handling different calendaring technologies in Asterisk. The services provided by the API are a dialplan function to query whether or not a calendar is busy at the present time, a adialplan function to query specific information about events in a time range, a devicestate provider, and notification of calendar events through execution of dialplan apps or dialplan logic at a specific context and extension. The information available through the CALENDAR_EVENT() dialplan function are:

SUMMARY, DESCRIPTION, ORGANIZER, LOCATION CALENDAR, UID, START, END, and BUSYSTATE

BUSYSTATE can have the values 0 (free), 1 (tentatively busy), or 2 (busy)

Usage All calendaring configuration data is located in calendar.conf and is only read directly by the Calendaring API. Each calendar technology resource must register a load_calendar callback which will be passed an ast_calendar_load_data structure. The load_calendar callback function should then set the values it needs from this cfg, load the calendar data, and then loop updating the calendar data and events baesd on the refresh interval in the ast_calendar object. Each call to the load_calendar callback will be will run in its own thread.

Updating events involves creating an astobj2 container of new events and passing it to the API through ast_calendar_merge_events.

Calendar technology resource modules must also register an unref_calendar callback which will only be called when the resource module calls ast_calendar_unregister() to unregister that module's calendar type (usually done in module_unload())

Definition in file calendar.h.

Enumeration Type Documentation

Enumerator
AST_CALENDAR_BS_FREE 
AST_CALENDAR_BS_BUSY_TENTATIVE 
AST_CALENDAR_BS_BUSY 

Definition at line 81 of file calendar.h.

Function Documentation

void ast_calendar_clear_events ( struct ast_calendar cal)

Remove all events from calendar.

Parameters
calcalendar whose events need to be cleared

Definition at line 596 of file res_calendar.c.

References ao2_callback, ast_debug, clear_events_cb(), ast_calendar::events, ast_calendar::name, OBJ_MULTIPLE, OBJ_NODATA, and OBJ_UNLINK.

Referenced by calendar_destructor().

597 {
598  ast_debug(3, "Clearing all events for calendar %s\n", cal->name);
599 
601 }
static int clear_events_cb(void *user_data, void *arg, int flags)
Definition: res_calendar.c:587
#define ao2_callback(c, flags, cb_fn, arg)
Definition: astobj2.h:910
#define ast_debug(level,...)
Log a DEBUG message.
Definition: logger.h:236
const ast_string_field name
Definition: calendar.h:127
struct ao2_container * events
Definition: calendar.h:136
struct ast_config* ast_calendar_config_acquire ( void  )

Grab and lock pointer to the calendar config (read only)

Note
ast_calendar_config_release must be called when finished with the pointer
Returns
the parsed calendar config

Definition at line 237 of file res_calendar.c.

References ast_rwlock_rdlock, ast_rwlock_unlock, and calendar_config.

Referenced by caldav_load_calendar(), ewscal_load_calendar(), exchangecal_load_calendar(), and ical_load_calendar().

238 {
240 
241  if (!calendar_config) {
243  return NULL;
244  }
245 
246  return calendar_config;
247 }
#define ast_rwlock_rdlock(a)
Definition: lock.h:201
#define ast_rwlock_unlock(a)
Definition: lock.h:200
static struct ast_config * calendar_config
Definition: res_calendar.c:234
static ast_rwlock_t config_lock
Definition: res_calendar.c:235
void ast_calendar_config_release ( void  )

Release the calendar config.

Definition at line 249 of file res_calendar.c.

References ast_rwlock_unlock, and config_lock.

Referenced by caldav_load_calendar(), ewscal_load_calendar(), exchangecal_load_calendar(), and ical_load_calendar().

250 {
252 }
#define ast_rwlock_unlock(a)
Definition: lock.h:200
static ast_rwlock_t config_lock
Definition: res_calendar.c:235
struct ast_calendar_event* ast_calendar_event_alloc ( struct ast_calendar cal)

Allocate an astobj2 ast_calendar_event object.

Parameters
calcalendar to allocate an event for
Returns
a new, initialized calendar event

Definition at line 603 of file res_calendar.c.

References ao2_alloc, ast_calendar_unref_event(), AST_LIST_HEAD_INIT_NOLOCK, ast_string_field_init, ast_calendar_event::attendees, calendar_event_destructor(), and evententry::event.

Referenced by caldav_add_event(), calendar_write_exec(), icalendar_add_event(), parse_tag(), and startelm().

604 {
605  struct ast_calendar_event *event;
606  if (!(event = ao2_alloc(sizeof(*event), calendar_event_destructor))) {
607  return NULL;
608  }
609 
610  if (ast_string_field_init(event, 32)) {
611  event = ast_calendar_unref_event(event);
612  return NULL;
613  }
614 
615  event->owner = cal;
616  event->notify_sched = -1;
617  event->bs_start_sched = -1;
618  event->bs_end_sched = -1;
619 
621 
622  return event;
623 }
#define ast_string_field_init(x, size)
Initialize a field pool and fields.
Definition: stringfields.h:249
static void calendar_event_destructor(void *obj)
Definition: res_calendar.c:545
#define ao2_alloc(data_size, destructor_fn)
Definition: astobj2.h:430
struct ast_calendar_event * ast_calendar_unref_event(struct ast_calendar_event *event)
Unreference an ast_calendar_event.
Definition: res_calendar.c:300
struct ast_calendar_event::attendees attendees
#define AST_LIST_HEAD_INIT_NOLOCK(head)
Initializes a list head structure.
Definition: linkedlists.h:666
struct ao2_container* ast_calendar_event_container_alloc ( void  )

Allocate an astobj2 container for ast_calendar_event objects.

Returns
a new event container

Definition at line 625 of file res_calendar.c.

References ao2_container_alloc, CALENDAR_BUCKETS, event_cmp_fn(), and event_hash_fn().

Referenced by caldav_load_calendar(), ewscal_load_calendar(), exchangecal_load_calendar(), and ical_load_calendar().

626 {
628 }
static int event_hash_fn(const void *obj, const int flags)
Definition: res_calendar.c:280
#define CALENDAR_BUCKETS
Definition: res_calendar.c:199
static int event_cmp_fn(void *obj, void *arg, int flags)
Definition: res_calendar.c:286
#define ao2_container_alloc(arg1, arg2, arg3)
Definition: astobj2.h:734
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.

Parameters
calcalendar containing the events to be merged
new_eventsan oa2 container of events to be merged into cal->events

Definition at line 961 of file res_calendar.c.

References add_new_event_cb(), ao2_callback, ast_calendar::events, merge_events_cb(), OBJ_MULTIPLE, OBJ_NODATA, and OBJ_UNLINK.

Referenced by endelm(), icalendar_update_events(), startelm(), update_caldav(), and update_exchangecal().

962 {
963  /* Loop through all events attached to the calendar. If there is a matching new event
964  * merge its data over and handle any schedule changes that need to be made. Then remove
965  * the new_event from new_events so that we are left with only new_events that we can add later. */
967 
968  /* Now, we should only have completely new events in new_events. Loop through and add them */
970 }
#define ao2_callback(c, flags, cb_fn, arg)
Definition: astobj2.h:910
struct ao2_container * events
Definition: calendar.h:136
static int merge_events_cb(void *obj, void *arg, int flags)
Definition: res_calendar.c:924
static int add_new_event_cb(void *obj, void *arg, int flags)
Definition: res_calendar.c:951
int ast_calendar_register ( struct ast_calendar_tech tech)

Register a new calendar technology.

Parameters
techcalendar technology to register
Return values
0success
-1failure

Definition at line 490 of file res_calendar.c.

References AST_LIST_INSERT_HEAD, AST_LIST_LOCK, AST_LIST_TRAVERSE, AST_LIST_UNLOCK, ast_log(), ast_module_user_add, ast_verb, ast_calendar_tech::description, evententry::list, load_tech_calendars(), LOG_WARNING, ast_calendar_tech::type, and ast_calendar_tech::user.

Referenced by load_module().

491 {
492  struct ast_calendar_tech *iter;
493 
495  AST_LIST_TRAVERSE(&techs, iter, list) {
496  if(!strcasecmp(tech->type, iter->type)) {
497  ast_log(LOG_WARNING, "Already have a handler for calendar type '%s'\n", tech->type);
499  return -1;
500  }
501  }
503  tech->user = ast_module_user_add(NULL);
505 
506  ast_verb(2, "Registered calendar type '%s' (%s)\n", tech->type, tech->description);
507 
508  return load_tech_calendars(tech);
509 }
#define AST_LIST_LOCK(head)
Locks a list.
Definition: linkedlists.h:39
struct ast_calendar_tech::@145 list
static int load_tech_calendars(struct ast_calendar_tech *tech)
Definition: res_calendar.c:454
#define LOG_WARNING
Definition: logger.h:144
#define AST_LIST_UNLOCK(head)
Attempts to unlock a list.
Definition: linkedlists.h:139
struct ast_module_user * user
Definition: calendar.h:73
const char * description
Definition: calendar.h:71
#define ast_verb(level,...)
Definition: logger.h:243
const char * type
Definition: calendar.h:70
#define ast_module_user_add(chan)
Definition: module.h:268
void ast_log(int level, const char *file, int line, const char *function, const char *fmt,...)
Used for sending a log message This is the standard logger function. Probably the only way you will i...
Definition: logger.c:1207
#define AST_LIST_TRAVERSE(head, var, field)
Loops over (traverses) the entries in a list.
Definition: linkedlists.h:490
#define AST_LIST_INSERT_HEAD(head, elm, field)
Inserts a list entry at the head of a list.
Definition: linkedlists.h:696
Individual calendaring technology data.
Definition: calendar.h:69
struct ast_calendar_event* ast_calendar_unref_event ( struct ast_calendar_event event)

Unreference an ast_calendar_event.

Parameters
eventevent to unref
Returns
NULL

Definition at line 300 of file res_calendar.c.

References ao2_ref.

Referenced by ast_calendar_event_alloc(), caldav_add_event(), calendar_devstate_change(), calendar_query_exec(), calendar_write_exec(), do_notify(), endelm(), event_notification_destroy(), handle_show_calendar(), icalendar_add_event(), merge_events_cb(), and parse_tag().

301 {
302  ao2_ref(event, -1);
303  return NULL;
304 }
#define ao2_ref(o, delta)
Definition: astobj2.h:472
void ast_calendar_unregister ( struct ast_calendar_tech tech)

Unregister a new calendar technology.

Parameters
techcalendar technology to unregister
Return values
0success
-1failure

Definition at line 523 of file res_calendar.c.

References ao2_callback, AST_LIST_LOCK, AST_LIST_REMOVE_CURRENT, AST_LIST_TRAVERSE_SAFE_BEGIN, AST_LIST_TRAVERSE_SAFE_END, AST_LIST_UNLOCK, ast_module_user_remove, ast_verb, evententry::list, match_caltech_cb(), OBJ_MULTIPLE, OBJ_NODATA, OBJ_UNLINK, ast_calendar_tech::type, and ast_calendar_tech::user.

Referenced by load_tech_calendars(), and unload_module().

524 {
525  struct ast_calendar_tech *iter;
526 
529  if (iter != tech) {
530  continue;
531  }
532 
534 
537  ast_verb(2, "Unregistered calendar type '%s'\n", tech->type);
538  break;
539  }
542 
543 }
#define AST_LIST_LOCK(head)
Locks a list.
Definition: linkedlists.h:39
static struct ao2_container * calendars
Definition: res_calendar.c:201
struct ast_calendar_tech::@145 list
#define AST_LIST_UNLOCK(head)
Attempts to unlock a list.
Definition: linkedlists.h:139
#define ao2_callback(c, flags, cb_fn, arg)
Definition: astobj2.h:910
struct ast_module_user * user
Definition: calendar.h:73
#define ast_module_user_remove(user)
Definition: module.h:269
#define AST_LIST_TRAVERSE_SAFE_END
Closes a safe loop traversal block.
Definition: linkedlists.h:600
#define ast_verb(level,...)
Definition: logger.h:243
const char * type
Definition: calendar.h:70
#define AST_LIST_REMOVE_CURRENT(field)
Removes the current entry from a list during a traversal.
Definition: linkedlists.h:554
static int match_caltech_cb(void *user_data, void *arg, int flags)
Definition: res_calendar.c:511
Individual calendaring technology data.
Definition: calendar.h:69
#define AST_LIST_TRAVERSE_SAFE_BEGIN(head, var, field)
Loops safely over (traverses) the entries in a list.
Definition: linkedlists.h:528