Wed Jan 8 2020 09:49:47

Asterisk developer's documentation


framehook.c
Go to the documentation of this file.
1 /*
2  * Asterisk -- An open source telephony toolkit.
3  *
4  * Copyright (C) 2010, Digium, Inc.
5  *
6  * David Vossel <dvossel@digium.com>
7  *
8  * See http://www.asterisk.org for more information about
9  * the Asterisk project. Please do not directly contact
10  * any of the maintainers of this project for assistance;
11  * the project provides a web site, mailing lists and IRC
12  * channels for your use.
13  *
14  * This program is free software, distributed under the terms of
15  * the GNU General Public License Version 2. See the LICENSE file
16  * at the top of the source tree.
17  */
18 
19 /*! \file
20  *
21  * \brief FrameHooks Architecture
22  *
23  * \author David Vossel <dvossel@digium.com>
24  */
25 
26 /*** MODULEINFO
27  <support_level>core</support_level>
28  ***/
29 
30 #include "asterisk.h"
31 
32 ASTERISK_FILE_VERSION(__FILE__, "$Revision: 369001 $")
33 
34 #include "asterisk/channel.h"
35 #include "asterisk/linkedlists.h"
36 #include "asterisk/framehook.h"
37 #include "asterisk/frame.h"
38 
39 struct ast_framehook {
41  /*! This pointer to ast_channel the framehook is attached to. */
42  struct ast_channel *chan;
43  /*! the id representing this framehook on a channel */
44  unsigned int id;
45  /*! when set, this signals the read and write function to detach the hook */
47  /*! list entry for ast_framehook_list object */
49 };
50 
52  unsigned int id_count;
54 };
55 
56 static void framehook_detach_and_destroy(struct ast_framehook *framehook)
57 {
58  struct ast_frame *frame;
59  frame = framehook->i.event_cb(framehook->chan, NULL, AST_FRAMEHOOK_EVENT_DETACHED, framehook->i.data);
60  /* never assume anything about this function. If you can return a frame during
61  * the detached event, then assume someone will. */
62  if (frame) {
63  ast_frfree(frame);
64  }
65  framehook->chan = NULL;
66 
67  if (framehook->i.destroy_cb) {
68  framehook->i.destroy_cb(framehook->i.data);
69  }
70  ast_free(framehook);
71 }
72 
73 static struct ast_frame *framehook_list_push_event(struct ast_framehook_list *framehooks, struct ast_frame *frame, enum ast_framehook_event event)
74 {
75  struct ast_framehook *framehook;
76 
77  if (!framehooks) {
78  return frame;
79  }
80 
81  AST_LIST_TRAVERSE_SAFE_BEGIN(&framehooks->list, framehook, list) {
82  if (framehook->detach_and_destroy_me) {
83  /* this guy is signaled for destruction */
86  } else {
87  frame = framehook->i.event_cb(framehook->chan, frame, event, framehook->i.data);
88  }
89  }
91  return frame;
92 }
93 
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 }
129 
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 }
154 
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 }
171 
172 int ast_framehook_list_is_empty(struct ast_framehook_list *framehooks)
173 {
174  if (!framehooks) {
175  return 1;
176  }
177  return AST_LIST_EMPTY(&framehooks->list) ? 1 : 0;
178 }
179 
180 struct ast_frame *ast_framehook_list_write_event(struct ast_framehook_list *framehooks, struct ast_frame *frame)
181 {
182  return framehook_list_push_event(framehooks, frame, AST_FRAMEHOOK_EVENT_WRITE);
183 }
184 
185 struct ast_frame *ast_framehook_list_read_event(struct ast_framehook_list *framehooks, struct ast_frame *frame)
186 {
187  return framehook_list_push_event(framehooks, frame, AST_FRAMEHOOK_EVENT_READ);
188 }
ast_framehook_event_callback event_cb
Definition: framehook.h:208
Main Channel structure associated with a channel.
Definition: channel.h:742
Asterisk main include file. File version handling, generic pbx functions.
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
int ast_framehook_list_is_empty(struct ast_framehook_list *framehooks)
Determine if an framehook list is empty or not.
Definition: framehook.c:172
ast_framehook_event
These are the types of events that the framehook&#39;s event callback can receive.
Definition: framehook.h:151
int ast_framehook_detach(struct ast_channel *chan, int framehook_id)
Detach an framehook from a channel.
Definition: framehook.c:130
#define AST_LIST_EMPTY(head)
Checks whether the specified list contains any entries.
Definition: linkedlists.h:449
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 dest...
Definition: framehook.c:155
#define AST_LIST_TRAVERSE_SAFE_END
Closes a safe loop traversal block.
Definition: linkedlists.h:600
int ast_framehook_attach(struct ast_channel *chan, struct ast_framehook_interface *i)
Attach an framehook onto a channel for frame interception.
Definition: framehook.c:94
struct ast_framehook::@272 list
Asterisk internal frame definitions.
#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
A set of macros to manage forward-linked lists.
unsigned int id_count
Definition: framehook.c:52
#define AST_LIST_HEAD_NOLOCK(name, type)
Defines a structure to be used to hold a list of specified type (with no lock).
Definition: linkedlists.h:224
#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
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&#39;s framehook list...
Definition: framehook.c:180
#define AST_LIST_ENTRY(type)
Declare a forward link structure inside a list entry.
Definition: linkedlists.h:409
#define ast_free(a)
Definition: astmm.h:97
struct ast_framehook_interface i
Definition: framehook.c:40
unsigned int id
Definition: framehook.c:44
FrameHook Architecture.
#define ast_calloc(a, b)
Definition: astmm.h:82
Data structure associated with a single frame of data.
Definition: frame.h:142
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
#define ast_frfree(fr)
Definition: frame.h:583
struct ast_channel * chan
Definition: framehook.c:42
static void framehook_detach_and_destroy(struct ast_framehook *framehook)
Definition: framehook.c:56
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&#39;s framehook list.
Definition: framehook.c:185
#define ASTERISK_FILE_VERSION(file, version)
Register/unregister a source code file with the core.
Definition: asterisk.h:180