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"

Include dependency graph for framehook.c:

Go to the source code of this file.

Data Structures
struct	ast_framehook
struct	ast_framehook_list

Enumerations
enum	framehook_detachment_mode { FRAMEHOOK_DETACH_DESTROY = 0 , FRAMEHOOK_DETACH_PRESERVE }

Functions
int	ast_framehook_attach (struct ast_channel *chan, struct ast_framehook_interface *i)
	Attach an framehook onto a channel for frame interception. More...
int	ast_framehook_detach (struct ast_channel *chan, int id)
	Detach an framehook from a channel. More...
int	ast_framehook_list_contains_no_active (struct ast_framehook_list *framehooks)
	Determine if a framehook list is free of active framehooks or not. More...
int	ast_framehook_list_contains_no_active_of_type (struct ast_framehook_list *framehooks, enum ast_frame_type type)
	Determine if a framehook list is free of active framehooks consuming a specific type of frame. More...
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. More...
void	ast_framehook_list_fixup (struct ast_channel *old_chan, struct ast_channel *new_chan)
	This is used by the channel API during a masquerade operation to move all mobile framehooks from the original channel to the clone channel. More...
int	ast_framehook_list_is_empty (struct ast_framehook_list *framehooks)
	Determine if an framehook list is empty or not. More...
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. More...
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. More...
static void	framehook_detach (struct ast_framehook *framehook, enum framehook_detachment_mode mode)
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 dvoss.nosp@m.el@d.nosp@m.igium.nosp@m..com

Definition in file framehook.c.

Enumeration Type Documentation

framehook_detachment_mode

enum framehook_detachment_mode

Enumerator
FRAMEHOOK_DETACH_DESTROY	Destroy the framehook outright.
FRAMEHOOK_DETACH_PRESERVE	Remove the framehook from the channel, but don't destroy the data since it will be used by a replacement framehook on another channel.

Definition at line 57 of file framehook.c.

{
    /*! Destroy the framehook outright. */
    FRAMEHOOK_DETACH_DESTROY = 0,
    /*! Remove the framehook from the channel, but don't destroy the data since
     *  it will be used by a replacement framehook on another channel. */
    FRAMEHOOK_DETACH_PRESERVE,
};

Function Documentation

ast_framehook_attach()

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

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

Precondition

The Channel must be locked during this function call.

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

non-negative	success, id representing this hook on the channel
-1	failure

Definition at line 132 of file framehook.c.

{
    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 (%i)\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);
    }
 
    ast_channel_framehooks(chan)->count++;
    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);
    }
 
    if (ast_channel_is_bridged(chan)) {
        ast_channel_set_unbridged_nolock(chan, 1);
    }
 
    return framehook->id;
}

References ast_calloc, ast_channel_framehooks(), ast_channel_framehooks_set(), ast_channel_is_bridged(), ast_channel_set_unbridged_nolock(), AST_FRAMEHOOK_EVENT_ATTACHED, AST_FRAMEHOOK_INTERFACE_VERSION, ast_free, ast_frfree, AST_LIST_INSERT_TAIL, ast_log, ast_framehook::chan, ast_framehook_list::count, ast_framehook_interface::data, ast_framehook_interface::event_cb, ast_framehook::i, ast_framehook::id, ast_framehook_list::id_count, LOG_ERROR, NULL, and ast_framehook_interface::version.

Referenced by aoc_attach_framehook(), ast_channel_suppress(), ast_framehook_list_fixup(), ast_jb_create_framehook(), attach_framehook(), dtmfstore_exec(), fax_detect_attach(), fax_gateway_attach(), frame_drop_helper(), frame_trace_helper(), handle_remb_set(), native_rtp_bridge_framehook_attach(), refer_blind_callback(), set_hold_intercept(), and t38_attach_framehook().

ast_framehook_detach()

int ast_framehook_detach	(	struct ast_channel *	chan,
		int	framehook_id
	)

Detach an framehook from a channel.

Since

1.8

Precondition

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

Parameters

chan	The channel the framehook is attached to
framehook_id	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 177 of file framehook.c.

{
    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;
 
    if (!res && ast_channel_is_bridged(chan)) {
        ast_channel_set_unbridged_nolock(chan, 1);
    }
 
    return res;
}

References ast_channel_framehooks(), ast_channel_is_bridged(), ast_channel_set_unbridged_nolock(), AST_LIST_TRAVERSE_SAFE_BEGIN, AST_LIST_TRAVERSE_SAFE_END, ast_framehook::chan, ast_framehook::detach_and_destroy_me, ast_framehook::id, and ast_framehook::list.

Referenced by acf_faxopt_write(), ast_channel_suppress(), ast_channel_unsuppress(), ast_framehook_list_fixup(), ast_jb_create_framehook(), fax_detect_framehook(), fax_gateway_detect_t38(), fax_gateway_framehook(), fax_gateway_request_t38(), fixup_callback(), frame_drop_helper(), frame_trace_helper(), handle_remb_set(), native_rtp_bridge_framehook_detach(), refer_blind_callback(), refer_progress_bridge(), refer_progress_framehook(), remove_dtmf_store(), remove_framehook(), remove_hold_intercept(), t38_attach_framehook(), t38_masq(), and transfer_target_framehook_cb().

