Wed Jan 8 2020 09:50:12

Asterisk developer's documentation


framehook.h File Reference

FrameHook Architecture. More...

Go to the source code of this file.

Data Structures

struct  ast_framehook_interface
 

Macros

#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. 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_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...
 
int ast_framehook_list_is_empty (struct ast_framehook_list *framehooks)
 Determine if an framehook list is empty or not. More...
 
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. More...
 
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. More...
 

Detailed Description

FrameHook Architecture.

Definition in file framehook.h.

Macro Definition Documentation

#define AST_FRAMEHOOK_INTERFACE_VERSION   1

Definition at line 202 of file framehook.h.

Referenced by ast_framehook_attach(), and frame_trace_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,Thedata 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,Theast_channel this framehook is attached to
frame,Theast_frame being intercepted for viewing and manipulation
event,Thetype of event which is occurring
data,Thedata pointer provided at framehook initilization.
Return values
theresulting frame.

Definition at line 184 of file framehook.h.

Enumeration Type Documentation

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.

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

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,Thechannel to attach the hook on to.
framehookinterface, 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
Onsuccess, positive id representing this hook on the channel
Onfailure, -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().

95 {
96  struct ast_framehook *framehook;
97  struct ast_frame *frame;
99  ast_log(LOG_ERROR, "Version '%hu' of framehook interface not what we compiled against (%hu)\n",
101  return -1;
102  }
103  if (!i->event_cb || !(framehook = ast_calloc(1, sizeof(*framehook)))) {
104  return -1;
105  }
106  framehook->i = *i;
107  framehook->chan = chan;
108 
109  /* create the framehook list if it didn't already exist */
110  if (!chan->framehooks && !(chan->framehooks = ast_calloc(1, sizeof(*chan->framehooks)))) {
111  ast_free(framehook);
112  return -1;
113  }
114 
115  framehook->id = ++chan->framehooks->id_count;
116  AST_LIST_INSERT_TAIL(&chan->framehooks->list, framehook, list);
117 
118  /* Tell the event callback we're live and rocking */
119  frame = framehook->i.event_cb(framehook->chan, NULL, AST_FRAMEHOOK_EVENT_ATTACHED, framehook->i.data);
120 
121  /* Never assume anything about this function. If you can return a frame during
122  * the attached event, then assume someone will. */
123  if (frame) {
124  ast_frfree(frame);
125  }
126 
127  return framehook->id;
128 }
ast_framehook_event_callback event_cb
Definition: framehook.h:208
struct ast_framehook_list::@273 list
unsigned int id_count
Definition: framehook.c:52
#define LOG_ERROR
Definition: logger.h:155
#define AST_LIST_INSERT_TAIL(head, elm, field)
Appends a list entry to the tail of a list.
Definition: linkedlists.h:716
#define AST_FRAMEHOOK_INTERFACE_VERSION
Definition: framehook.h:202
struct ast_framehook_list * framehooks
Definition: channel.h:765
void ast_log(int level, const char *file, int line, const char *function, const char *fmt,...)
Used for sending a log message This is the standard logger function. Probably the only way you will i...
Definition: logger.c:1207
#define ast_free(a)
Definition: astmm.h:97
struct ast_framehook_interface i
Definition: framehook.c:40
unsigned int id
Definition: framehook.c:44
#define ast_calloc(a, b)
Definition: astmm.h:82
Data structure associated with a single frame of data.
Definition: frame.h:142
#define ast_frfree(fr)
Definition: frame.h:583
struct ast_channel * chan
Definition: framehook.c:42
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
Thechannel the framehook is attached to
Theframehook's id
Return values
0success
-1framehook 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().

131 {
132  struct ast_framehook *framehook;
133  int res = -1;
134 
135  if (!chan->framehooks) {
136  return res;
137  }
138 
139  AST_LIST_TRAVERSE_SAFE_BEGIN(&chan->framehooks->list, framehook, list) {
140  if (framehook->id == id) {
141  /* we mark for detachment rather than doing explicitly here because
142  * it needs to be safe for this function to be called within the
143  * event callback. If we allowed the hook to actually be destroyed
144  * immediately here, the event callback would crash on exit. */
145  framehook->detach_and_destroy_me = 1;
146  res = 0;
147  break;
148  }
149  }
151 
152  return res;
153 }
#define AST_LIST_TRAVERSE_SAFE_END
Closes a safe loop traversal block.
Definition: linkedlists.h:600
struct ast_framehook::@272 list
struct ast_framehook_list::@273 list
struct ast_framehook_list * framehooks
Definition: channel.h:765
unsigned int id
Definition: framehook.c:44
int detach_and_destroy_me
Definition: framehook.c:46
#define AST_LIST_TRAVERSE_SAFE_BEGIN(head, var, field)
Loops safely over (traverses) the entries in a list.
Definition: linkedlists.h:528
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
channelcontaining the framehook list to destroy.
Return values
0success
-1failure

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

156 {
157  struct ast_framehook *framehook;
158 
159  if (!chan->framehooks) {
160  return 0;
161  }
162  AST_LIST_TRAVERSE_SAFE_BEGIN(&chan->framehooks->list, framehook, list) {
164  framehook_detach_and_destroy(framehook);
165  }
167  ast_free(chan->framehooks);
168  chan->framehooks = NULL;
169  return 0;
170 }
#define AST_LIST_TRAVERSE_SAFE_END
Closes a safe loop traversal block.
Definition: linkedlists.h:600
struct ast_framehook::@272 list
#define AST_LIST_REMOVE_CURRENT(field)
Removes the current entry from a list during a traversal.
Definition: linkedlists.h:554
struct ast_framehook_list::@273 list
struct ast_framehook_list * framehooks
Definition: channel.h:765
#define ast_free(a)
Definition: astmm.h:97
#define AST_LIST_TRAVERSE_SAFE_BEGIN(head, var, field)
Loops safely over (traverses) the entries in a list.
Definition: linkedlists.h:528
static void framehook_detach_and_destroy(struct ast_framehook *framehook)
Definition: framehook.c:56
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
theframehook list
Return values
0,notempty
1,isempty

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

173 {
174  if (!framehooks) {
175  return 1;
176  }
177  return AST_LIST_EMPTY(&framehooks->list) ? 1 : 0;
178 }
#define AST_LIST_EMPTY(head)
Checks whether the specified list contains any entries.
Definition: linkedlists.h:449
struct ast_framehook_list::@273 list
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
XXX The Channel must be locked during this function all.
Parameters
framehooklist to push event to.
framebeing 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().

186 {
187  return framehook_list_push_event(framehooks, frame, AST_FRAMEHOOK_EVENT_READ);
188 }
static struct ast_frame * framehook_list_push_event(struct ast_framehook_list *framehooks, struct ast_frame *frame, enum ast_framehook_event event)
Definition: framehook.c:73
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
XXX The Channel must be locked during this function all.
Parameters
framehooklist to push event to.
framebeing 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().

181 {
182  return framehook_list_push_event(framehooks, frame, AST_FRAMEHOOK_EVENT_WRITE);
183 }
static struct ast_frame * framehook_list_push_event(struct ast_framehook_list *framehooks, struct ast_frame *frame, enum ast_framehook_event event)
Definition: framehook.c:73