FrameHooks Architecture. More...

#include "asterisk.h"
#include "asterisk/channel.h"
#include "asterisk/linkedlists.h"
#include "asterisk/framehook.h"
#include "asterisk/frame.h"

Include dependency graph for framehook.c:

Go to the source code of this file.

Data Structures
struct	ast_framehook
struct	ast_framehook_list
Functions
int	ast_framehook_attach (struct ast_channel chan, struct ast_framehook_interface i)
	Attach an framehook onto a channel for frame interception.
int	ast_framehook_detach (struct ast_channel *chan, int id)
	Detach an framehook from a channel.
int	ast_framehook_list_destroy (struct ast_channel *chan)
	This is used by the channel API to detach and destroy all framehooks on a channel during channel destruction.
int	ast_framehook_list_is_empty (struct ast_framehook_list *framehooks)
	Determine if an framehook list is empty or not.
struct ast_frame *	ast_framehook_list_read_event (struct ast_framehook_list framehooks, struct ast_frame frame)
	This is used by the channel API push a frame read event to a channel's framehook list.
struct ast_frame *	ast_framehook_list_write_event (struct ast_framehook_list framehooks, struct ast_frame frame)
	This is used by the channel API push a frame write event to a channel's framehook list.
static void	framehook_detach_and_destroy (struct ast_framehook *framehook)
static struct ast_frame *	framehook_list_push_event (struct ast_framehook_list framehooks, struct ast_frame frame, enum ast_framehook_event event)

Detailed Description

FrameHooks Architecture.

Author:: David Vossel <dvossel@digium.com>

Definition in file framehook.c.

Function Documentation

int ast_framehook_attach	(	struct ast_channel *	chan,
		struct ast_framehook_interface *	i
	)

Attach an framehook onto a channel for frame interception.

Since:: 1.8

Parameters:

ast_channel,The	channel to attach the hook on to.
framehook	interface, The framehook's callback functions and stored data.

Precondition:: XXX The Channel must be locked during this function all.

Note:: The data pointer is never touched by the framehook API except to provide it during the event and destruction callbacks. It is entirely up to the application using this API to manage the memory associated with the data pointer.

Return values:

On	success, positive id representing this hook on the channel
On	failure, -1

Definition at line 90 of file framehook.c.

References ast_calloc, AST_FRAMEHOOK_EVENT_ATTACHED, AST_FRAMEHOOK_INTERFACE_VERSION, ast_free, ast_frfree, AST_LIST_INSERT_TAIL, ast_log(), ast_framehook::chan, ast_framehook_interface::data, ast_framehook_interface::event_cb, ast_channel::framehooks, ast_framehook::i, ast_framehook::id, ast_framehook_list::id_count, ast_framehook_list::list, LOG_ERROR, and ast_framehook_interface::version.

Referenced by frame_trace_helper().

{
   struct ast_framehook *framehook;
   struct ast_frame *frame;
   if (i->version != AST_FRAMEHOOK_INTERFACE_VERSION) {
      ast_log(LOG_ERROR, "Version '%hu' of framehook interface not what we compiled against (%hu)\n",
         i->version, AST_FRAMEHOOK_INTERFACE_VERSION);
      return -1;
   }
   if (!i->event_cb || !(framehook = ast_calloc(1, sizeof(*framehook)))) {
      return -1;
   }
   framehook->i = *i;
   framehook->chan = chan;

   /* create the framehook list if it didn't already exist */
   if (!chan->framehooks && !(chan->framehooks = ast_calloc(1, sizeof(*chan->framehooks)))) {
      ast_free(framehook);
      return -1;
   }

   framehook->id = ++chan->framehooks->id_count;
   AST_LIST_INSERT_TAIL(&chan->framehooks->list, framehook, list);

   /* Tell the event callback we're live and rocking */
   frame = framehook->i.event_cb(framehook->chan, NULL, AST_FRAMEHOOK_EVENT_ATTACHED, framehook->i.data);

   /* Never assume anything about this function. If you can return a frame during
    * the attached event, then assume someone will. */
   if (frame) {
      ast_frfree(frame);
   }

   return framehook->id;
}

int ast_framehook_detach	(	struct ast_channel *	chan,
		int	framehook_id
	)

Detach an framehook from a channel.

Since:: 1.8

Precondition:: XXX The Channel must be locked during this function all. If this function is never called after attaching an framehook, the framehook will be detached and destroyed during channel destruction.

Parameters:

The	channel the framehook is attached to
The	framehook's id

Return values:

0	success
-1	framehook did not exist on the channel. This means the framehook either never existed on the channel, or was already detached.

Definition at line 126 of file framehook.c.

References AST_LIST_TRAVERSE_SAFE_BEGIN, AST_LIST_TRAVERSE_SAFE_END, ast_framehook::detach_and_destroy_me, ast_channel::framehooks, ast_framehook::id, and ast_framehook_list::list.

Referenced by frame_trace_helper().

{
   struct ast_framehook *framehook;
   int res = -1;

   if (!chan->framehooks) {
      return res;
   }

   AST_LIST_TRAVERSE_SAFE_BEGIN(&chan->framehooks->list, framehook, list) {
      if (framehook->id == id) {
         /* we mark for detachment rather than doing explicitly here because
          * it needs to be safe for this function to be called within the
          * event callback.  If we allowed the hook to actually be destroyed
          * immediately here, the event callback would crash on exit. */
         framehook->detach_and_destroy_me = 1;
         res = 0;
         break;
      }
   }
   AST_LIST_TRAVERSE_SAFE_END;

   return res;
}

int ast_framehook_list_destroy ( struct ast_channel * chan )

This is used by the channel API to detach and destroy all framehooks on a channel during channel destruction.