ast_framehook_list_contains_no_active()

int ast_framehook_list_contains_no_active

(

struct ast_framehook_list *

framehooks

)

Determine if a framehook list is free of active framehooks or not.

Since

12.0.0

Precondition

The channel must be locked during this function call.

Parameters

framehooks

the framehook list

Return values

0	not empty
1	is empty (aside from dying framehooks)

Note

This function is very similar to ast_framehook_list_is_empty, but it checks individual framehooks to see if they have been marked for destruction and doesn't count them if they are.

Definition at line 282 of file framehook.c.

{
    return ast_framehook_list_contains_no_active_of_type(framehooks, 0);
}

References ast_framehook_list_contains_no_active_of_type().

Referenced by ast_channel_has_audio_frame_or_monitor().

ast_framehook_list_contains_no_active_of_type()

int ast_framehook_list_contains_no_active_of_type	(	struct ast_framehook_list *	framehooks,
		enum ast_frame_type	type
	)

Determine if a framehook list is free of active framehooks consuming a specific type of frame.

Since

12.3.0

Precondition

The channel must be locked during this function call.

Parameters

framehooks	the framehook list
type	type of frame

Return values

0	not empty
1	is empty (aside from dying framehooks)

Note

This function is very similar to ast_framehook_list_is_empty, but it checks individual framehooks to see if they have been marked for destruction and doesn't count them if they are.

Definition at line 287 of file framehook.c.

{
    struct ast_framehook *cur;
 
    if (!framehooks) {
        return 1;
    }
 
    if (AST_LIST_EMPTY(&framehooks->list)) {
        return 1;
    }
 
    AST_LIST_TRAVERSE(&framehooks->list, cur, list) {
        if (cur->detach_and_destroy_me) {
            continue;
        }
        if (type && cur->i.consume_cb && !cur->i.consume_cb(cur->i.data, type)) {
            continue;
        }
        return 0;
    }
 
    return 1;
}

References AST_LIST_EMPTY, AST_LIST_TRAVERSE, ast_framehook_interface::consume_cb, ast_framehook_interface::data, ast_framehook::detach_and_destroy_me, ast_framehook::i, ast_framehook::list, ast_framehook_list::list, and type.

Referenced by ast_channel_has_hook_requiring_audio(), and ast_framehook_list_contains_no_active().

ast_framehook_list_destroy()

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

The Channel must be locked during this function call.

Parameters

chan	channel containing the framehook list to destroy.

Return values

0	success
-1	failure

Definition at line 206 of file framehook.c.

{
    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(framehook, FRAMEHOOK_DETACH_DESTROY);
    }
    AST_LIST_TRAVERSE_SAFE_END;
    ast_free(ast_channel_framehooks(chan));
    ast_channel_framehooks_set(chan, NULL);
    return 0;
}

References ast_channel_framehooks(), ast_channel_framehooks_set(), ast_free, AST_LIST_REMOVE_CURRENT, AST_LIST_TRAVERSE_SAFE_BEGIN, AST_LIST_TRAVERSE_SAFE_END, ast_framehook::chan, framehook_detach(), FRAMEHOOK_DETACH_DESTROY, ast_framehook::list, and NULL.

Referenced by destroy_hooks().

ast_framehook_list_fixup()

void ast_framehook_list_fixup	(	struct ast_channel *	old_chan,
		struct ast_channel *	new_chan
	)

This is used by the channel API during a masquerade operation to move all mobile framehooks from the original channel to the clone channel.

Since

12.5.0

Precondition

Both channels must be locked prior to this function call.

Parameters

old_chan	The channel being cloned from
new_chan	The channel being cloned to

Definition at line 223 of file framehook.c.

{
    struct ast_framehook *framehook;
    int moved_framehook_id;
 
    if (ast_channel_framehooks(new_chan)) {
        AST_LIST_TRAVERSE_SAFE_BEGIN(&ast_channel_framehooks(new_chan)->list, framehook, list) {
            if (framehook->i.disable_inheritance) {
                ast_framehook_detach(new_chan, framehook->id);
                continue;
            }
 
            if (framehook->i.chan_breakdown_cb) {
                framehook->i.chan_breakdown_cb(framehook->i.data, framehook->id,
                    old_chan, new_chan);
            }
        }
        AST_LIST_TRAVERSE_SAFE_END;
    }
 
    if (!ast_channel_framehooks(old_chan)) {
        return;
    }
 
    if (!AST_LIST_EMPTY(&ast_channel_framehooks(old_chan)->list)
        && ast_channel_is_bridged(old_chan)) {
        ast_channel_set_unbridged_nolock(old_chan, 1);
    }
    while ((framehook = AST_LIST_REMOVE_HEAD(&ast_channel_framehooks(old_chan)->list, list))) {
        /* If inheritance is not allowed for this framehook, just destroy it. */
        if (framehook->i.disable_inheritance) {
            framehook_detach(framehook, FRAMEHOOK_DETACH_DESTROY);
            continue;
        }
 
        /* Otherwise move it to the other channel and perform any fixups set by the framehook interface */
        moved_framehook_id = ast_framehook_attach(new_chan, &framehook->i);
        if (moved_framehook_id < 0) {
            ast_log(LOG_WARNING, "Failed framehook copy during masquerade. Expect loss of features.\n");
            framehook_detach(framehook, FRAMEHOOK_DETACH_DESTROY);
        } else {
            if (framehook->i.chan_fixup_cb) {
                framehook->i.chan_fixup_cb(framehook->i.data, moved_framehook_id,
                    old_chan, new_chan);
            }
 
            framehook_detach(framehook, FRAMEHOOK_DETACH_PRESERVE);
        }
    }
}

