Wed Jan 8 2020 09:49:39

Asterisk developer's documentation


app_directed_pickup.c
Go to the documentation of this file.
1 /*
2  * Asterisk -- An open source telephony toolkit.
3  *
4  * Copyright (C) 2005, Joshua Colp
5  *
6  * Joshua Colp <jcolp@digium.com>
7  *
8  * Portions merged from app_pickupchan, which was
9  * Copyright (C) 2008, Gary Cook
10  *
11  * See http://www.asterisk.org for more information about
12  * the Asterisk project. Please do not directly contact
13  * any of the maintainers of this project for assistance;
14  * the project provides a web site, mailing lists and IRC
15  * channels for your use.
16  *
17  * This program is free software, distributed under the terms of
18  * the GNU General Public License Version 2. See the LICENSE file
19  * at the top of the source tree.
20  */
21 
22 /*! \file
23  *
24  * \brief Directed Call Pickup Support
25  *
26  * \author Joshua Colp <jcolp@digium.com>
27  * \author Gary Cook
28  *
29  * \ingroup applications
30  */
31 
32 /*** MODULEINFO
33  <support_level>core</support_level>
34  ***/
35 
36 #include "asterisk.h"
37 
38 ASTERISK_FILE_VERSION(__FILE__, "$Revision: 370642 $")
39 
40 #include "asterisk/file.h"
41 #include "asterisk/channel.h"
42 #include "asterisk/pbx.h"
43 #include "asterisk/module.h"
44 #include "asterisk/lock.h"
45 #include "asterisk/app.h"
46 #include "asterisk/features.h"
47 #include "asterisk/manager.h"
48 #include "asterisk/callerid.h"
49 #include "asterisk/cel.h"
50 
51 #define PICKUPMARK "PICKUPMARK"
52 
53 /*** DOCUMENTATION
54  <application name="Pickup" language="en_US">
55  <synopsis>
56  Directed extension call pickup.
57  </synopsis>
58  <syntax>
59  <parameter name="targets" argsep="&amp;">
60  <argument name="extension" argsep="@" required="true">
61  <para>Specification of the pickup target.</para>
62  <argument name="extension" required="true"/>
63  <argument name="context" />
64  </argument>
65  <argument name="extension2" argsep="@" multiple="true">
66  <para>Additional specifications of pickup targets.</para>
67  <argument name="extension2" required="true"/>
68  <argument name="context2"/>
69  </argument>
70  </parameter>
71  </syntax>
72  <description>
73  <para>This application can pickup a specified ringing channel. The channel
74  to pickup can be specified in the following ways.</para>
75  <para>1) If no <replaceable>extension</replaceable> targets are specified,
76  the application will pickup a channel matching the pickup group of the
77  requesting channel.</para>
78  <para>2) If the <replaceable>extension</replaceable> is specified with a
79  <replaceable>context</replaceable> of the special string
80  <literal>PICKUPMARK</literal> (for example 10@PICKUPMARK), the application
81  will pickup a channel which has defined the channel variable
82  <variable>PICKUPMARK</variable> with the same value as
83  <replaceable>extension</replaceable> (in this example,
84  <literal>10</literal>).</para>
85  <para>3) If the <replaceable>extension</replaceable> is specified
86  with or without a <replaceable>context</replaceable>, the channel with a
87  matching <replaceable>extension</replaceable> and <replaceable>context</replaceable>
88  will be picked up. If no <replaceable>context</replaceable> is specified,
89  the current context will be used.</para>
90  <note><para>The <replaceable>extension</replaceable> is typically set on
91  matching channels by the dial application that created the channel. The
92  <replaceable>context</replaceable> is set on matching channels by the
93  channel driver for the device.</para></note>
94  </description>
95  </application>
96  <application name="PickupChan" language="en_US">
97  <synopsis>
98  Pickup a ringing channel.
99  </synopsis>
100  <syntax >
101  <parameter name="Technology/Resource" argsep="&amp;" required="true">
102  <argument name="Technology/Resource" required="true" />
103  <argument name="Technology2/Resource2" required="false" multiple="true" />
104  </parameter>
105  <parameter name="options" required="false">
106  <optionlist>
107  <option name="p">
108  <para>Channel name specified partial name. Used when find channel by callid.</para>
109  </option>
110  </optionlist>
111  </parameter>
112  </syntax>
113  <description>
114  <para>This will pickup a specified <replaceable>channel</replaceable> if ringing.</para>
115  </description>
116  </application>
117  ***/
118 
119 static const char app[] = "Pickup";
120 static const char app2[] = "PickupChan";
121 
123  const char *name;
124  size_t len;
125 };
126 
127 static int pickup_by_name_cb(void *obj, void *arg, void *data, int flags)
128 {
129  struct ast_channel *target = obj;/*!< Potential pickup target */
130  struct pickup_by_name_args *args = data;
131 
132  ast_channel_lock(target);
133  if (!strncasecmp(target->name, args->name, args->len) && ast_can_pickup(target)) {
134  /* Return with the channel still locked on purpose */
135  return CMP_MATCH | CMP_STOP;
136  }
137  ast_channel_unlock(target);
138 
139  return 0;
140 }
141 
142 /*! \brief Helper Function to walk through ALL channels checking NAME and STATE */
143 static struct ast_channel *my_ast_get_channel_by_name_locked(const char *channame)
144 {
145  char *chkchan;
146  struct pickup_by_name_args pickup_args;
147 
148  /* Check if channel name contains a '-'.
149  * In this case the channel name will be interpreted as full channel name.
150  */
151  if (strchr(channame, '-')) {
152  /* check full channel name */
153  pickup_args.len = strlen(channame);
154  pickup_args.name = channame;
155  } else {
156  /* need to append a '-' for the comparison so we check full channel name,
157  * i.e SIP/hgc- , use a temporary variable so original stays the same for
158  * debugging.
159  */
160  pickup_args.len = strlen(channame) + 1;
161  chkchan = ast_alloca(pickup_args.len + 1);
162  strcpy(chkchan, channame);
163  strcat(chkchan, "-");
164  pickup_args.name = chkchan;
165  }
166 
167  return ast_channel_callback(pickup_by_name_cb, NULL, &pickup_args, 0);
168 }
169 
170 /*! \brief Attempt to pick up named channel, does not use context */
171 static int pickup_by_channel(struct ast_channel *chan, char *pickup)
172 {
173  int res = -1;
174  struct ast_channel *target;/*!< Potential pickup target */
175 
176  target = my_ast_get_channel_by_name_locked(pickup);
177  if (target) {
178  /* Just check that we are not picking up the SAME as target. (i.e. ourself) */
179  if (chan != target) {
180  res = ast_do_pickup(chan, target);
181  }
182  ast_channel_unlock(target);
183  target = ast_channel_unref(target);
184  }
185 
186  return res;
187 }
188 
189 /* Attempt to pick up specified extension with context */
190 static int pickup_by_exten(struct ast_channel *chan, const char *exten, const char *context)
191 {
192  struct ast_channel *target = NULL;/*!< Potential pickup target */
193  struct ast_channel_iterator *iter;
194  int res = -1;
195 
196  if (!(iter = ast_channel_iterator_by_exten_new(exten, context))) {
197  return -1;
198  }
199 
200  while ((target = ast_channel_iterator_next(iter))) {
201  ast_channel_lock(target);
202  if ((chan != target) && ast_can_pickup(target)) {
203  ast_log(LOG_NOTICE, "%s pickup by %s\n", target->name, chan->name);
204  break;
205  }
206  ast_channel_unlock(target);
207  target = ast_channel_unref(target);
208  }
209 
211 
212  if (target) {
213  res = ast_do_pickup(chan, target);
214  ast_channel_unlock(target);
215  target = ast_channel_unref(target);
216  }
217 
218  return res;
219 }
220 
221 static int find_by_mark(void *obj, void *arg, void *data, int flags)
222 {
223  struct ast_channel *target = obj;/*!< Potential pickup target */
224  const char *mark = data;
225  const char *tmp;
226 
227  ast_channel_lock(target);
228  tmp = pbx_builtin_getvar_helper(target, PICKUPMARK);
229  if (tmp && !strcasecmp(tmp, mark) && ast_can_pickup(target)) {
230  /* Return with the channel still locked on purpose */
231  return CMP_MATCH | CMP_STOP;
232  }
233  ast_channel_unlock(target);
234 
235  return 0;
236 }
237 
238 /* Attempt to pick up specified mark */
239 static int pickup_by_mark(struct ast_channel *chan, const char *mark)
240 {
241  struct ast_channel *target;/*!< Potential pickup target */
242  int res = -1;
243 
244  /* The found channel is already locked. */
245  target = ast_channel_callback(find_by_mark, NULL, (char *) mark, 0);
246  if (target) {
247  res = ast_do_pickup(chan, target);
248  ast_channel_unlock(target);
249  target = ast_channel_unref(target);
250  }
251 
252  return res;
253 }
254 
255 static int find_channel_by_group(void *obj, void *arg, void *data, int flags)
256 {
257  struct ast_channel *target = obj;/*!< Potential pickup target */
258  struct ast_channel *chan = data;/*!< Channel wanting to pickup call */
259 
260  ast_channel_lock(target);
261  if (chan != target && (chan->pickupgroup & target->callgroup)
262  && ast_can_pickup(target)) {
263  /* Return with the channel still locked on purpose */
264  return CMP_MATCH | CMP_STOP;
265  }
266  ast_channel_unlock(target);
267 
268  return 0;
269 }
270 
271 static int pickup_by_group(struct ast_channel *chan)
272 {
273  struct ast_channel *target;/*!< Potential pickup target */
274  int res = -1;
275 
276  /* The found channel is already locked. */
277  target = ast_channel_callback(find_channel_by_group, NULL, chan, 0);
278  if (target) {
279  ast_log(LOG_NOTICE, "pickup %s attempt by %s\n", target->name, chan->name);
280  res = ast_do_pickup(chan, target);
281  ast_channel_unlock(target);
282  target = ast_channel_unref(target);
283  }
284 
285  return res;
286 }
287 
288 /* application entry point for Pickup() */
289 static int pickup_exec(struct ast_channel *chan, const char *data)
290 {
291  char *tmp = ast_strdupa(data);
292  char *exten = NULL, *context = NULL;
293 
294  if (ast_strlen_zero(data)) {
295  return pickup_by_group(chan) ? 0 : -1;
296  }
297 
298  /* Parse extension (and context if there) */
299  while (!ast_strlen_zero(tmp) && (exten = strsep(&tmp, "&"))) {
300  if ((context = strchr(exten, '@')))
301  *context++ = '\0';
302  if (!ast_strlen_zero(context) && !strcasecmp(context, PICKUPMARK)) {
303  if (!pickup_by_mark(chan, exten)) {
304  /* Pickup successful. Stop the dialplan this channel is a zombie. */
305  return -1;
306  }
307  } else {
308  if (!pickup_by_exten(chan, exten, !ast_strlen_zero(context) ? context : chan->context)) {
309  /* Pickup successful. Stop the dialplan this channel is a zombie. */
310  return -1;
311  }
312  }
313  ast_log(LOG_NOTICE, "No target channel found for %s.\n", exten);
314  }
315 
316  /* Pickup failed. Keep going in the dialplan. */
317  return 0;
318 }
319 
320 /* Find channel for pick up specified by partial channel name */
321 static int find_by_part(void *obj, void *arg, void *data, int flags)
322 {
323  struct ast_channel *target = obj;/*!< Potential pickup target */
324  const char *part = data;
325  int len = strlen(part);
326 
327  ast_channel_lock(target);
328  if (len <= strlen(target->name) && !strncmp(target->name, part, len)
329  && ast_can_pickup(target)) {
330  /* Return with the channel still locked on purpose */
331  return CMP_MATCH | CMP_STOP;
332  }
333  ast_channel_unlock(target);
334 
335  return 0;
336 }
337 
338 /* Attempt to pick up specified by partial channel name */
339 static int pickup_by_part(struct ast_channel *chan, const char *part)
340 {
341  struct ast_channel *target;/*!< Potential pickup target */
342  int res = -1;
343 
344  /* The found channel is already locked. */
345  target = ast_channel_callback(find_by_part, NULL, (char *) part, 0);
346  if (target) {
347  res = ast_do_pickup(chan, target);
348  ast_channel_unlock(target);
349  target = ast_channel_unref(target);
350  }
351 
352  return res;
353 }
354 
355 /* application entry point for PickupChan() */
356 static int pickupchan_exec(struct ast_channel *chan, const char *data)
357 {
358  int partial_pickup = 0;
359  char *pickup = NULL;
360  char *parse = ast_strdupa(data);
362  AST_APP_ARG(channel);
363  AST_APP_ARG(options);
364  );
365  AST_STANDARD_APP_ARGS(args, parse);
366 
367  if (ast_strlen_zero(args.channel)) {
368  ast_log(LOG_WARNING, "PickupChan requires an argument (channel)!\n");
369  /* Pickup failed. Keep going in the dialplan. */
370  return 0;
371  }
372 
373  if (!ast_strlen_zero(args.options) && strchr(args.options, 'p')) {
374  partial_pickup = 1;
375  }
376 
377  /* Parse channel */
378  while (!ast_strlen_zero(args.channel) && (pickup = strsep(&args.channel, "&"))) {
379  if (!strncasecmp(chan->name, pickup, strlen(pickup))) {
380  ast_log(LOG_NOTICE, "Cannot pickup your own channel %s.\n", pickup);
381  } else {
382  if (partial_pickup) {
383  if (!pickup_by_part(chan, pickup)) {
384  /* Pickup successful. Stop the dialplan this channel is a zombie. */
385  return -1;
386  }
387  } else if (!pickup_by_channel(chan, pickup)) {
388  /* Pickup successful. Stop the dialplan this channel is a zombie. */
389  return -1;
390  }
391  ast_log(LOG_NOTICE, "No target channel found for %s.\n", pickup);
392  }
393  }
394 
395  /* Pickup failed. Keep going in the dialplan. */
396  return 0;
397 }
398 
399 static int unload_module(void)
400 {
401  int res;
402 
403  res = ast_unregister_application(app);
404  res |= ast_unregister_application(app2);
405 
406  return res;
407 }
408 
409 static int load_module(void)
410 {
411  int res;
412 
415 
416  return res;
417 }
418 
419 AST_MODULE_INFO_STANDARD(ASTERISK_GPL_KEY, "Directed Call Pickup Application");
#define ast_channel_lock(chan)
Definition: channel.h:2466
static char exten[AST_MAX_EXTENSION]
Definition: chan_alsa.c:109
Main Channel structure associated with a channel.
Definition: channel.h:742
#define AST_MODULE_INFO_STANDARD(keystr, desc)
Definition: module.h:396
Asterisk locking-related definitions:
struct ast_channel * ast_channel_iterator_next(struct ast_channel_iterator *i)
Get the next channel for a channel iterator.
Definition: channel.c:1715
Asterisk main include file. File version handling, generic pbx functions.
char * strsep(char **str, const char *delims)
CallerID (and other GR30) management and generation Includes code and algorithms from the Zapata libr...
static int find_by_part(void *obj, void *arg, void *data, int flags)
#define ast_alloca(size)
call __builtin_alloca to ensure we get gcc builtin semantics
Definition: utils.h:653
#define ast_channel_unref(c)
Decrease channel reference count.
Definition: channel.h:2502
static int pickup_by_channel(struct ast_channel *chan, char *pickup)
Attempt to pick up named channel, does not use context.
Call Event Logging API.
char context[AST_MAX_CONTEXT]
Definition: channel.h:868
#define LOG_WARNING
Definition: logger.h:144
static int pickup_by_mark(struct ast_channel *chan, const char *mark)
#define AST_DECLARE_APP_ARGS(name, arglist)
Declare a structure to hold an application&#39;s arguments.
Definition: app.h:572
static int pickup_by_exten(struct ast_channel *chan, const char *exten, const char *context)
const char * data
Definition: channel.h:755
static int find_channel_by_group(void *obj, void *arg, void *data, int flags)
int ast_unregister_application(const char *app)
Unregister an application.
Definition: pbx.c:7705
ast_group_t pickupgroup
Definition: channel.h:819
ast_group_t callgroup
Definition: channel.h:818
const char * pbx_builtin_getvar_helper(struct ast_channel *chan, const char *name)
Return a pointer to the value of the corresponding channel variable.
Definition: pbx.c:10475
unsigned int flags
Definition: channel.h:850
static int find_by_mark(void *obj, void *arg, void *data, int flags)
General Asterisk PBX channel definitions.
static int load_module(void)
static force_inline int attribute_pure ast_strlen_zero(const char *s)
Definition: strings.h:63
static const char app[]
static int pickup_exec(struct ast_channel *chan, const char *data)
Core PBX routines and definitions.
struct ast_channel * ast_channel_callback(ao2_callback_data_fn *cb_fn, void *arg, void *data, int ao2_flags)
Call a function with every active channel.
Definition: channel.c:1634
The AMI - Asterisk Manager Interface - is a TCP protocol created to manage Asterisk with third-party ...
static int pickup_by_name_cb(void *obj, void *arg, void *data, int flags)
static int pickupchan_exec(struct ast_channel *chan, const char *data)
#define ast_strdupa(s)
duplicate a string in memory from the stack
Definition: utils.h:663
static int pickup_by_part(struct ast_channel *chan, const char *part)
static struct @350 args
static int len(struct ast_channel *chan, const char *cmd, char *data, char *buf, size_t buflen)
struct ast_channel_iterator * ast_channel_iterator_by_exten_new(const char *exten, const char *context)
Create a new channel iterator based on extension.
Definition: channel.c:1691
const ast_string_field name
Definition: channel.h:787
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
#define LOG_NOTICE
Definition: logger.h:133
#define ast_channel_unlock(chan)
Definition: channel.h:2467
static void parse(struct mgcp_request *req)
Definition: chan_mgcp.c:1858
int ast_do_pickup(struct ast_channel *chan, struct ast_channel *target)
Pickup a call target.
Definition: features.c:7414
static struct ast_channel * my_ast_get_channel_by_name_locked(const char *channame)
Helper Function to walk through ALL channels checking NAME and STATE.
static const char app2[]
static int pickup_by_group(struct ast_channel *chan)
struct ast_channel_iterator * ast_channel_iterator_destroy(struct ast_channel_iterator *i)
Destroy a channel iterator.
Definition: channel.c:1649
Application convenience functions, designed to give consistent look and feel to Asterisk apps...
#define AST_APP_ARG(name)
Define an application argument.
Definition: app.h:555
#define AST_STANDARD_APP_ARGS(args, parse)
Performs the &#39;standard&#39; argument separation process for an application.
Definition: app.h:604
static char context[AST_MAX_CONTEXT]
Definition: chan_alsa.c:107
Call Parking and Pickup API Includes code and algorithms from the Zapata library. ...
#define ASTERISK_GPL_KEY
The text the key() function should return.
Definition: module.h:38
Asterisk module definitions.
static int unload_module(void)
#define ast_register_application_xml(app, execute)
Register an application using XML documentation.
Definition: module.h:437
#define ASTERISK_FILE_VERSION(file, version)
Register/unregister a source code file with the core.
Definition: asterisk.h:180
int ast_can_pickup(struct ast_channel *chan)
Test if a channel can be picked up.
Definition: features.c:7338
#define PICKUPMARK