Asterisk - The Open Source Telephony Project  21.4.1
func_volume.c
Go to the documentation of this file.
1 /*
2  * Asterisk -- An open source telephony toolkit.
3  *
4  * Copyright (C) 2011, Digium, Inc.
5  *
6  * Joshua Colp <jcolp@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 Technology independent volume control
22  *
23  * \author Joshua Colp <jcolp@digium.com>
24  *
25  * \ingroup functions
26  *
27  */
28 
29 /*** MODULEINFO
30  <support_level>core</support_level>
31  ***/
32 
33 #include "asterisk.h"
34 
35 #include "asterisk/module.h"
36 #include "asterisk/channel.h"
37 #include "asterisk/pbx.h"
38 #include "asterisk/utils.h"
39 #include "asterisk/audiohook.h"
40 #include "asterisk/app.h"
41 
42 /*** DOCUMENTATION
43  <function name="VOLUME" language="en_US">
44  <synopsis>
45  Set or get the TX or RX volume of a channel.
46  </synopsis>
47  <syntax>
48  <parameter name="direction" required="true">
49  <para>Must be <literal>TX</literal> or <literal>RX</literal>.</para>
50  </parameter>
51  <parameter name="options">
52  <optionlist>
53  <option name="p">
54  <para>Enable DTMF volume control</para>
55  </option>
56  </optionlist>
57  </parameter>
58  </syntax>
59  <description>
60  <para>The VOLUME function can be used to increase or decrease the <literal>tx</literal> or
61  <literal>rx</literal> gain of any channel.</para>
62  <example title="Increase volume">
63  same => n,Set(VOLUME(TX)=3)
64  </example>
65  <example title="Increase volume">
66  same => n,Set(VOLUME(RX)=2)
67  </example>
68  <example title="Increase volume with DTMF control">
69  same => n,Set(VOLUME(TX,p)=3)
70  </example>
71  <example title="Increase RX volume with DTMF control">
72  same => n,Set(VOLUME(RX,p)=3)
73  </example>
74  <example title="Decrease RX volume">
75  same => n,Set(VOLUME(RX)=-4)
76  </example>
77  <example title="Reset to normal">
78  same => n,Set(VOLUME(RX)=0)
79  </example>
80  </description>
81  </function>
82  ***/
83 
85  struct ast_audiohook audiohook;
86  float tx_gain;
87  float rx_gain;
88  unsigned int flags;
89 };
90 
91 enum volume_flags {
92  VOLUMEFLAG_CHANGE = (1 << 1),
93 };
94 
95 AST_APP_OPTIONS(volume_opts, {
96  AST_APP_OPTION('p', VOLUMEFLAG_CHANGE),
97 });
98 
99 static void destroy_callback(void *data)
100 {
101  struct volume_information *vi = data;
102 
103  /* Destroy the audiohook, and destroy ourselves */
104  ast_audiohook_lock(&vi->audiohook);
105  ast_audiohook_detach(&vi->audiohook);
106  ast_audiohook_unlock(&vi->audiohook);
107  ast_audiohook_destroy(&vi->audiohook);
108  ast_free(vi);
109 
110  return;
111 }
112 
113 /*! \brief Static structure for datastore information */
114 static const struct ast_datastore_info volume_datastore = {
115  .type = "volume",
116  .destroy = destroy_callback
117 };
118 
119 static int volume_callback(struct ast_audiohook *audiohook, struct ast_channel *chan, struct ast_frame *frame, enum ast_audiohook_direction direction)
120 {
121  struct ast_datastore *datastore = NULL;
122  struct volume_information *vi = NULL;
123  float *gain = NULL;
124 
125  /* If the audiohook is stopping it means the channel is shutting down.... but we let the datastore destroy take care of it */
126  if (audiohook->status == AST_AUDIOHOOK_STATUS_DONE)
127  return 0;
128 
129  /* Grab datastore which contains our gain information */
130  if (!(datastore = ast_channel_datastore_find(chan, &volume_datastore, NULL)))
131  return 0;
132 
133  vi = datastore->data;
134 
135  /* If this is DTMF then allow them to increase/decrease the gains */
136  if (ast_test_flag(vi, VOLUMEFLAG_CHANGE)) {
137  if (frame->frametype == AST_FRAME_DTMF) {
138  /* Only use DTMF coming from the source... not going to it */
139  if (direction != AST_AUDIOHOOK_DIRECTION_READ)
140  return 0;
141  if (frame->subclass.integer == '*') {
142  vi->tx_gain += 1;
143  vi->rx_gain += 1;
144  } else if (frame->subclass.integer == '#') {
145  vi->tx_gain -= 1;
146  vi->rx_gain -= 1;
147  }
148  }
149  }
150 
151 
152  if (frame->frametype == AST_FRAME_VOICE) {
153  /* Based on direction of frame grab the gain, and confirm it is applicable */
154  if (!(gain = (direction == AST_AUDIOHOOK_DIRECTION_READ) ? &vi->rx_gain : &vi->tx_gain) || !*gain)
155  return 0;
156  /* Apply gain to frame... easy as pi */
157  ast_frame_adjust_volume_float(frame, *gain);
158  }
159 
160  return 0;
161 }
162 
163 static int volume_write(struct ast_channel *chan, const char *cmd, char *data, const char *value)
164 {
165  struct ast_datastore *datastore = NULL;
166  struct volume_information *vi = NULL;
167  int is_new = 0;
168 
169  /* Separate options from argument */
170 
172  AST_APP_ARG(direction);
173  AST_APP_ARG(options);
174  );
175 
176  if (!chan) {
177  ast_log(LOG_WARNING, "No channel was provided to %s function.\n", cmd);
178  return -1;
179  }
180 
181  AST_STANDARD_APP_ARGS(args, data);
182 
183  ast_channel_lock(chan);
184  if (!(datastore = ast_channel_datastore_find(chan, &volume_datastore, NULL))) {
185  ast_channel_unlock(chan);
186  /* Allocate a new datastore to hold the reference to this volume and audiohook information */
187  if (!(datastore = ast_datastore_alloc(&volume_datastore, NULL)))
188  return 0;
189  if (!(vi = ast_calloc(1, sizeof(*vi)))) {
190  ast_datastore_free(datastore);
191  return 0;
192  }
194  vi->audiohook.manipulate_callback = volume_callback;
195  ast_set_flag(&vi->audiohook, AST_AUDIOHOOK_WANTS_DTMF);
196  is_new = 1;
197  } else {
198  ast_channel_unlock(chan);
199  vi = datastore->data;
200  }
201 
202  /* Adjust gain on volume information structure */
203  if (ast_strlen_zero(args.direction)) {
204  ast_log(LOG_ERROR, "Direction must be specified for VOLUME function\n");
205  return -1;
206  }
207 
208  if (!strcasecmp(args.direction, "tx")) {
209  vi->tx_gain = atof(value);
210  } else if (!strcasecmp(args.direction, "rx")) {
211  vi->rx_gain = atof(value);
212  } else {
213  ast_log(LOG_ERROR, "Direction must be either RX or TX\n");
214  }
215 
216  if (is_new) {
217  datastore->data = vi;
218  ast_channel_lock(chan);
219  ast_channel_datastore_add(chan, datastore);
220  ast_channel_unlock(chan);
221  ast_audiohook_attach(chan, &vi->audiohook);
222  }
223 
224  /* Add Option data to struct */
225 
226  if (!ast_strlen_zero(args.options)) {
227  struct ast_flags flags = { 0 };
228  ast_app_parse_options(volume_opts, &flags, NULL, args.options);
229  vi->flags = flags.flags;
230  } else {
231  vi->flags = 0;
232  }
233 
234  return 0;
235 }
236 
237 static int volume_read(struct ast_channel *chan, const char *cmd, char *data, char *buffer, size_t buflen)
238 {
239  struct ast_datastore *datastore = NULL;
240  struct volume_information *vi = NULL;
241 
242  /* Separate options from argument */
243 
245  AST_APP_ARG(direction);
246  AST_APP_ARG(options);
247  );
248 
249  if (!chan) {
250  ast_log(LOG_WARNING, "No channel was provided to %s function.\n", cmd);
251  return -1;
252  }
253 
254  AST_STANDARD_APP_ARGS(args, data);
255 
256  ast_channel_lock(chan);
257  if (!(datastore = ast_channel_datastore_find(chan, &volume_datastore, NULL))) {
258  ast_channel_unlock(chan);
259  return -1; /* no active audiohook, nothing to read */
260  } else {
261  ast_channel_unlock(chan);
262  vi = datastore->data;
263  }
264 
265  /* Obtain current gain using volume information structure */
266  if (ast_strlen_zero(args.direction)) {
267  ast_log(LOG_ERROR, "Direction must be specified for VOLUME function\n");
268  return -1;
269  }
270 
271  if (!strcasecmp(args.direction, "tx")) {
272  snprintf(buffer, buflen, "%f", vi->tx_gain);
273  } else if (!strcasecmp(args.direction, "rx")) {
274  snprintf(buffer, buflen, "%f", vi->rx_gain);
275  } else {
276  ast_log(LOG_ERROR, "Direction must be either RX or TX\n");
277  }
278 
279  return 0;
280 }
281 
282 static struct ast_custom_function volume_function = {
283  .name = "VOLUME",
284  .write = volume_write,
285  .read = volume_read,
286 };
287 
288 static int unload_module(void)
289 {
290  return ast_custom_function_unregister(&volume_function);
291 }
292 
293 static int load_module(void)
294 {
295  return ast_custom_function_register(&volume_function);
296 }
297 
298 AST_MODULE_INFO_STANDARD(ASTERISK_GPL_KEY, "Technology independent volume control");
const char * name
Definition: pbx.h:119
const char * type
Definition: datastore.h:32
Main Channel structure associated with a channel.
Asterisk main include file. File version handling, generic pbx functions.
#define AST_STANDARD_APP_ARGS(args, parse)
Performs the 'standard' argument separation process for an application.
Audiohooks Architecture.
Structure for a data store type.
Definition: datastore.h:31
int ast_audiohook_attach(struct ast_channel *chan, struct ast_audiohook *audiohook)
Attach audiohook to channel.
Definition: audiohook.c:484
Structure for a data store object.
Definition: datastore.h:64
struct ast_datastore * ast_channel_datastore_find(struct ast_channel *chan, const struct ast_datastore_info *info, const char *uid)
Find a datastore on a channel.
Definition: channel.c:2399
int ast_audiohook_destroy(struct ast_audiohook *audiohook)
Destroys an audiohook structure.
Definition: audiohook.c:124
int ast_custom_function_unregister(struct ast_custom_function *acf)
Unregister a custom function.
int ast_datastore_free(struct ast_datastore *datastore)
Free a data store object.
Definition: datastore.c:68
struct ast_frame_subclass subclass
Utility functions.
int ast_frame_adjust_volume_float(struct ast_frame *f, float adjustment)
Adjusts the volume of the audio samples contained in a frame.
Definition: main/frame.c:812
#define AST_APP_OPTIONS(holder, options...)
Declares an array of options for an application.
ast_audiohook_manipulate_callback manipulate_callback
Definition: audiohook.h:118
int ast_audiohook_init(struct ast_audiohook *audiohook, enum ast_audiohook_type type, const char *source, enum ast_audiohook_init_flags flags)
Initialize an audiohook structure.
Definition: audiohook.c:100
#define ast_audiohook_unlock(ah)
Unlock an audiohook.
Definition: audiohook.h:318
static const struct ast_datastore_info volume_datastore
Static structure for datastore information.
Definition: func_volume.c:114
General Asterisk PBX channel definitions.
Data structure associated with a custom dialplan function.
Definition: pbx.h:118
int ast_app_parse_options(const struct ast_app_option *options, struct ast_flags *flags, char **args, char *optstr)
Parses a string containing application options and sets flags/arguments.
Definition: main/app.c:3066
Core PBX routines and definitions.
int ast_audiohook_detach(struct ast_audiohook *audiohook)
Detach audiohook from channel.
Definition: audiohook.c:550
static void destroy_callback(void *data)
Helper function used by datastores to destroy the speech structure upon hangup.
#define ast_calloc(num, len)
A wrapper for calloc()
Definition: astmm.h:202
Structure used to handle boolean flags.
Definition: utils.h:199
ast_audiohook_direction
Definition: audiohook.h:48
void * data
Definition: datastore.h:66
unsigned int flags
Definition: audiohook.h:111
Data structure associated with a single frame of data.
enum ast_audiohook_status status
Definition: audiohook.h:108
enum ast_frame_type frametype
#define AST_APP_OPTION(option, flagno)
Declares an application option that does not accept an argument.
#define ASTERISK_GPL_KEY
The text the key() function should return.
Definition: module.h:46
#define ast_audiohook_lock(ah)
Lock an audiohook.
Definition: audiohook.h:313
Asterisk module definitions.
int ast_channel_datastore_add(struct ast_channel *chan, struct ast_datastore *datastore)
Add a datastore to a channel.
Definition: channel.c:2385
#define AST_DECLARE_APP_ARGS(name, arglist)
Declare a structure to hold an application's arguments.
Application convenience functions, designed to give consistent look and feel to Asterisk apps...
#define ast_custom_function_register(acf)
Register a custom function.
Definition: pbx.h:1558
#define AST_APP_ARG(name)
Define an application argument.