Since:: 1.8

Precondition:: XXX The Channel must be locked during this function all.

Parameters:

channel containing the framehook list to destroy.

Return values:

0	success
-1	failure

Definition at line 151 of file framehook.c.

References ast_free, AST_LIST_REMOVE_CURRENT, AST_LIST_TRAVERSE_SAFE_BEGIN, AST_LIST_TRAVERSE_SAFE_END, framehook_detach_and_destroy(), ast_channel::framehooks, and ast_framehook_list::list.

Referenced by ast_hangup().

{
   struct ast_framehook *framehook;

   if (!chan->framehooks) {
      return 0;
   }
   AST_LIST_TRAVERSE_SAFE_BEGIN(&chan->framehooks->list, framehook, list) {
      AST_LIST_REMOVE_CURRENT(list);
      framehook_detach_and_destroy(framehook);
   }
   AST_LIST_TRAVERSE_SAFE_END;
   ast_free(chan->framehooks);
   chan->framehooks = NULL;
   return 0;
}

int ast_framehook_list_is_empty ( struct ast_framehook_list * framehooks )

Determine if an framehook list is empty or not.

Since:: 1.8

Precondition:: XXX The Channel must be locked during this function all.

Parameters:

the	framehook list

Return values:

0,not	empty
1,is	empty

Definition at line 168 of file framehook.c.

References AST_LIST_EMPTY, and ast_framehook_list::list.

Referenced by ast_channel_bridge(), ast_indicate_data(), local_bridge_loop(), and remote_bridge_loop().

{
   if (!framehooks) {
      return 1;
   }
   return AST_LIST_EMPTY(&framehooks->list) ? 1 : 0;
}

struct ast_frame* ast_framehook_list_read_event	(	struct ast_framehook_list *	framehooks,
		struct ast_frame *	frame
	)		`[read]`

This is used by the channel API push a frame read event to a channel's framehook list.

Since:: 1.8

After this function completes, the resulting frame that is returned could be anything, even NULL. There is nothing to keep up with after this function. If the frame is modified, the framehook callback is in charge of any memory management associated with that modification.

Precondition:: XXX The Channel must be locked during this function all.

Parameters:

framehook	list to push event to.
frame	being pushed to the framehook list.

Returns:: The resulting frame after being viewed and modified by the framehook callbacks.

Definition at line 181 of file framehook.c.

References AST_FRAMEHOOK_EVENT_READ, and framehook_list_push_event().

Referenced by __ast_read().

{
   return framehook_list_push_event(framehooks, frame, AST_FRAMEHOOK_EVENT_READ);
}

struct ast_frame* ast_framehook_list_write_event	(	struct ast_framehook_list *	framehooks,
		struct ast_frame *	frame
	)		`[read]`

This is used by the channel API push a frame write event to a channel's framehook list.

Since:: 1.8

After this function completes, the resulting frame that is returned could be anything, even NULL. There is nothing to keep up with after this function. If the frame is modified, the framehook callback is in charge of any memory management associated with that modification.

Precondition:: XXX The Channel must be locked during this function all.

Parameters:

framehook	list to push event to.
frame	being pushed to the framehook list.

Returns:: The resulting frame after being viewed and modified by the framehook callbacks.

Definition at line 176 of file framehook.c.

References AST_FRAMEHOOK_EVENT_WRITE, and framehook_list_push_event().

Referenced by ast_indicate_data(), and ast_write().

{
   return framehook_list_push_event(framehooks, frame, AST_FRAMEHOOK_EVENT_WRITE);
}

static void framehook_detach_and_destroy ( struct ast_framehook * framehook ) [static]

Definition at line 52 of file framehook.c.

References AST_FRAMEHOOK_EVENT_DETACHED, ast_free, and ast_frfree.

Referenced by ast_framehook_list_destroy(), and framehook_list_push_event().

{
   struct ast_frame *frame;
   frame = framehook->i.event_cb(framehook->chan, NULL, AST_FRAMEHOOK_EVENT_DETACHED, framehook->i.data);
   /* never assume anything about this function. If you can return a frame during
    * the detached event, then assume someone will. */
   if (frame) {
      ast_frfree(frame);
   }
   framehook->chan = NULL;

   if (framehook->i.destroy_cb) {
      framehook->i.destroy_cb(framehook->i.data);
   }
   ast_free(framehook);
}

static struct ast_frame* framehook_list_push_event	(	struct ast_framehook_list *	framehooks,
		struct ast_frame *	frame,
		enum ast_framehook_event	event
	)		`[static, read]`

Definition at line 69 of file framehook.c.

References AST_LIST_REMOVE_CURRENT, AST_LIST_TRAVERSE_SAFE_BEGIN, AST_LIST_TRAVERSE_SAFE_END, ast_framehook::chan, ast_framehook_interface::data, ast_framehook::detach_and_destroy_me, ast_framehook_interface::event_cb, framehook_detach_and_destroy(), ast_framehook::i, and ast_framehook_list::list.

Referenced by ast_framehook_list_read_event(), and ast_framehook_list_write_event().

{
   struct ast_framehook *framehook;

   if (!framehooks) {
      return frame;
   }

   AST_LIST_TRAVERSE_SAFE_BEGIN(&framehooks->list, framehook, list) {
      if (framehook->detach_and_destroy_me) {
         /* this guy is signaled for destruction */
         AST_LIST_REMOVE_CURRENT(list);
         framehook_detach_and_destroy(framehook);
      } else {
         frame = framehook->i.event_cb(framehook->chan, frame, event, framehook->i.data);
      }
   }
   AST_LIST_TRAVERSE_SAFE_END;
   return frame;
}

Asterisk developer's documentation

Data Structures

Functions

Detailed Description

Function Documentation