References ast_channel_framehooks(), ast_channel_is_bridged(), ast_channel_set_unbridged_nolock(), ast_framehook_attach(), ast_framehook_detach(), AST_LIST_EMPTY, AST_LIST_REMOVE_HEAD, AST_LIST_TRAVERSE_SAFE_BEGIN, AST_LIST_TRAVERSE_SAFE_END, ast_log, ast_framehook_interface::chan_breakdown_cb, ast_framehook_interface::chan_fixup_cb, ast_framehook_interface::data, ast_framehook_interface::disable_inheritance, framehook_detach(), FRAMEHOOK_DETACH_DESTROY, FRAMEHOOK_DETACH_PRESERVE, ast_framehook::i, ast_framehook::id, ast_framehook::list, and LOG_WARNING.

Referenced by channel_do_masquerade().

ast_framehook_list_is_empty()

int ast_framehook_list_is_empty

(

struct ast_framehook_list *

framehooks

)

Determine if an framehook list is empty or not.

Since

1.8

Precondition

The Channel must be locked during this function call.

Parameters

framehooks

the framehook list

Return values

0	not empty
1	is empty

Definition at line 274 of file framehook.c.

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

References AST_LIST_EMPTY, and ast_framehook_list::list.

Referenced by ast_indicate_data().

ast_framehook_list_read_event()

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.

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

The Channel must be locked during this function call.

Parameters

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

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

References AST_FRAMEHOOK_EVENT_READ, and framehook_list_push_event().

Referenced by __ast_read().

ast_framehook_list_write_event()

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.

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

The Channel must be locked during this function call.

Parameters

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

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

References AST_FRAMEHOOK_EVENT_WRITE, and framehook_list_push_event().

Referenced by ast_indicate_data(), and ast_write_stream().

framehook_detach()

static void framehook_detach ( struct ast_framehook *  framehook, enum framehook_detachment_mode  mode  )

static

Definition at line 66 of file framehook.c.

{
    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 (mode == FRAMEHOOK_DETACH_DESTROY && framehook->i.destroy_cb) {
        framehook->i.destroy_cb(framehook->i.data);
    }
    ast_free(framehook);
}

References AST_FRAMEHOOK_EVENT_DETACHED, ast_free, ast_frfree, ast_framehook::chan, ast_framehook_interface::data, ast_framehook_interface::destroy_cb, ast_framehook_interface::event_cb, FRAMEHOOK_DETACH_DESTROY, ast_framehook::i, and NULL.

Referenced by ast_framehook_list_destroy(), ast_framehook_list_fixup(), and framehook_list_push_event().

framehook_list_push_event()

static struct ast_frame * framehook_list_push_event ( struct ast_framehook_list *  framehooks, struct ast_frame *  frame, enum ast_framehook_event  event  )

static

Definition at line 83 of file framehook.c.

{
    struct ast_framehook *framehook;
    struct ast_frame *original_frame;
    int *skip;
    size_t skip_size;
 
    if (!framehooks) {
        return frame;
    }
 
    skip_size = sizeof(int) * framehooks->count;
    skip = ast_alloca(skip_size);
    memset(skip, 0, skip_size);
 
    do {
        unsigned int num = 0;
        original_frame = 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(framehook, FRAMEHOOK_DETACH_DESTROY);
                continue;
            }
 
            /* If this framehook has been marked as needing to be skipped, do so */
            if (skip[num]) {
                num++;
                continue;
            }
 
            frame = framehook->i.event_cb(framehook->chan, frame, event, framehook->i.data);
 
            if (frame != original_frame) {
                /* To prevent looping we skip any framehooks that have already provided a modified frame */
                skip[num] = 1;
                break;
            }
 
            num++;
        }
        AST_LIST_TRAVERSE_SAFE_END;
    } while (frame != original_frame);
 
    return frame;
}

References ast_alloca, AST_LIST_REMOVE_CURRENT, AST_LIST_TRAVERSE_SAFE_BEGIN, AST_LIST_TRAVERSE_SAFE_END, ast_framehook::chan, ast_framehook_list::count, ast_framehook_interface::data, ast_framehook::detach_and_destroy_me, ast_framehook_interface::event_cb, framehook_detach(), FRAMEHOOK_DETACH_DESTROY, ast_framehook::i, and ast_framehook_list::list.

Referenced by ast_framehook_list_read_event(), and ast_framehook_list_write_event().