Asterisk - The Open Source Telephony Project  21.4.1
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"

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
 Calendar events. More...
 
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.
 
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 based 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.

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

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

663 {
664  ast_debug(3, "Clearing all events for calendar %s\n", cal->name);
665 
666  ao2_callback(cal->events, OBJ_UNLINK | OBJ_NODATA | OBJ_MULTIPLE, clear_events_cb, NULL);
667 }
#define ao2_callback(c, flags, cb_fn, arg)
ao2_callback() is a generic function that applies cb_fn() to all objects in a container, as described below.
Definition: astobj2.h:1693
#define ast_debug(level,...)
Log a DEBUG message.
const ast_string_field name
Definition: calendar.h:129
struct ao2_container * events
Definition: calendar.h:140
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 260 of file res_calendar.c.

261 {
262  ast_rwlock_rdlock(&config_lock);
263 
264  if (!calendar_config) {
265  ast_rwlock_unlock(&config_lock);
266  return NULL;
267  }
268 
269  return calendar_config;
270 }
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 669 of file res_calendar.c.

References ast_calendar_unref_event(), AST_LIST_HEAD_INIT_NOLOCK, and ast_string_field_init.

670 {
671  struct ast_calendar_event *event;
672  if (!(event = ao2_alloc(sizeof(*event), calendar_event_destructor))) {
673  return NULL;
674  }
675 
676  if (ast_string_field_init(event, 32)) {
677  event = ast_calendar_unref_event(event);
678  return NULL;
679  }
680 
681  event->owner = cal;
682  event->notify_sched = -1;
683  event->bs_start_sched = -1;
684  event->bs_end_sched = -1;
685 
686  AST_LIST_HEAD_INIT_NOLOCK(&event->attendees);
687 
688  return event;
689 }
Definition: astman.c:222
#define ast_string_field_init(x, size)
Initialize a field pool and fields.
Definition: stringfields.h:359
#define AST_LIST_HEAD_INIT_NOLOCK(head)
Initializes a list head structure.
Definition: linkedlists.h:681
Calendar events.
Definition: calendar.h:95
struct ast_calendar_event * ast_calendar_unref_event(struct ast_calendar_event *event)
Unreference an ast_calendar_event.
Definition: res_calendar.c:323
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 691 of file res_calendar.c.

References AO2_ALLOC_OPT_LOCK_MUTEX, and ao2_container_alloc_hash.

692 {
693  return ao2_container_alloc_hash(AO2_ALLOC_OPT_LOCK_MUTEX, 0, CALENDAR_BUCKETS,
694  event_hash_fn, NULL, event_cmp_fn);
695 }
#define ao2_container_alloc_hash(ao2_options, container_options, n_buckets, hash_fn, sort_fn, cmp_fn)
Allocate and initialize a hash container with the desired number of buckets.
Definition: astobj2.h:1303
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 1060 of file res_calendar.c.

References ao2_callback, ast_calendar::events, OBJ_MULTIPLE, OBJ_NODATA, and OBJ_UNLINK.

1061 {
1062  /* Loop through all events attached to the calendar. If there is a matching new event
1063  * merge its data over and handle any schedule changes that need to be made. Then remove
1064  * the new_event from new_events so that we are left with only new_events that we can add later. */
1065  ao2_callback(cal->events, OBJ_UNLINK | OBJ_NODATA | OBJ_MULTIPLE, merge_events_cb, new_events);
1066 
1067  /* Now, we should only have completely new events in new_events. Loop through and add them */
1068  ao2_callback(new_events, OBJ_UNLINK | OBJ_NODATA | OBJ_MULTIPLE, add_new_event_cb, cal->events);
1069 }
#define ao2_callback(c, flags, cb_fn, arg)
ao2_callback() is a generic function that applies cb_fn() to all objects in a container, as described below.
Definition: astobj2.h:1693
struct ao2_container * events
Definition: calendar.h:140
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 551 of file res_calendar.c.

References AST_LIST_INSERT_HEAD, AST_LIST_LOCK, AST_LIST_TRAVERSE, and AST_LIST_UNLOCK.

552 {
553  struct ast_calendar_tech *iter;
554 
555  if (!calendar_config) {
556  ast_log(LOG_WARNING, "Calendar support disabled, not loading %s calendar module\n", tech->type);
557  return -1;
558  }
559 
561  AST_LIST_TRAVERSE(&techs, iter, list) {
562  if(!strcasecmp(tech->type, iter->type)) {
563  ast_log(LOG_WARNING, "Already have a handler for calendar type '%s'\n", tech->type);
565  return -1;
566  }
567  }
568  AST_LIST_INSERT_HEAD(&techs, tech, list);
569  tech->user = ast_module_user_add(NULL);
571 
572  ast_verb(2, "Registered calendar type '%s' (%s)\n", tech->type, tech->description);
573 
574  return load_tech_calendars(tech);
575 }
#define AST_LIST_LOCK(head)
Locks a list.
Definition: linkedlists.h:40
#define AST_LIST_UNLOCK(head)
Attempts to unlock a list.
Definition: linkedlists.h:140
#define AST_LIST_TRAVERSE(head, var, field)
Loops over (traverses) the entries in a list.
Definition: linkedlists.h:491
#define AST_LIST_INSERT_HEAD(head, elm, field)
Inserts a list entry at the head of a list.
Definition: linkedlists.h:711
Individual calendaring technology data.
Definition: calendar.h:71
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 323 of file res_calendar.c.

References ao2_ref.

Referenced by ast_calendar_event_alloc().

324 {
325  ao2_ref(event, -1);
326  return NULL;
327 }
#define ao2_ref(o, delta)
Reference/unreference an object and return the old refcount.
Definition: astobj2.h:459
void ast_calendar_unregister ( struct ast_calendar_tech tech)

Unregister a new calendar technology.

Parameters
techcalendar technology to unregister

Definition at line 589 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, OBJ_MULTIPLE, OBJ_NODATA, and OBJ_UNLINK.

590 {
591  struct ast_calendar_tech *iter;
592 
594  AST_LIST_TRAVERSE_SAFE_BEGIN(&techs, iter, list) {
595  if (iter != tech) {
596  continue;
597  }
598 
599  ao2_callback(calendars, OBJ_UNLINK | OBJ_NODATA | OBJ_MULTIPLE, match_caltech_cb, tech);
600 
602  ast_module_user_remove(iter->user);
603  ast_verb(2, "Unregistered calendar type '%s'\n", tech->type);
604  break;
605  }
608 
609 }
#define AST_LIST_LOCK(head)
Locks a list.
Definition: linkedlists.h:40
#define AST_LIST_UNLOCK(head)
Attempts to unlock a list.
Definition: linkedlists.h:140
#define ao2_callback(c, flags, cb_fn, arg)
ao2_callback() is a generic function that applies cb_fn() to all objects in a container, as described below.
Definition: astobj2.h:1693
#define AST_LIST_TRAVERSE_SAFE_END
Closes a safe loop traversal block.
Definition: linkedlists.h:615
#define AST_LIST_REMOVE_CURRENT(field)
Removes the current entry from a list during a traversal.
Definition: linkedlists.h:557
Individual calendaring technology data.
Definition: calendar.h:71
#define AST_LIST_TRAVERSE_SAFE_BEGIN(head, var, field)
Loops safely over (traverses) the entries in a list.
Definition: linkedlists.h:529