Thu Sep 7 01:03:29 2017

Asterisk developer's documentation


framehook.c File Reference

FrameHooks Architecture. More...

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

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_frameast_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_frameast_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_frameframehook_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 94 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().

00095 {
00096    struct ast_framehook *framehook;
00097    struct ast_frame *frame;
00098    if (i->version != AST_FRAMEHOOK_INTERFACE_VERSION) {
00099       ast_log(LOG_ERROR, "Version '%hu' of framehook interface not what we compiled against (%hu)\n",
00100          i->version, AST_FRAMEHOOK_INTERFACE_VERSION);
00101       return -1;
00102    }
00103    if (!i->event_cb || !(framehook = ast_calloc(1, sizeof(*framehook)))) {
00104       return -1;
00105    }
00106    framehook->i = *i;
00107    framehook->chan = chan;
00108 
00109    /* create the framehook list if it didn't already exist */
00110    if (!chan->framehooks && !(chan->framehooks = ast_calloc(1, sizeof(*chan->framehooks)))) {
00111       ast_free(framehook);
00112       return -1;
00113    }
00114 
00115    framehook->id = ++chan->framehooks->id_count;
00116    AST_LIST_INSERT_TAIL(&chan->framehooks->list, framehook, list);
00117 
00118    /* Tell the event callback we're live and rocking */
00119    frame = framehook->i.event_cb(framehook->chan, NULL, AST_FRAMEHOOK_EVENT_ATTACHED, framehook->i.data);
00120 
00121    /* Never assume anything about this function. If you can return a frame during
00122     * the attached event, then assume someone will. */
00123    if (frame) {
00124       ast_frfree(frame);
00125    }
00126 
00127    return framehook->id;
00128 }

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

00131 {
00132    struct ast_framehook *framehook;
00133    int res = -1;
00134 
00135    if (!chan->framehooks) {
00136       return res;
00137    }
00138 
00139    AST_LIST_TRAVERSE_SAFE_BEGIN(&chan->framehooks->list, framehook, list) {
00140       if (framehook->id == id) {
00141          /* we mark for detachment rather than doing explicitly here because
00142           * it needs to be safe for this function to be called within the
00143           * event callback.  If we allowed the hook to actually be destroyed
00144           * immediately here, the event callback would crash on exit. */
00145          framehook->detach_and_destroy_me = 1;
00146          res = 0;
00147          break;
00148       }
00149    }
00150    AST_LIST_TRAVERSE_SAFE_END;
00151 
00152    return res;
00153 }

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

00156 {
00157    struct ast_framehook *framehook;
00158 
00159    if (!chan->framehooks) {
00160       return 0;
00161    }
00162    AST_LIST_TRAVERSE_SAFE_BEGIN(&chan->framehooks->list, framehook, list) {
00163       AST_LIST_REMOVE_CURRENT(list);
00164       framehook_detach_and_destroy(framehook);
00165    }
00166    AST_LIST_TRAVERSE_SAFE_END;
00167    ast_free(chan->framehooks);
00168    chan->framehooks = NULL;
00169    return 0;
00170 }

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

00173 {
00174    if (!framehooks) {
00175       return 1;
00176    }
00177    return AST_LIST_EMPTY(&framehooks->list) ? 1 : 0;
00178 }

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

References AST_FRAMEHOOK_EVENT_READ, and framehook_list_push_event().

Referenced by __ast_read().

00186 {
00187    return framehook_list_push_event(framehooks, frame, AST_FRAMEHOOK_EVENT_READ);
00188 }

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

References AST_FRAMEHOOK_EVENT_WRITE, and framehook_list_push_event().

Referenced by ast_indicate_data(), and ast_write().

00181 {
00182    return framehook_list_push_event(framehooks, frame, AST_FRAMEHOOK_EVENT_WRITE);
00183 }

static void framehook_detach_and_destroy ( struct ast_framehook framehook  )  [static]

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

00057 {
00058    struct ast_frame *frame;
00059    frame = framehook->i.event_cb(framehook->chan, NULL, AST_FRAMEHOOK_EVENT_DETACHED, framehook->i.data);
00060    /* never assume anything about this function. If you can return a frame during
00061     * the detached event, then assume someone will. */
00062    if (frame) {
00063       ast_frfree(frame);
00064    }
00065    framehook->chan = NULL;
00066 
00067    if (framehook->i.destroy_cb) {
00068       framehook->i.destroy_cb(framehook->i.data);
00069    }
00070    ast_free(framehook);
00071 }

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

00074 {
00075    struct ast_framehook *framehook;
00076 
00077    if (!framehooks) {
00078       return frame;
00079    }
00080 
00081    AST_LIST_TRAVERSE_SAFE_BEGIN(&framehooks->list, framehook, list) {
00082       if (framehook->detach_and_destroy_me) {
00083          /* this guy is signaled for destruction */
00084          AST_LIST_REMOVE_CURRENT(list);
00085          framehook_detach_and_destroy(framehook);
00086       } else {
00087          frame = framehook->i.event_cb(framehook->chan, frame, event, framehook->i.data);
00088       }
00089    }
00090    AST_LIST_TRAVERSE_SAFE_END;
00091    return frame;
00092 }


Generated on 7 Sep 2017 for Asterisk - The Open Source Telephony Project by  doxygen 1.6.1