Add support for a realtime sorcery module.
[asterisk/asterisk.git] / main / framehook.c
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$")
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 {
40         struct ast_framehook_interface i;
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 */
46         int detach_and_destroy_me;
47         /*! list entry for ast_framehook_list object */
48         AST_LIST_ENTRY(ast_framehook) list;
49 };
50
51 struct ast_framehook_list {
52         unsigned int id_count;
53         AST_LIST_HEAD_NOLOCK(, ast_framehook) list;
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 */
84                         AST_LIST_REMOVE_CURRENT(list);
85                         framehook_detach_and_destroy(framehook);
86                 } else {
87                         frame = framehook->i.event_cb(framehook->chan, frame, event, framehook->i.data);
88                 }
89         }
90         AST_LIST_TRAVERSE_SAFE_END;
91         return frame;
92 }
93
94 int ast_framehook_attach(struct ast_channel *chan, struct ast_framehook_interface *i)
95 {
96         struct ast_framehook *framehook;
97         struct ast_framehook_list *fh_list;
98         struct ast_frame *frame;
99         if (i->version != AST_FRAMEHOOK_INTERFACE_VERSION) {
100                 ast_log(LOG_ERROR, "Version '%hu' of framehook interface not what we compiled against (%hu)\n",
101                         i->version, AST_FRAMEHOOK_INTERFACE_VERSION);
102                 return -1;
103         }
104         if (!i->event_cb || !(framehook = ast_calloc(1, sizeof(*framehook)))) {
105                 return -1;
106         }
107         framehook->i = *i;
108         framehook->chan = chan;
109
110         /* create the framehook list if it didn't already exist */
111         if (!ast_channel_framehooks(chan)) {
112                 if (!(fh_list = ast_calloc(1, sizeof(*ast_channel_framehooks(chan))))) {
113                         ast_free(framehook);
114                         return -1;
115                 }
116                 ast_channel_framehooks_set(chan, fh_list);
117         }
118
119         framehook->id = ++ast_channel_framehooks(chan)->id_count;
120         AST_LIST_INSERT_TAIL(&ast_channel_framehooks(chan)->list, framehook, list);
121
122         /* Tell the event callback we're live and rocking */
123         frame = framehook->i.event_cb(framehook->chan, NULL, AST_FRAMEHOOK_EVENT_ATTACHED, framehook->i.data);
124
125         /* Never assume anything about this function. If you can return a frame during
126          * the attached event, then assume someone will. */
127         if (frame) {
128                 ast_frfree(frame);
129         }
130
131         return framehook->id;
132 }
133
134 int ast_framehook_detach(struct ast_channel *chan, int id)
135 {
136         struct ast_framehook *framehook;
137         int res = -1;
138
139         if (!ast_channel_framehooks(chan)) {
140                 return res;
141         }
142
143         AST_LIST_TRAVERSE_SAFE_BEGIN(&ast_channel_framehooks(chan)->list, framehook, list) {
144                 if (framehook->id == id) {
145                         /* we mark for detachment rather than doing explicitly here because
146                          * it needs to be safe for this function to be called within the
147                          * event callback.  If we allowed the hook to actually be destroyed
148                          * immediately here, the event callback would crash on exit. */
149                         framehook->detach_and_destroy_me = 1;
150                         res = 0;
151                         break;
152                 }
153         }
154         AST_LIST_TRAVERSE_SAFE_END;
155
156         return res;
157 }
158
159 int ast_framehook_list_destroy(struct ast_channel *chan)
160 {
161         struct ast_framehook *framehook;
162
163         if (!ast_channel_framehooks(chan)) {
164                 return 0;
165         }
166         AST_LIST_TRAVERSE_SAFE_BEGIN(&ast_channel_framehooks(chan)->list, framehook, list) {
167                 AST_LIST_REMOVE_CURRENT(list);
168                 framehook_detach_and_destroy(framehook);
169         }
170         AST_LIST_TRAVERSE_SAFE_END;
171         ast_free(ast_channel_framehooks(chan));
172         ast_channel_framehooks_set(chan, NULL);
173         return 0;
174 }
175
176 int ast_framehook_list_is_empty(struct ast_framehook_list *framehooks)
177 {
178         if (!framehooks) {
179                 return 1;
180         }
181         return AST_LIST_EMPTY(&framehooks->list) ? 1 : 0;
182 }
183
184 struct ast_frame *ast_framehook_list_write_event(struct ast_framehook_list *framehooks, struct ast_frame *frame)
185 {
186         return framehook_list_push_event(framehooks, frame, AST_FRAMEHOOK_EVENT_WRITE);
187 }
188
189 struct ast_frame *ast_framehook_list_read_event(struct ast_framehook_list *framehooks, struct ast_frame *frame)
190 {
191         return framehook_list_push_event(framehooks, frame, AST_FRAMEHOOK_EVENT_READ);
192 }