FrameHook Architecture. More...

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

Include dependency graph for framehook.h:

This graph shows which files directly or indirectly include this file:

Data Structures
struct	ast_framehook_interface
Defines
#define	AST_FRAMEHOOK_INTERFACE_VERSION 1
Typedefs
typedef void(*	ast_framehook_destroy_callback )(void *data)
	This callback is called immediately before the framehook is destroyed.
typedef struct ast_frame (	ast_framehook_event_callback )(struct ast_channel chan, struct ast_frame frame, enum ast_framehook_event event, void *data)
	This callback is called every time an event occurs on the framehook.
Enumerations
enum	ast_framehook_event { AST_FRAMEHOOK_EVENT_READ, AST_FRAMEHOOK_EVENT_WRITE, AST_FRAMEHOOK_EVENT_ATTACHED, AST_FRAMEHOOK_EVENT_DETACHED }
	These are the types of events that the framehook's event callback can receive. More...
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 framehook_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.

Detailed Description

FrameHook Architecture.

Definition in file framehook.h.

Define Documentation

#define AST_FRAMEHOOK_INTERFACE_VERSION 1

Definition at line 202 of file framehook.h.

Referenced by ast_framehook_attach(), fax_detect_attach(), fax_gateway_attach(), frame_trace_helper(), and jb_helper().

Typedef Documentation

typedef void(* ast_framehook_destroy_callback)(void *data)

This callback is called immediately before the framehook is destroyed.

Since:: 1.8

Note:: This function should be used to clean up any pointers pointing to the framehook structure as the framehook will be freed immediately afterwards.

Parameters:

data,The data pointer provided at framehook initialization. This is a good place to clean up any state data allocated for the framehook stored in this pointer.

Definition at line 200 of file framehook.h.

typedef struct ast_frame*(* ast_framehook_event_callback)(struct ast_channel *chan, struct ast_frame *frame, enum ast_framehook_event event, void *data)

This callback is called every time an event occurs on the framehook.

Since:: 1.8

Two events are guaranteed to occur once the ast_framehook_attach() function is called. These events are AST_FRAMEHOOK_EVENT_ATTACHED, which occurs immediately after the framehook is attached to a channel, and AST_FRAMEHOOK_EVENT_DETACHED, which occurs right after the framehook is detached.

It is completely valid for the frame variable to be set to NULL. Always do a NULL check on the frame before attempted to access it. When the frame variable is present, it is safe to view and manipulate that frame in any way possible. It is even safe to return a completely different frame, but when that occurs this function is in charge of freeing the previous frame.

The ast_channel will always be locked during this callback. Never attempt to unlock the channel for any reason.

Parameters:

channel,The	ast_channel this framehook is attached to
frame,The	ast_frame being intercepted for viewing and manipulation
event,The	type of event which is occurring
data,The	data pointer provided at framehook initilization.

Return values:

the	resulting frame.

Definition at line 184 of file framehook.h.

Enumeration Type Documentation

enum ast_framehook_event

These are the types of events that the framehook's event callback can receive.

Since:: 1.8

Enumerator:

AST_FRAMEHOOK_EVENT_READ	frame is intercepted in the read direction on the channel.
AST_FRAMEHOOK_EVENT_WRITE	frame is intercepted on the write direction on the channel.
AST_FRAMEHOOK_EVENT_ATTACHED	framehook is attached and running on the channel, the first message sent to event_cb.
AST_FRAMEHOOK_EVENT_DETACHED	framehook is detached from the channel, last message sent to event_cb.

Definition at line 151 of file framehook.h.

                         {
   AST_FRAMEHOOK_EVENT_READ, /*!< frame is intercepted in the read direction on the channel. */
   AST_FRAMEHOOK_EVENT_WRITE, /*!< frame is intercepted on the write direction on the channel. */
   AST_FRAMEHOOK_EVENT_ATTACHED, /*!< framehook is attached and running on the channel, the first message sent to event_cb. */
   AST_FRAMEHOOK_EVENT_DETACHED /*!< framehook is detached from the channel, last message sent to event_cb. */
};

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 94 of file framehook.c.

References ast_calloc, ast_channel_framehooks(), ast_channel_framehooks_set(), 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_framehook::i, ast_framehook::id, ast_framehook_list::id_count, LOG_ERROR, and ast_framehook_interface::version.

Referenced by fax_detect_attach(), fax_gateway_attach(), frame_trace_helper(), and jb_helper().

{
   struct ast_framehook *framehook;
   struct ast_framehook_list *fh_list;
   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 (!ast_channel_framehooks(chan)) {
      if (!(fh_list = ast_calloc(1, sizeof(*ast_channel_framehooks(chan))))) {
         ast_free(framehook);
         return -1;
      }
      ast_channel_framehooks_set(chan, fh_list);
   }

   framehook->id = ++ast_channel_framehooks(chan)->id_count;
   AST_LIST_INSERT_TAIL(&ast_channel_framehooks(chan)->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 134 of file framehook.c.

References ast_channel_framehooks(), AST_LIST_TRAVERSE_SAFE_BEGIN, AST_LIST_TRAVERSE_SAFE_END, ast_framehook::detach_and_destroy_me, and ast_framehook::id.

Referenced by acf_faxopt_write(), fax_detect_framehook(), fax_gateway_detect_t38(), fax_gateway_framehook(), fax_gateway_request_t38(), frame_trace_helper(), and jb_helper().

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

   if (!ast_channel_framehooks(chan)) {
      return res;
   }

   AST_LIST_TRAVERSE_SAFE_BEGIN(&ast_channel_framehooks(chan)->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 159 of file framehook.c.

References ast_channel_framehooks(), ast_channel_framehooks_set(), ast_free, AST_LIST_REMOVE_CURRENT, AST_LIST_TRAVERSE_SAFE_BEGIN, AST_LIST_TRAVERSE_SAFE_END, and framehook_detach_and_destroy().

Referenced by destroy_hooks().

{
   struct ast_framehook *framehook;

   if (!ast_channel_framehooks(chan)) {
      return 0;
   }
   AST_LIST_TRAVERSE_SAFE_BEGIN(&ast_channel_framehooks(chan)->list, framehook, list) {
      AST_LIST_REMOVE_CURRENT(list);
      framehook_detach_and_destroy(framehook);
   }
   AST_LIST_TRAVERSE_SAFE_END;
   ast_free(ast_channel_framehooks(chan));
   ast_channel_framehooks_set(chan, 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 176 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 189 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 184 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);
}

Asterisk developer's documentation

Data Structures

Defines

Typedefs

Enumerations

Functions

Detailed Description

Define Documentation

Typedef Documentation

Enumeration Type Documentation

Function Documentation