Asterisk - The Open Source Telephony Project  21.4.1
app_chanisavail.c
Go to the documentation of this file.
1 /*
2 * Asterisk -- An open source telephony toolkit.
3 *
4 * Copyright (C) 1999 - 2005, Digium, Inc.
5 *
6 * Mark Spencer <markster@digium.com>
7 * James Golovich <james@gnuinter.net>
8 *
9 * See http://www.asterisk.org for more information about
10 * the Asterisk project. Please do not directly contact
11 * any of the maintainers of this project for assistance;
12 * the project provides a web site, mailing lists and IRC
13 * channels for your use.
14 *
15 * This program is free software, distributed under the terms of
16 * the GNU General Public License Version 2. See the LICENSE file
17 * at the top of the source tree.
18 */
19 
20 /*! \file
21  *
22  * \brief Check if Channel is Available
23  *
24  * \author Mark Spencer <markster@digium.com>
25  * \author James Golovich <james@gnuinter.net>
26 
27  * \ingroup applications
28  */
29 
30 /*** MODULEINFO
31  <support_level>extended</support_level>
32  ***/
33 
34 #include "asterisk.h"
35 
36 #include <sys/ioctl.h>
37 
38 #include "asterisk/lock.h"
39 #include "asterisk/file.h"
40 #include "asterisk/channel.h"
41 #include "asterisk/pbx.h"
42 #include "asterisk/module.h"
43 #include "asterisk/app.h"
44 #include "asterisk/devicestate.h"
45 
46 static const char app[] = "ChanIsAvail";
47 
48 /*** DOCUMENTATION
49  <application name="ChanIsAvail" language="en_US">
50  <synopsis>
51  Check channel availability
52  </synopsis>
53  <syntax>
54  <parameter name="Technology/Resource" required="false" argsep="&amp;">
55  <argument name="Technology/Resource" required="true">
56  <para>Specification of the device(s) to check. These must be in the format of
57  <literal>Technology/Resource</literal>, where <replaceable>Technology</replaceable>
58  represents a particular channel driver, and <replaceable>Resource</replaceable>
59  represents a resource available to that particular channel driver.</para>
60  </argument>
61  <argument name="Technology2/Resource2" multiple="true">
62  <para>Optional extra devices to check</para>
63  <para>If you need more than one enter them as
64  Technology2/Resource2&amp;Technology3/Resource3&amp;.....</para>
65  </argument>
66  </parameter>
67  <parameter name="options" required="false">
68  <optionlist>
69  <option name="a">
70  <para>Check for all available channels, not only the first one</para>
71  </option>
72  <option name="s">
73  <para>Consider the channel unavailable if the channel is in use at all</para>
74  </option>
75  <option name="t" implies="s">
76  <para>Simply checks if specified channels exist in the channel list</para>
77  </option>
78  </optionlist>
79  </parameter>
80  </syntax>
81  <description>
82  <para>This application will check to see if any of the specified channels are available.</para>
83  <para>This application sets the following channel variables:</para>
84  <variablelist>
85  <variable name="AVAILCHAN">
86  <para>The name of the available channel, if one exists</para>
87  </variable>
88  <variable name="AVAILORIGCHAN">
89  <para>The canonical channel name that was used to create the channel</para>
90  </variable>
91  <variable name="AVAILSTATUS">
92  <para>The device state for the device</para>
93  </variable>
94  <variable name="AVAILCAUSECODE">
95  <para>The cause code returned when requesting the channel</para>
96  </variable>
97  </variablelist>
98  </description>
99  </application>
100  ***/
101 
102 static int chanavail_exec(struct ast_channel *chan, const char *data)
103 {
104  int inuse = -1;
105  int option_state = 0;
106  int string_compare = 0;
107  int option_all_avail = 0;
108  int status;
109  char *info;
110  char trychan[512];
111  char *rest;
112  char *tech;
113  char *number;
114  struct ast_str *tmp_availchan = ast_str_alloca(2048);
115  struct ast_str *tmp_availorig = ast_str_alloca(2048);
116  struct ast_str *tmp_availstat = ast_str_alloca(2048);
117  struct ast_str *tmp_availcause = ast_str_alloca(2048);
118  struct ast_channel *tempchan;
119  struct ast_custom_function *cdr_prop_func = ast_custom_function_find("CDR_PROP");
120  struct ast_format_cap *caps = NULL;
122  AST_APP_ARG(reqchans);
123  AST_APP_ARG(options);
124  );
125 
126  info = ast_strdupa(data ?: "");
127 
128  AST_STANDARD_APP_ARGS(args, info);
129 
130  ao2_lock(chan);
131  caps = ao2_bump(ast_channel_nativeformats(chan));
132  ao2_unlock(chan);
133 
134  if (args.options) {
135  if (strchr(args.options, 'a')) {
136  option_all_avail = 1;
137  }
138  if (strchr(args.options, 's')) {
139  option_state = 1;
140  }
141  if (strchr(args.options, 't')) {
142  string_compare = 1;
143  }
144  }
145 
146  rest = args.reqchans;
147  if (!rest) {
148  rest = "";
149  }
150  while ((tech = strsep(&rest, "&"))) {
151  tech = ast_strip(tech);
152 
153  number = strchr(tech, '/');
154  if (!number) {
155  if (!ast_strlen_zero(tech)) {
156  ast_log(LOG_WARNING, "Invalid ChanIsAvail technology/resource argument: '%s'\n",
157  tech);
158  }
159 
160  ast_str_append(&tmp_availstat, 0, "%s%d",
161  ast_str_strlen(tmp_availstat) ? "&" : "", AST_DEVICE_INVALID);
162  continue;
163  }
164  *number++ = '\0';
165 
166  status = AST_DEVICE_UNKNOWN;
167 
168  if (string_compare) {
169  /* ast_parse_device_state checks for "SIP/1234" as a channel name.
170  ast_device_state will ask the SIP driver for the channel state. */
171 
172  snprintf(trychan, sizeof(trychan), "%s/%s", tech, number);
173  status = inuse = ast_parse_device_state(trychan);
174  } else if (option_state) {
175  /* If the pbx says in use then don't bother trying further.
176  This is to permit testing if someone's on a call, even if the
177  channel can permit more calls (ie callwaiting, sip calls, etc). */
178 
179  snprintf(trychan, sizeof(trychan), "%s/%s", tech, number);
180  status = inuse = ast_device_state(trychan);
181  }
182  ast_str_append(&tmp_availstat, 0, "%s%d", ast_str_strlen(tmp_availstat) ? "&" : "", status);
183 
184  if ((inuse <= (int) AST_DEVICE_NOT_INUSE)
185  && (tempchan = ast_request(tech, caps, NULL, chan, number, &status))) {
186 
187  ast_str_append(&tmp_availchan, 0, "%s%s",
188  ast_str_strlen(tmp_availchan) ? "&" : "", ast_channel_name(tempchan));
189 
190  ast_str_append(&tmp_availorig, 0, "%s%s/%s",
191  ast_str_strlen(tmp_availorig) ? "&" : "", tech, number);
192 
193  ast_str_append(&tmp_availcause, 0, "%s%d",
194  ast_str_strlen(tmp_availcause) ? "&" : "", status);
195 
196  /* Disable CDR for this temporary channel. */
197  if (cdr_prop_func) {
198  ast_func_write(tempchan, "CDR_PROP(disable)", "1");
199  }
200 
201  ast_hangup(tempchan);
202  tempchan = NULL;
203 
204  if (!option_all_avail) {
205  break;
206  }
207  }
208 
209  }
210 
211  ao2_cleanup(caps);
212 
213  pbx_builtin_setvar_helper(chan, "AVAILCHAN", ast_str_buffer(tmp_availchan));
214  /* Store the originally used channel too */
215  pbx_builtin_setvar_helper(chan, "AVAILORIGCHAN", ast_str_buffer(tmp_availorig));
216  pbx_builtin_setvar_helper(chan, "AVAILSTATUS", ast_str_buffer(tmp_availstat));
217  pbx_builtin_setvar_helper(chan, "AVAILCAUSECODE", ast_str_buffer(tmp_availcause));
218 
219  return 0;
220 }
221 
222 static int unload_module(void)
223 {
224  return ast_unregister_application(app);
225 }
226 
227 static int load_module(void)
228 {
229  return ast_register_application_xml(app, chanavail_exec) ?
231 }
232 
233 AST_MODULE_INFO(ASTERISK_GPL_KEY, AST_MODFLAG_DEFAULT, "Check channel availability",
234  .support_level = AST_MODULE_SUPPORT_EXTENDED,
235  .load = load_module,
236  .unload = unload_module,
237  .optional_modules = "func_cdr"
238 );
Main Channel structure associated with a channel.
ast_device_state
Device States.
Definition: devicestate.h:52
Asterisk locking-related definitions:
Asterisk main include file. File version handling, generic pbx functions.
Device state management.
#define AST_STANDARD_APP_ARGS(args, parse)
Performs the 'standard' argument separation process for an application.
char * ast_str_buffer(const struct ast_str *buf)
Returns the string buffer within the ast_str buf.
Definition: strings.h:761
enum ast_device_state ast_parse_device_state(const char *device)
Search the Channels by Name.
Definition: devicestate.c:287
int ast_str_append(struct ast_str **buf, ssize_t max_len, const char *fmt,...)
Append to a thread local dynamic string.
Definition: strings.h:1139
Generic File Format Support. Should be included by clients of the file handling routines. File service providers should instead include mod_format.h.
int ast_unregister_application(const char *app)
Unregister an application.
Definition: pbx_app.c:392
struct ast_channel * ast_request(const char *type, struct ast_format_cap *request_cap, const struct ast_assigned_ids *assignedids, const struct ast_channel *requestor, const char *addr, int *cause)
Requests a channel.
Definition: channel.c:6354
Number structure.
Definition: app_followme.c:154
#define ao2_bump(obj)
Bump refcount on an AO2 object by one, returning the object.
Definition: astobj2.h:480
General Asterisk PBX channel definitions.
#define ast_strdupa(s)
duplicate a string in memory from the stack
Definition: astmm.h:298
Data structure associated with a custom dialplan function.
Definition: pbx.h:118
char * ast_strip(char *s)
Strip leading/trailing whitespace from a string.
Definition: strings.h:223
Core PBX routines and definitions.
Support for dynamic strings.
Definition: strings.h:623
Format capabilities structure, holds formats + preference order + etc.
Definition: format_cap.c:54
void ast_hangup(struct ast_channel *chan)
Hang up a channel.
Definition: channel.c:2541
Module has failed to load, may be in an inconsistent state.
Definition: module.h:78
int pbx_builtin_setvar_helper(struct ast_channel *chan, const char *name, const char *value)
Add a variable to the channel variable stack, removing the most recently set value for the same name...
size_t ast_str_strlen(const struct ast_str *buf)
Returns the current length of the string stored within buf.
Definition: strings.h:730
#define ASTERISK_GPL_KEY
The text the key() function should return.
Definition: module.h:46
Asterisk module definitions.
int ast_func_write(struct ast_channel *chan, const char *function, const char *value)
executes a write operation on a function
#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_register_application_xml(app, execute)
Register an application using XML documentation.
Definition: module.h:640
#define AST_APP_ARG(name)
Define an application argument.