Wed Jan 8 2020 09:49:48

Asterisk developer's documentation


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 ASTERISK_FILE_VERSION(__FILE__, "$Revision: 411313 $")
36 
37 #include "asterisk/module.h"
38 #include "asterisk/channel.h"
39 #include "asterisk/pbx.h"
40 #include "asterisk/utils.h"
41 #include "asterisk/audiohook.h"
42 #include "asterisk/app.h"
43 
44 /*** DOCUMENTATION
45  <function name="VOLUME" language="en_US">
46  <synopsis>
47  Set the TX or RX volume of a channel.
48  </synopsis>
49  <syntax>
50  <parameter name="direction" required="true">
51  <para>Must be <literal>TX</literal> or <literal>RX</literal>.</para>
52  </parameter>
53  <parameter name="options">
54  <optionlist>
55  <option name="p">
56  <para>Enable DTMF volume control</para>
57  </option>
58  </optionlist>
59  </parameter>
60  </syntax>
61  <description>
62  <para>The VOLUME function can be used to increase or decrease the <literal>tx</literal> or
63  <literal>rx</literal> gain of any channel.</para>
64  <para>For example:</para>
65  <para>Set(VOLUME(TX)=3)</para>
66  <para>Set(VOLUME(RX)=2)</para>
67  <para>Set(VOLUME(TX,p)=3)</para>
68  <para>Set(VOLUME(RX,p)=3)</para>
69  </description>
70  </function>
71  ***/
72 
75  int tx_gain;
76  int rx_gain;
77  unsigned int flags;
78 };
79 
81  VOLUMEFLAG_CHANGE = (1 << 1),
82 };
83 
86 });
87 
88 static void destroy_callback(void *data)
89 {
90  struct volume_information *vi = data;
91 
92  /* Destroy the audiohook, and destroy ourselves */
97  ast_free(vi);
98 
99  return;
100 }
101 
102 /*! \brief Static structure for datastore information */
103 static const struct ast_datastore_info volume_datastore = {
104  .type = "volume",
105  .destroy = destroy_callback
106 };
107 
108 static int volume_callback(struct ast_audiohook *audiohook, struct ast_channel *chan, struct ast_frame *frame, enum ast_audiohook_direction direction)
109 {
110  struct ast_datastore *datastore = NULL;
111  struct volume_information *vi = NULL;
112  int *gain = NULL;
113 
114  /* If the audiohook is stopping it means the channel is shutting down.... but we let the datastore destroy take care of it */
115  if (audiohook->status == AST_AUDIOHOOK_STATUS_DONE)
116  return 0;
117 
118  /* Grab datastore which contains our gain information */
119  if (!(datastore = ast_channel_datastore_find(chan, &volume_datastore, NULL)))
120  return 0;
121 
122  vi = datastore->data;
123 
124  /* If this is DTMF then allow them to increase/decrease the gains */
125  if (ast_test_flag(vi, VOLUMEFLAG_CHANGE)) {
126  if (frame->frametype == AST_FRAME_DTMF) {
127  /* Only use DTMF coming from the source... not going to it */
128  if (direction != AST_AUDIOHOOK_DIRECTION_READ)
129  return 0;
130  if (frame->subclass.integer == '*') {
131  vi->tx_gain += 1;
132  vi->rx_gain += 1;
133  } else if (frame->subclass.integer == '#') {
134  vi->tx_gain -= 1;
135  vi->rx_gain -= 1;
136  }
137  }
138  }
139 
140 
141  if (frame->frametype == AST_FRAME_VOICE) {
142  /* Based on direction of frame grab the gain, and confirm it is applicable */
143  if (!(gain = (direction == AST_AUDIOHOOK_DIRECTION_READ) ? &vi->rx_gain : &vi->tx_gain) || !*gain)
144  return 0;
145  /* Apply gain to frame... easy as pi */
146  ast_frame_adjust_volume(frame, *gain);
147  }
148 
149  return 0;
150 }
151 
152 static int volume_write(struct ast_channel *chan, const char *cmd, char *data, const char *value)
153 {
154  struct ast_datastore *datastore = NULL;
155  struct volume_information *vi = NULL;
156  int is_new = 0;
157 
158  /* Separate options from argument */
159 
161  AST_APP_ARG(direction);
162  AST_APP_ARG(options);
163  );
164 
165  if (!chan) {
166  ast_log(LOG_WARNING, "No channel was provided to %s function.\n", cmd);
167  return -1;
168  }
169 
171 
172  ast_channel_lock(chan);
173  if (!(datastore = ast_channel_datastore_find(chan, &volume_datastore, NULL))) {
174  ast_channel_unlock(chan);
175  /* Allocate a new datastore to hold the reference to this volume and audiohook information */
176  if (!(datastore = ast_datastore_alloc(&volume_datastore, NULL)))
177  return 0;
178  if (!(vi = ast_calloc(1, sizeof(*vi)))) {
179  ast_datastore_free(datastore);
180  return 0;
181  }
185  is_new = 1;
186  } else {
187  ast_channel_unlock(chan);
188  vi = datastore->data;
189  }
190 
191  /* Adjust gain on volume information structure */
192  if (ast_strlen_zero(args.direction)) {
193  ast_log(LOG_ERROR, "Direction must be specified for VOLUME function\n");
194  return -1;
195  }
196 
197  if (!strcasecmp(args.direction, "tx")) {
198  vi->tx_gain = atoi(value);
199  } else if (!strcasecmp(args.direction, "rx")) {
200  vi->rx_gain = atoi(value);
201  } else {
202  ast_log(LOG_ERROR, "Direction must be either RX or TX\n");
203  }
204 
205  if (is_new) {
206  datastore->data = vi;
207  ast_channel_lock(chan);
208  ast_channel_datastore_add(chan, datastore);
209  ast_channel_unlock(chan);
210  ast_audiohook_attach(chan, &vi->audiohook);
211  }
212 
213  /* Add Option data to struct */
214 
215  if (!ast_strlen_zero(args.options)) {
216  struct ast_flags flags = { 0 };
217  ast_app_parse_options(volume_opts, &flags, NULL, args.options);
218  vi->flags = flags.flags;
219  } else {
220  vi->flags = 0;
221  }
222 
223  return 0;
224 }
225 
227  .name = "VOLUME",
228  .write = volume_write,
229 };
230 
231 static int unload_module(void)
232 {
233  return ast_custom_function_unregister(&volume_function);
234 }
235 
236 static int load_module(void)
237 {
238  return ast_custom_function_register(&volume_function);
239 }
240 
241 AST_MODULE_INFO_STANDARD(ASTERISK_GPL_KEY, "Technology independent volume control");
const char * type
Definition: datastore.h:32
static struct ast_custom_function volume_function
Definition: func_volume.c:226
union ast_frame_subclass subclass
Definition: frame.h:146
#define ast_channel_lock(chan)
Definition: channel.h:2466
Main Channel structure associated with a channel.
Definition: channel.h:742
#define AST_MODULE_INFO_STANDARD(keystr, desc)
Definition: module.h:396
Asterisk main include file. File version handling, generic pbx functions.
#define AST_APP_OPTIONS(holder, options...)
Declares an array of options for an application.
Definition: app.h:712
#define ast_test_flag(p, flag)
Definition: utils.h:63
#define ast_set_flag(p, flag)
Definition: utils.h:70
int ast_audiohook_init(struct ast_audiohook *audiohook, enum ast_audiohook_type type, const char *source)
Initialize an audiohook structure.
Definition: audiohook.c:64
#define LOG_WARNING
Definition: logger.h:144
Audiohooks Architecture.
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: app.c:2101
#define AST_FRAME_DTMF
Definition: frame.h:128
#define AST_DECLARE_APP_ARGS(name, arglist)
Declare a structure to hold an application&#39;s arguments.
Definition: app.h:572
unsigned int flags
Definition: utils.h:201
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:348
static void destroy_callback(void *data)
Definition: func_volume.c:88
unsigned int flags
Definition: func_volume.c:77
Structure for a data store object.
Definition: datastore.h:54
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:2604
int value
Definition: syslog.c:39
int ast_audiohook_destroy(struct ast_audiohook *audiohook)
Destroys an audiohook structure.
Definition: audiohook.c:96
int ast_custom_function_unregister(struct ast_custom_function *acf)
Unregister a custom function.
Definition: pbx.c:3814
int ast_datastore_free(struct ast_datastore *datastore)
Free a data store object.
Definition: datastore.c:65
Utility functions.
ast_audiohook_manipulate_callback manipulate_callback
Definition: audiohook.h:116
static struct ast_datastore_info volume_datastore
Static structure for datastore information.
Definition: func_volume.c:103
#define ast_audiohook_unlock(ah)
Unlock an audiohook.
Definition: audiohook.h:272
static struct ast_app_option volume_opts[128]
Definition: func_volume.c:86
General Asterisk PBX channel definitions.
volume_flags
Definition: func_volume.c:80
static force_inline int attribute_pure ast_strlen_zero(const char *s)
Definition: strings.h:63
Data structure associated with a custom dialplan function.
Definition: pbx.h:95
Core PBX routines and definitions.
int ast_audiohook_detach(struct ast_audiohook *audiohook)
Detach audiohook from channel.
Definition: audiohook.c:401
#define LOG_ERROR
Definition: logger.h:155
static struct @350 args
static int load_module(void)
Definition: func_volume.c:236
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_datastore * ast_datastore_alloc(const struct ast_datastore_info *info, const char *uid)
Definition: datastore.c:98
#define ast_channel_unlock(chan)
Definition: channel.h:2467
static int unload_module(void)
Definition: func_volume.c:231
#define ast_free(a)
Definition: astmm.h:97
Structure used to handle boolean flags.
Definition: utils.h:200
ast_audiohook_direction
Definition: audiohook.h:49
static int volume_write(struct ast_channel *chan, const char *cmd, char *data, const char *value)
Definition: func_volume.c:152
void * data
Definition: datastore.h:56
struct ast_audiohook audiohook
Definition: func_volume.c:74
#define ast_calloc(a, b)
Definition: astmm.h:82
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:108
int ast_frame_adjust_volume(struct ast_frame *f, int adjustment)
Adjusts the volume of the audio samples contained in a frame.
Definition: frame.c:1584
Application convenience functions, designed to give consistent look and feel to Asterisk apps...
Data structure associated with a single frame of data.
Definition: frame.h:142
const char * name
Definition: pbx.h:96
enum ast_audiohook_status status
Definition: audiohook.h:107
#define AST_APP_ARG(name)
Define an application argument.
Definition: app.h:555
enum ast_frame_type frametype
Definition: frame.h:144
#define AST_STANDARD_APP_ARGS(args, parse)
Performs the &#39;standard&#39; argument separation process for an application.
Definition: app.h:604
#define ASTERISK_GPL_KEY
The text the key() function should return.
Definition: module.h:38
#define ast_audiohook_lock(ah)
Lock an audiohook.
Definition: audiohook.h:267
int ast_channel_datastore_add(struct ast_channel *chan, struct ast_datastore *datastore)
Add a datastore to a channel.
Definition: channel.c:2590
#define ast_custom_function_register(acf)
Register a custom function.
Definition: pbx.h:1164
#define ASTERISK_FILE_VERSION(file, version)
Register/unregister a source code file with the core.
Definition: asterisk.h:180
#define AST_APP_OPTION(option, flagno)
Declares an application option that does not accept an argument.
Definition: app.h:721