Asterisk - The Open Source Telephony Project  GIT-master-a1fa8df
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  <para>For example:</para>
63  <para>Set(VOLUME(TX)=3)</para>
64  <para>Set(VOLUME(RX)=2)</para>
65  <para>Set(VOLUME(TX,p)=3)</para>
66  <para>Set(VOLUME(RX,p)=3)</para>
67  </description>
68  </function>
69  ***/
70 
73  float tx_gain;
74  float rx_gain;
75  unsigned int flags;
76 };
77 
79  VOLUMEFLAG_CHANGE = (1 << 1),
80 };
81 
84 });
85 
86 static void destroy_callback(void *data)
87 {
88  struct volume_information *vi = data;
89 
90  /* Destroy the audiohook, and destroy ourselves */
95  ast_free(vi);
96 
97  return;
98 }
99 
100 /*! \brief Static structure for datastore information */
101 static const struct ast_datastore_info volume_datastore = {
102  .type = "volume",
103  .destroy = destroy_callback
104 };
105 
106 static int volume_callback(struct ast_audiohook *audiohook, struct ast_channel *chan, struct ast_frame *frame, enum ast_audiohook_direction direction)
107 {
108  struct ast_datastore *datastore = NULL;
109  struct volume_information *vi = NULL;
110  float *gain = NULL;
111 
112  /* If the audiohook is stopping it means the channel is shutting down.... but we let the datastore destroy take care of it */
113  if (audiohook->status == AST_AUDIOHOOK_STATUS_DONE)
114  return 0;
115 
116  /* Grab datastore which contains our gain information */
117  if (!(datastore = ast_channel_datastore_find(chan, &volume_datastore, NULL)))
118  return 0;
119 
120  vi = datastore->data;
121 
122  /* If this is DTMF then allow them to increase/decrease the gains */
123  if (ast_test_flag(vi, VOLUMEFLAG_CHANGE)) {
124  if (frame->frametype == AST_FRAME_DTMF) {
125  /* Only use DTMF coming from the source... not going to it */
126  if (direction != AST_AUDIOHOOK_DIRECTION_READ)
127  return 0;
128  if (frame->subclass.integer == '*') {
129  vi->tx_gain += 1;
130  vi->rx_gain += 1;
131  } else if (frame->subclass.integer == '#') {
132  vi->tx_gain -= 1;
133  vi->rx_gain -= 1;
134  }
135  }
136  }
137 
138 
139  if (frame->frametype == AST_FRAME_VOICE) {
140  /* Based on direction of frame grab the gain, and confirm it is applicable */
141  if (!(gain = (direction == AST_AUDIOHOOK_DIRECTION_READ) ? &vi->rx_gain : &vi->tx_gain) || !*gain)
142  return 0;
143  /* Apply gain to frame... easy as pi */
144  ast_frame_adjust_volume_float(frame, *gain);
145  }
146 
147  return 0;
148 }
149 
150 static int volume_write(struct ast_channel *chan, const char *cmd, char *data, const char *value)
151 {
152  struct ast_datastore *datastore = NULL;
153  struct volume_information *vi = NULL;
154  int is_new = 0;
155 
156  /* Separate options from argument */
157 
161  );
162 
163  if (!chan) {
164  ast_log(LOG_WARNING, "No channel was provided to %s function.\n", cmd);
165  return -1;
166  }
167 
169 
170  ast_channel_lock(chan);
171  if (!(datastore = ast_channel_datastore_find(chan, &volume_datastore, NULL))) {
172  ast_channel_unlock(chan);
173  /* Allocate a new datastore to hold the reference to this volume and audiohook information */
174  if (!(datastore = ast_datastore_alloc(&volume_datastore, NULL)))
175  return 0;
176  if (!(vi = ast_calloc(1, sizeof(*vi)))) {
177  ast_datastore_free(datastore);
178  return 0;
179  }
183  is_new = 1;
184  } else {
185  ast_channel_unlock(chan);
186  vi = datastore->data;
187  }
188 
189  /* Adjust gain on volume information structure */
190  if (ast_strlen_zero(args.direction)) {
191  ast_log(LOG_ERROR, "Direction must be specified for VOLUME function\n");
192  return -1;
193  }
194 
195  if (!strcasecmp(args.direction, "tx")) {
196  vi->tx_gain = atof(value);
197  } else if (!strcasecmp(args.direction, "rx")) {
198  vi->rx_gain = atof(value);
199  } else {
200  ast_log(LOG_ERROR, "Direction must be either RX or TX\n");
201  }
202 
203  if (is_new) {
204  datastore->data = vi;
205  ast_channel_lock(chan);
206  ast_channel_datastore_add(chan, datastore);
207  ast_channel_unlock(chan);
208  ast_audiohook_attach(chan, &vi->audiohook);
209  }
210 
211  /* Add Option data to struct */
212 
213  if (!ast_strlen_zero(args.options)) {
214  struct ast_flags flags = { 0 };
215  ast_app_parse_options(volume_opts, &flags, NULL, args.options);
216  vi->flags = flags.flags;
217  } else {
218  vi->flags = 0;
219  }
220 
221  return 0;
222 }
223 
224 static int volume_read(struct ast_channel *chan, const char *cmd, char *data, char *buffer, size_t buflen)
225 {
226  struct ast_datastore *datastore = NULL;
227  struct volume_information *vi = NULL;
228 
229  /* Separate options from argument */
230 
234  );
235 
236  if (!chan) {
237  ast_log(LOG_WARNING, "No channel was provided to %s function.\n", cmd);
238  return -1;
239  }
240 
242 
243  ast_channel_lock(chan);
244  if (!(datastore = ast_channel_datastore_find(chan, &volume_datastore, NULL))) {
245  ast_channel_unlock(chan);
246  return -1; /* no active audiohook, nothing to read */
247  } else {
248  ast_channel_unlock(chan);
249  vi = datastore->data;
250  }
251 
252  /* Obtain current gain using volume information structure */
253  if (ast_strlen_zero(args.direction)) {
254  ast_log(LOG_ERROR, "Direction must be specified for VOLUME function\n");
255  return -1;
256  }
257 
258  if (!strcasecmp(args.direction, "tx")) {
259  snprintf(buffer, buflen, "%f", vi->tx_gain);
260  } else if (!strcasecmp(args.direction, "rx")) {
261  snprintf(buffer, buflen, "%f", vi->rx_gain);
262  } else {
263  ast_log(LOG_ERROR, "Direction must be either RX or TX\n");
264  }
265 
266  return 0;
267 }
268 
270  .name = "VOLUME",
271  .write = volume_write,
272  .read = volume_read,
273 };
274 
275 static int unload_module(void)
276 {
277  return ast_custom_function_unregister(&volume_function);
278 }
279 
280 static int load_module(void)
281 {
282  return ast_custom_function_register(&volume_function);
283 }
284 
285 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
static struct ast_custom_function volume_function
Definition: func_volume.c:269
#define ast_channel_lock(chan)
Definition: channel.h:2913
Main Channel structure associated with a channel.
#define AST_MODULE_INFO_STANDARD(keystr, desc)
Definition: module.h:567
Asterisk main include file. File version handling, generic pbx functions.
static const struct ast_app_option volume_opts[128]
Definition: func_volume.c:84
#define ast_test_flag(p, flag)
Definition: utils.h:63
#define ast_set_flag(p, flag)
Definition: utils.h:70
#define AST_STANDARD_APP_ARGS(args, parse)
Performs the &#39;standard&#39; argument separation process for an application.
#define LOG_WARNING
Definition: logger.h:274
Audiohooks Architecture.
unsigned int flags
Definition: utils.h:200
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:501
static void destroy_callback(void *data)
Definition: func_volume.c:86
unsigned int flags
Definition: func_volume.c:75
Structure for a data store object.
Definition: datastore.h:68
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:2400
const char * args
#define NULL
Definition: resample.c:96
int value
Definition: syslog.c:37
#define AST_FRAME_DTMF
int ast_audiohook_destroy(struct ast_audiohook *audiohook)
Destroys an audiohook structure.
Definition: audiohook.c:133
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:117
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:108
#define ast_audiohook_unlock(ah)
Unlock an audiohook.
Definition: audiohook.h:300
#define ast_log
Definition: astobj2.c:42
static const struct ast_datastore_info volume_datastore
Static structure for datastore information.
Definition: func_volume.c:101
General Asterisk PBX channel definitions.
volume_flags
Definition: func_volume.c:78
static force_inline int attribute_pure ast_strlen_zero(const char *s)
Definition: strings.h:65
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:2846
Core PBX routines and definitions.
int ast_audiohook_detach(struct ast_audiohook *audiohook)
Detach audiohook from channel.
Definition: audiohook.c:579
#define LOG_ERROR
Definition: logger.h:285
static int load_module(void)
Definition: func_volume.c:280
#define ast_channel_unlock(chan)
Definition: channel.h:2914
static int unload_module(void)
Definition: func_volume.c:275
#define ast_free(a)
Definition: astmm.h:182
#define ast_calloc(num, len)
A wrapper for calloc()
Definition: astmm.h:204
static int volume_read(struct ast_channel *chan, const char *cmd, char *data, char *buffer, size_t buflen)
Definition: func_volume.c:224
Structure used to handle boolean flags.
Definition: utils.h:199
ast_audiohook_direction
Definition: audiohook.h:48
static int volume_write(struct ast_channel *chan, const char *cmd, char *data, const char *value)
Definition: func_volume.c:150
void * data
Definition: datastore.h:70
struct ast_audiohook audiohook
Definition: func_volume.c:72
static int volume_callback(struct ast_audiohook *audiohook, struct ast_channel *chan, struct ast_frame *frame, enum ast_audiohook_direction direction)
Definition: func_volume.c:106
Data structure associated with a single frame of data.
enum ast_audiohook_status status
Definition: audiohook.h:107
#define ast_datastore_alloc(info, uid)
Definition: datastore.h:89
enum ast_frame_type frametype
static struct test_options options
#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
direction
#define ast_audiohook_lock(ah)
Lock an audiohook.
Definition: audiohook.h:295
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:2386
#define AST_DECLARE_APP_ARGS(name, arglist)
Declare a structure to hold an application&#39;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:1508
#define AST_APP_ARG(name)
Define an application argument.