framehook.h File Reference

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:

Go to the source code of this file.

Data Structures
struct	ast_framehook_interface

Macros
#define	AST_FRAMEHOOK_INTERFACE_VERSION   4

Typedefs
typedef void(*	ast_framehook_chan_fixup_callback) (void *data, int framehook_id, struct ast_channel *old_chan, struct ast_channel *new_chan)
	This callback is called when a masquerade occurs on a channel with a framehook. More...
typedef int(*	ast_framehook_consume_callback) (void *data, enum ast_frame_type type)
	This callback is called to determine if the framehook is currently consuming frames of a given type. More...
typedef void(*	ast_framehook_destroy_callback) (void *data)
	This callback is called immediately before the framehook is destroyed. More...
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. More...

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. More...
int	ast_framehook_detach (struct ast_channel *chan, int framehook_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...

Detailed Description

FrameHook Architecture.

Definition in file framehook.h.

Macro Definition Documentation

AST_FRAMEHOOK_INTERFACE_VERSION

#define AST_FRAMEHOOK_INTERFACE_VERSION   4

Definition at line 227 of file framehook.h.

Typedef Documentation

ast_framehook_chan_fixup_callback

typedef void(* ast_framehook_chan_fixup_callback) (void *data, int framehook_id, struct ast_channel *old_chan, struct ast_channel *new_chan)

This callback is called when a masquerade occurs on a channel with a framehook.

Since

12

Parameters

data	The data pointer provided at framehook initialization.
framehook_id	The framehook ID where the framehook lives now
old_chan	The channel that was masqueraded.
new_chan	The channel that the masqueraded channel became.

Definition at line 224 of file framehook.h.

ast_framehook_consume_callback

typedef int(* ast_framehook_consume_callback) (void *data, enum ast_frame_type type)

This callback is called to determine if the framehook is currently consuming frames of a given type.

Since

12

Parameters

data	The data pointer provided at framehook initialization.
type	The type of frame.

Returns

0 if frame type is being ignored

1 if frame type is not being ignored

Definition at line 213 of file framehook.h.

ast_framehook_destroy_callback

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.

ast_framehook_event_callback

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

chan	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 initialization.

Returns

the resulting frame.

Definition at line 1 of file framehook.h.

Enumeration Type Documentation

ast_framehook_event

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

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