Asterisk - The Open Source Telephony Project  18.5.0
func_devstate.c
Go to the documentation of this file.
1 /*
2  * Asterisk -- An open source telephony toolkit.
3  *
4  * Copyright (C) 2007, Digium, Inc.
5  *
6  * Russell Bryant <[email protected]>
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 Manually controlled blinky lights
22  *
23  * \author Russell Bryant <[email protected]>
24  *
25  * \ingroup functions
26  *
27  * \todo Delete the entry from AstDB when set to nothing like Set(DEVICE_STATE(Custom:lamp1)=)
28  *
29  * \note Props go out to Ahrimanes in \#asterisk for requesting this at 4:30 AM
30  * when I couldn't sleep. :)
31  */
32 
33 /*** MODULEINFO
34  <support_level>core</support_level>
35  ***/
36 
37 #include "asterisk.h"
38 
39 #include "asterisk/module.h"
40 #include "asterisk/channel.h"
41 #include "asterisk/pbx.h"
42 #include "asterisk/utils.h"
43 #include "asterisk/linkedlists.h"
44 #include "asterisk/devicestate.h"
45 #include "asterisk/cli.h"
46 #include "asterisk/astdb.h"
47 #include "asterisk/app.h"
48 
49 /*** DOCUMENTATION
50  <function name="DEVICE_STATE" language="en_US">
51  <synopsis>
52  Get or Set a device state.
53  </synopsis>
54  <syntax>
55  <parameter name="device" required="true" />
56  </syntax>
57  <description>
58  <para>The DEVICE_STATE function can be used to retrieve the device state from any
59  device state provider. For example:</para>
60  <para>NoOp(SIP/mypeer has state ${DEVICE_STATE(SIP/mypeer)})</para>
61  <para>NoOp(Conference number 1234 has state ${DEVICE_STATE(MeetMe:1234)})</para>
62  <para>The DEVICE_STATE function can also be used to set custom device state from
63  the dialplan. The <literal>Custom:</literal> prefix must be used. For example:</para>
64  <para>Set(DEVICE_STATE(Custom:lamp1)=BUSY)</para>
65  <para>Set(DEVICE_STATE(Custom:lamp2)=NOT_INUSE)</para>
66  <para>You can subscribe to the status of a custom device state using a hint in
67  the dialplan:</para>
68  <para>exten => 1234,hint,Custom:lamp1</para>
69  <para>The possible values for both uses of this function are:</para>
70  <para>UNKNOWN | NOT_INUSE | INUSE | BUSY | INVALID | UNAVAILABLE | RINGING |
71  RINGINUSE | ONHOLD</para>
72  </description>
73  </function>
74  <function name="HINT" language="en_US">
75  <synopsis>
76  Get the devices set for a dialplan hint.
77  </synopsis>
78  <syntax>
79  <parameter name="extension" required="true" argsep="@">
80  <argument name="extension" required="true" />
81  <argument name="context" />
82  </parameter>
83  <parameter name="options">
84  <optionlist>
85  <option name="n">
86  <para>Retrieve name on the hint instead of list of devices.</para>
87  </option>
88  </optionlist>
89  </parameter>
90  </syntax>
91  <description>
92  <para>The HINT function can be used to retrieve the list of devices that are
93  mapped to a dialplan hint. For example:</para>
94  <para>NoOp(Hint for Extension 1234 is ${HINT(1234)})</para>
95  </description>
96  </function>
97  ***/
98 
99 
100 static const char astdb_family[] = "CustomDevstate";
101 
102 static int devstate_read(struct ast_channel *chan, const char *cmd, char *data, char *buf, size_t len)
103 {
105 
106  return 0;
107 }
108 
109 static int devstate_write(struct ast_channel *chan, const char *cmd, char *data, const char *value)
110 {
111  size_t len = strlen("Custom:");
112  enum ast_device_state state_val;
113 
114  if (strncasecmp(data, "Custom:", len)) {
115  ast_log(LOG_WARNING, "The DEVICE_STATE function can only be used to set 'Custom:' device state!\n");
116  return -1;
117  }
118  data += len;
119  if (ast_strlen_zero(data)) {
120  ast_log(LOG_WARNING, "DEVICE_STATE function called with no custom device name!\n");
121  return -1;
122  }
123 
124  state_val = ast_devstate_val(value);
125 
126  if (state_val == AST_DEVICE_UNKNOWN) {
127  ast_log(LOG_ERROR, "DEVICE_STATE function given invalid state value '%s'\n", value);
128  return -1;
129  }
130 
131  ast_db_put(astdb_family, data, value);
132 
133  ast_devstate_changed(state_val, AST_DEVSTATE_CACHABLE, "Custom:%s", data);
134 
135  return 0;
136 }
137 
138 enum {
139  HINT_OPT_NAME = (1 << 0),
140 };
141 
145 
146 static int hint_read(struct ast_channel *chan, const char *cmd, char *data, char *buf, size_t len)
147 {
148  char *exten, *context;
150  AST_APP_ARG(exten);
152  );
153  struct ast_flags opts = { 0, };
154  int res;
155 
156  if (ast_strlen_zero(data)) {
157  ast_log(LOG_WARNING, "The HINT function requires an extension\n");
158  return -1;
159  }
160 
162 
163  if (ast_strlen_zero(args.exten)) {
164  ast_log(LOG_WARNING, "The HINT function requires an extension\n");
165  return -1;
166  }
167 
168  context = exten = args.exten;
169  strsep(&context, "@");
170  if (ast_strlen_zero(context))
171  context = "default";
172 
173  if (!ast_strlen_zero(args.options))
174  ast_app_parse_options(hint_options, &opts, NULL, args.options);
175 
176  if (ast_test_flag(&opts, HINT_OPT_NAME))
177  res = ast_get_hint(NULL, 0, buf, len, chan, context, exten);
178  else
179  res = ast_get_hint(buf, len, NULL, 0, chan, context, exten);
180 
181  return !res; /* ast_get_hint returns non-zero on success */
182 }
183 
184 static enum ast_device_state custom_devstate_callback(const char *data)
185 {
186  char buf[256] = "";
187 
188  /* Ignore check_return warning from Coverity fow ast_db_get below */
189  ast_db_get(astdb_family, data, buf, sizeof(buf));
190 
191  return ast_devstate_val(buf);
192 }
193 
194 static char *handle_cli_devstate_list(struct ast_cli_entry *e, int cmd, struct ast_cli_args *a)
195 {
196  struct ast_db_entry *db_entry, *db_tree;
197 
198  switch (cmd) {
199  case CLI_INIT:
200  e->command = "devstate list";
201  e->usage =
202  "Usage: devstate list\n"
203  " List all custom device states that have been set by using\n"
204  " the DEVICE_STATE dialplan function.\n";
205  return NULL;
206  case CLI_GENERATE:
207  return NULL;
208  }
209 
210  if (a->argc != e->args)
211  return CLI_SHOWUSAGE;
212 
213  ast_cli(a->fd, "\n"
214  "---------------------------------------------------------------------\n"
215  "--- Custom Device States --------------------------------------------\n"
216  "---------------------------------------------------------------------\n"
217  "---\n");
218 
219  db_entry = db_tree = ast_db_gettree(astdb_family, NULL);
220  for (; db_entry; db_entry = db_entry->next) {
221  const char *dev_name = strrchr(db_entry->key, '/') + 1;
222  if (dev_name <= (const char *) 1)
223  continue;
224  ast_cli(a->fd, "--- Name: 'Custom:%s' State: '%s'\n"
225  "---\n", dev_name, db_entry->data);
226  }
227  ast_db_freetree(db_tree);
228  db_tree = NULL;
229 
230  ast_cli(a->fd,
231  "---------------------------------------------------------------------\n"
232  "---------------------------------------------------------------------\n"
233  "\n");
234 
235  return CLI_SUCCESS;
236 }
237 
238 static char *handle_cli_devstate_change(struct ast_cli_entry *e, int cmd, struct ast_cli_args *a)
239 {
240  size_t len;
241  const char *dev, *state;
242  enum ast_device_state state_val;
243 
244  switch (cmd) {
245  case CLI_INIT:
246  e->command = "devstate change";
247  e->usage =
248  "Usage: devstate change <device> <state>\n"
249  " Change a custom device to a new state.\n"
250  " The possible values for the state are:\n"
251  "UNKNOWN | NOT_INUSE | INUSE | BUSY | INVALID | UNAVAILABLE | RINGING\n"
252  "RINGINUSE | ONHOLD\n"
253  "\n"
254  "Examples:\n"
255  " devstate change Custom:mystate1 INUSE\n"
256  " devstate change Custom:mystate1 NOT_INUSE\n"
257  " \n";
258  return NULL;
259  case CLI_GENERATE:
260  {
261  static const char * const cmds[] = { "UNKNOWN", "NOT_INUSE", "INUSE", "BUSY",
262  "UNAVAILABLE", "RINGING", "RINGINUSE", "ONHOLD", NULL };
263 
264  if (a->pos == e->args + 1)
265  return ast_cli_complete(a->word, cmds, a->n);
266 
267  return NULL;
268  }
269  }
270 
271  if (a->argc != e->args + 2)
272  return CLI_SHOWUSAGE;
273 
274  len = strlen("Custom:");
275  dev = a->argv[e->args];
276  state = a->argv[e->args + 1];
277 
278  if (strncasecmp(dev, "Custom:", len)) {
279  ast_cli(a->fd, "The devstate command can only be used to set 'Custom:' device state!\n");
280  return CLI_FAILURE;
281  }
282 
283  dev += len;
284  if (ast_strlen_zero(dev))
285  return CLI_SHOWUSAGE;
286 
287  state_val = ast_devstate_val(state);
288 
289  if (state_val == AST_DEVICE_UNKNOWN)
290  return CLI_SHOWUSAGE;
291 
292  ast_cli(a->fd, "Changing %s to %s\n", dev, state);
293 
294  ast_db_put(astdb_family, dev, state);
295 
296  ast_devstate_changed(state_val, AST_DEVSTATE_CACHABLE, "Custom:%s", dev);
297 
298  return CLI_SUCCESS;
299 }
300 
301 static struct ast_cli_entry cli_funcdevstate[] = {
302  AST_CLI_DEFINE(handle_cli_devstate_list, "List currently known custom device states"),
303  AST_CLI_DEFINE(handle_cli_devstate_change, "Change a custom device state"),
304 };
305 
307  .name = "DEVICE_STATE",
308  .read = devstate_read,
309  .write = devstate_write,
310 };
311 
313  .name = "HINT",
314  .read = hint_read,
315 };
316 
317 static int unload_module(void)
318 {
319  int res = 0;
320 
321  res |= ast_custom_function_unregister(&devstate_function);
322  res |= ast_custom_function_unregister(&hint_function);
323  res |= ast_devstate_prov_del("Custom");
324  res |= ast_cli_unregister_multiple(cli_funcdevstate, ARRAY_LEN(cli_funcdevstate));
325 
326  return res;
327 }
328 
329 static int load_module(void)
330 {
331  int res = 0;
332  struct ast_db_entry *db_entry, *db_tree;
333 
334  /* Populate the device state cache on the system with all of the currently
335  * known custom device states. */
336  db_entry = db_tree = ast_db_gettree(astdb_family, NULL);
337  for (; db_entry; db_entry = db_entry->next) {
338  const char *dev_name = strrchr(db_entry->key, '/') + 1;
339  if (dev_name <= (const char *) 1)
340  continue;
342  AST_DEVSTATE_CACHABLE, "Custom:%s", dev_name);
343  }
344  ast_db_freetree(db_tree);
345  db_tree = NULL;
346 
347  res |= ast_custom_function_register(&devstate_function);
348  res |= ast_custom_function_register(&hint_function);
350  res |= ast_cli_register_multiple(cli_funcdevstate, ARRAY_LEN(cli_funcdevstate));
351 
352  return res;
353 }
354 
355 AST_MODULE_INFO(ASTERISK_GPL_KEY, AST_MODFLAG_LOAD_ORDER, "Gets or sets a device state in the dialplan",
356  .support_level = AST_MODULE_SUPPORT_CORE,
357  .load = load_module,
358  .unload = unload_module,
359  .load_pri = AST_MODPRI_DEVSTATE_PROVIDER,
360 );
const char * name
Definition: pbx.h:119
enum sip_cc_notify_state state
Definition: chan_sip.c:959
int ast_get_hint(char *hint, int hintsize, char *name, int namesize, struct ast_channel *c, const char *context, const char *exten)
If an extension hint exists, return non-zero.
Definition: pbx.c:4141
static char exten[AST_MAX_EXTENSION]
Definition: chan_alsa.c:118
Main Channel structure associated with a channel.
#define AST_CLI_DEFINE(fn, txt,...)
Definition: cli.h:197
ast_device_state
Device States.
Definition: devicestate.h:52
Asterisk main include file. File version handling, generic pbx functions.
#define ARRAY_LEN(a)
Definition: isdn_lib.c:42
int ast_cli_unregister_multiple(struct ast_cli_entry *e, int len)
Unregister multiple commands.
Definition: clicompat.c:30
#define ast_test_flag(p, flag)
Definition: utils.h:63
Device state management.
#define BEGIN_OPTIONS
char buf[BUFSIZE]
Definition: eagi_proxy.c:66
#define AST_STANDARD_APP_ARGS(args, parse)
Performs the &#39;standard&#39; argument separation process for an application.
descriptor for a cli entry.
Definition: cli.h:171
const int argc
Definition: cli.h:160
#define LOG_WARNING
Definition: logger.h:274
void ast_db_freetree(struct ast_db_entry *entry)
Free structure created by ast_db_gettree()
Definition: main/db.c:598
static int hint_read(struct ast_channel *chan, const char *cmd, char *data, char *buf, size_t len)
static const struct ast_app_option hint_options[128]
Definition: cli.h:152
int ast_devstate_prov_del(const char *label)
Remove device state provider.
Definition: devicestate.c:418
#define ast_cli_register_multiple(e, len)
Register multiple commands.
Definition: cli.h:265
int ast_devstate_prov_add(const char *label, ast_devstate_prov_cb_type callback)
Add device state provider.
Definition: devicestate.c:391
const char * args
#define NULL
Definition: resample.c:96
int value
Definition: syslog.c:37
void ast_cli(int fd, const char *fmt,...)
Definition: clicompat.c:6
int ast_custom_function_unregister(struct ast_custom_function *acf)
Unregister a custom function.
Utility functions.
int args
This gets set in ast_cli_register()
Definition: cli.h:185
#define ast_strlen_zero(foo)
Definition: strings.h:52
static int load_module(void)
char * ast_cli_complete(const char *word, const char *const choices[], int pos)
Definition: main/cli.c:1811
#define AST_APP_OPTIONS(holder, options...)
Declares an array of options for an application.
static struct ast_custom_function hint_function
#define ast_log
Definition: astobj2.c:42
struct ast_db_entry * next
Definition: astdb.h:32
int ast_devstate_changed(enum ast_device_state state, enum ast_devstate_cache cachable, const char *fmt,...)
Tells Asterisk the State for Device is changed.
Definition: devicestate.c:510
enum ast_device_state ast_devstate_val(const char *val)
Convert device state from text to integer value.
Definition: devicestate.c:260
General Asterisk PBX channel definitions.
const int fd
Definition: cli.h:159
static enum ast_device_state custom_devstate_callback(const char *data)
const int n
Definition: cli.h:165
Data structure associated with a custom dialplan function.
Definition: pbx.h:118
A set of macros to manage forward-linked lists.
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:2906
Core PBX routines and definitions.
const char *const * argv
Definition: cli.h:161
const char * ast_devstate_str(enum ast_device_state devstate) attribute_pure
Convert device state to text string that is easier to parse.
Definition: devicestate.c:255
#define LOG_ERROR
Definition: logger.h:285
struct ast_db_entry * ast_db_gettree(const char *family, const char *keytree)
Get a list of values within the astdb tree.
Definition: main/db.c:531
#define CLI_SHOWUSAGE
Definition: cli.h:45
static char * handle_cli_devstate_list(struct ast_cli_entry *e, int cmd, struct ast_cli_args *a)
static struct ast_custom_function devstate_function
static int len(struct ast_channel *chan, const char *cmd, char *data, char *buf, size_t buflen)
Definition: astdb.h:31
static char * handle_cli_devstate_change(struct ast_cli_entry *e, int cmd, struct ast_cli_args *a)
#define CLI_FAILURE
Definition: cli.h:46
char data[0]
Definition: astdb.h:34
char * command
Definition: cli.h:186
static int unload_module(void)
const char * word
Definition: cli.h:163
static int devstate_read(struct ast_channel *chan, const char *cmd, char *data, char *buf, size_t len)
static const char astdb_family[]
int ast_db_get(const char *family, const char *key, char *value, int valuelen)
Get key value specified by family/key.
Definition: main/db.c:412
Structure used to handle boolean flags.
Definition: utils.h:199
AST_MODULE_INFO(ASTERISK_GPL_KEY, AST_MODFLAG_GLOBAL_SYMBOLS|AST_MODFLAG_LOAD_ORDER, "HTTP Phone Provisioning",.support_level=AST_MODULE_SUPPORT_EXTENDED,.load=load_module,.unload=unload_module,.reload=reload,.load_pri=AST_MODPRI_CHANNEL_DEPEND,.requires="http",)
const char * usage
Definition: cli.h:177
#define CLI_SUCCESS
Definition: cli.h:44
char * strsep(char **str, const char *delims)
Standard Command Line Interface.
void ast_copy_string(char *dst, const char *src, size_t size)
Size-limited null-terminating string copy.
Definition: strings.h:401
const int pos
Definition: cli.h:164
#define END_OPTIONS
static int devstate_write(struct ast_channel *chan, const char *cmd, char *data, const char *value)
int ast_db_put(const char *family, const char *key, const char *value)
Store value addressed by family/key.
Definition: main/db.c:327
static struct test_options options
static char context[AST_MAX_CONTEXT]
Definition: chan_alsa.c:116
#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
Asterisk module definitions.
Persistant data storage (akin to *doze registry)
#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
static struct ast_cli_entry cli_funcdevstate[]
char * key
Definition: astdb.h:33
#define AST_APP_ARG(name)
Define an application argument.
static struct test_val a