Asterisk - The Open Source Telephony Project  18.5.0
Data Structures | Enumerations | Functions
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"
Include dependency graph for calendar.h:
This graph shows which files directly or indirectly include this file:

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...
 
const 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

◆ ast_calendar_busy_state

Enumerator
AST_CALENDAR_BS_FREE 
AST_CALENDAR_BS_BUSY_TENTATIVE 
AST_CALENDAR_BS_BUSY 

Definition at line 81 of file calendar.h.

Function Documentation

◆ ast_calendar_clear_events()

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 660 of file res_calendar.c.

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

Referenced by calendar_destructor().

661 {
662  ast_debug(3, "Clearing all events for calendar %s\n", cal->name);
663 
665 }
static int clear_events_cb(void *user_data, void *arg, int flags)
Definition: res_calendar.c:651
#define ao2_callback(c, flags, cb_fn, arg)
Definition: astobj2.h:1716
#define NULL
Definition: resample.c:96
#define ast_debug(level,...)
Log a DEBUG message.
Definition: logger.h:452
const ast_string_field name
Definition: calendar.h:127
struct ao2_container * events
Definition: calendar.h:138

◆ ast_calendar_config_acquire()

const 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 258 of file res_calendar.c.

References ast_rwlock_rdlock, ast_rwlock_unlock, calendar_config, config_lock, and NULL.

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

259 {
261 
262  if (!calendar_config) {
264  return NULL;
265  }
266 
267  return calendar_config;
268 }
#define ast_rwlock_rdlock(a)
Definition: lock.h:233
#define NULL
Definition: resample.c:96
#define ast_rwlock_unlock(a)
Definition: lock.h:232
static struct ast_config * calendar_config
Definition: res_calendar.c:255
static ast_rwlock_t config_lock
Definition: res_calendar.c:256

◆ ast_calendar_config_release()

void ast_calendar_config_release ( void  )

Release the calendar config.

Definition at line 270 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().

271 {
273 }
#define ast_rwlock_unlock(a)
Definition: lock.h:232
static ast_rwlock_t config_lock
Definition: res_calendar.c:256

◆ ast_calendar_event_alloc()

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 667 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(), evententry::event, and NULL.

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

668 {
669  struct ast_calendar_event *event;
670  if (!(event = ao2_alloc(sizeof(*event), calendar_event_destructor))) {
671  return NULL;
672  }
673 
674  if (ast_string_field_init(event, 32)) {
675  event = ast_calendar_unref_event(event);
676  return NULL;
677  }
678 
679  event->owner = cal;
680  event->notify_sched = -1;
681  event->bs_start_sched = -1;
682  event->bs_end_sched = -1;
683 
685 
686  return event;
687 }
Definition: astman.c:222
#define NULL
Definition: resample.c:96
#define ast_string_field_init(x, size)
Initialize a field pool and fields.
Definition: stringfields.h:353
static void calendar_event_destructor(void *obj)
Definition: res_calendar.c:609
#define ao2_alloc(data_size, destructor_fn)
Definition: astobj2.h:411
struct ast_calendar_event::attendees attendees
#define AST_LIST_HEAD_INIT_NOLOCK(head)
Initializes a list head structure.
Definition: linkedlists.h:680
struct ast_calendar_event * ast_calendar_unref_event(struct ast_calendar_event *event)
Unreference an ast_calendar_event.
Definition: res_calendar.c:321

◆ ast_calendar_event_container_alloc()

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 689 of file res_calendar.c.

References AO2_ALLOC_OPT_LOCK_MUTEX, ao2_container_alloc_hash, CALENDAR_BUCKETS, event_cmp_fn(), event_hash_fn(), and NULL.

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

690 {
693 }
static int event_hash_fn(const void *obj, const int flags)
Definition: res_calendar.c:301
#define NULL
Definition: resample.c:96
#define CALENDAR_BUCKETS
Definition: res_calendar.c:220
#define ao2_container_alloc_hash(ao2_options, container_options, n_buckets, hash_fn, sort_fn, cmp_fn)
Definition: astobj2.h:1310
static int event_cmp_fn(void *obj, void *arg, int flags)
Definition: res_calendar.c:307

◆ ast_calendar_merge_events()

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 1053 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().

1054 {
1055  /* Loop through all events attached to the calendar. If there is a matching new event
1056  * merge its data over and handle any schedule changes that need to be made. Then remove
1057  * the new_event from new_events so that we are left with only new_events that we can add later. */
1059 
1060  /* Now, we should only have completely new events in new_events. Loop through and add them */
1062 }
#define ao2_callback(c, flags, cb_fn, arg)
Definition: astobj2.h:1716
struct ao2_container * events
Definition: calendar.h:138
static int merge_events_cb(void *obj, void *arg, int flags)
static int add_new_event_cb(void *obj, void *arg, int flags)

◆ ast_calendar_register()

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 549 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, NULL, ast_calendar_tech::type, and ast_calendar_tech::user.

Referenced by load_module().

550 {
551  struct ast_calendar_tech *iter;
552 
553  if (!calendar_config) {
554  ast_log(LOG_WARNING, "Calendar support disabled, not loading %s calendar module\n", tech->type);
555  return -1;
556  }
557 
559  AST_LIST_TRAVERSE(&techs, iter, list) {
560  if(!strcasecmp(tech->type, iter->type)) {
561  ast_log(LOG_WARNING, "Already have a handler for calendar type '%s'\n", tech->type);
563  return -1;
564  }
565  }
567  tech->user = ast_module_user_add(NULL);
569 
570  ast_verb(2, "Registered calendar type '%s' (%s)\n", tech->type, tech->description);
571 
572  return load_tech_calendars(tech);
573 }
#define AST_LIST_LOCK(head)
Locks a list.
Definition: linkedlists.h:39
static int load_tech_calendars(struct ast_calendar_tech *tech)
Definition: res_calendar.c:513
#define LOG_WARNING
Definition: logger.h:274
#define AST_LIST_UNLOCK(head)
Attempts to unlock a list.
Definition: linkedlists.h:139
struct ast_calendar_tech::@239 list
struct ast_module_user * user
Definition: calendar.h:73
const char * description
Definition: calendar.h:71
#define NULL
Definition: resample.c:96
#define ast_verb(level,...)
Definition: logger.h:463
const char * type
Definition: calendar.h:70
#define ast_log
Definition: astobj2.c:42
#define ast_module_user_add(chan)
Definition: module.h:426
#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:710
static struct ast_config * calendar_config
Definition: res_calendar.c:255
Individual calendaring technology data.
Definition: calendar.h:69

◆ ast_calendar_unref_event()

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 321 of file res_calendar.c.

References ao2_ref, and NULL.

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().

322 {
323  ao2_ref(event, -1);
324  return NULL;
325 }
#define NULL
Definition: resample.c:96
#define ao2_ref(o, delta)
Definition: astobj2.h:464

◆ ast_calendar_unregister()

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 587 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().

588 {
589  struct ast_calendar_tech *iter;
590 
593  if (iter != tech) {
594  continue;
595  }
596 
598 
601  ast_verb(2, "Unregistered calendar type '%s'\n", tech->type);
602  break;
603  }
606 
607 }
#define AST_LIST_LOCK(head)
Locks a list.
Definition: linkedlists.h:39
static struct ao2_container * calendars
Definition: res_calendar.c:222
#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:1716
struct ast_calendar_tech::@239 list
struct ast_module_user * user
Definition: calendar.h:73
#define ast_module_user_remove(user)
Definition: module.h:427
#define AST_LIST_TRAVERSE_SAFE_END
Closes a safe loop traversal block.
Definition: linkedlists.h:614
#define ast_verb(level,...)
Definition: logger.h:463
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:556
static int match_caltech_cb(void *user_data, void *arg, int flags)
Definition: res_calendar.c:575
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