Wed Jan 8 2020 09:49:47

Asterisk developer's documentation


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 <russell@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 Manually controlled blinky lights
22  *
23  * \author Russell Bryant <russell@digium.com>
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 ASTERISK_FILE_VERSION(__FILE__, "$Revision: 378303 $")
40 
41 #include "asterisk/module.h"
42 #include "asterisk/channel.h"
43 #include "asterisk/pbx.h"
44 #include "asterisk/utils.h"
45 #include "asterisk/linkedlists.h"
46 #include "asterisk/devicestate.h"
47 #include "asterisk/cli.h"
48 #include "asterisk/astdb.h"
49 #include "asterisk/app.h"
50 
51 /*** DOCUMENTATION
52  <function name="DEVICE_STATE" language="en_US">
53  <synopsis>
54  Get or Set a device state.
55  </synopsis>
56  <syntax>
57  <parameter name="device" required="true" />
58  </syntax>
59  <description>
60  <para>The DEVICE_STATE function can be used to retrieve the device state from any
61  device state provider. For example:</para>
62  <para>NoOp(SIP/mypeer has state ${DEVICE_STATE(SIP/mypeer)})</para>
63  <para>NoOp(Conference number 1234 has state ${DEVICE_STATE(MeetMe:1234)})</para>
64  <para>The DEVICE_STATE function can also be used to set custom device state from
65  the dialplan. The <literal>Custom:</literal> prefix must be used. For example:</para>
66  <para>Set(DEVICE_STATE(Custom:lamp1)=BUSY)</para>
67  <para>Set(DEVICE_STATE(Custom:lamp2)=NOT_INUSE)</para>
68  <para>You can subscribe to the status of a custom device state using a hint in
69  the dialplan:</para>
70  <para>exten => 1234,hint,Custom:lamp1</para>
71  <para>The possible values for both uses of this function are:</para>
72  <para>UNKNOWN | NOT_INUSE | INUSE | BUSY | INVALID | UNAVAILABLE | RINGING |
73  RINGINUSE | ONHOLD</para>
74  </description>
75  </function>
76  <function name="HINT" language="en_US">
77  <synopsis>
78  Get the devices set for a dialplan hint.
79  </synopsis>
80  <syntax>
81  <parameter name="extension" required="true" argsep="@">
82  <argument name="extension" required="true" />
83  <argument name="context" />
84  </parameter>
85  <parameter name="options">
86  <optionlist>
87  <option name="n">
88  <para>Retrieve name on the hint instead of list of devices.</para>
89  </option>
90  </optionlist>
91  </parameter>
92  </syntax>
93  <description>
94  <para>The HINT function can be used to retrieve the list of devices that are
95  mapped to a dialplan hint. For example:</para>
96  <para>NoOp(Hint for Extension 1234 is ${HINT(1234)})</para>
97  </description>
98  </function>
99  ***/
100 
101 
102 static const char astdb_family[] = "CustomDevstate";
103 
104 static int devstate_read(struct ast_channel *chan, const char *cmd, char *data, char *buf, size_t len)
105 {
107 
108  return 0;
109 }
110 
111 static int devstate_write(struct ast_channel *chan, const char *cmd, char *data, const char *value)
112 {
113  size_t len = strlen("Custom:");
114  enum ast_device_state state_val;
115 
116  if (strncasecmp(data, "Custom:", len)) {
117  ast_log(LOG_WARNING, "The DEVICE_STATE function can only be used to set 'Custom:' device state!\n");
118  return -1;
119  }
120  data += len;
121  if (ast_strlen_zero(data)) {
122  ast_log(LOG_WARNING, "DEVICE_STATE function called with no custom device name!\n");
123  return -1;
124  }
125 
126  state_val = ast_devstate_val(value);
127 
128  if (state_val == AST_DEVICE_UNKNOWN) {
129  ast_log(LOG_ERROR, "DEVICE_STATE function given invalid state value '%s'\n", value);
130  return -1;
131  }
132 
133  ast_db_put(astdb_family, data, value);
134 
135  ast_devstate_changed(state_val, AST_DEVSTATE_CACHABLE, "Custom:%s", data);
136 
137  return 0;
138 }
139 
140 enum {
141  HINT_OPT_NAME = (1 << 0),
142 };
143 
147 
148 static int hint_read(struct ast_channel *chan, const char *cmd, char *data, char *buf, size_t len)
149 {
150  char *exten, *context;
152  AST_APP_ARG(exten);
153  AST_APP_ARG(options);
154  );
155  struct ast_flags opts = { 0, };
156  int res;
157 
158  if (ast_strlen_zero(data)) {
159  ast_log(LOG_WARNING, "The HINT function requires an extension\n");
160  return -1;
161  }
162 
164 
165  if (ast_strlen_zero(args.exten)) {
166  ast_log(LOG_WARNING, "The HINT function requires an extension\n");
167  return -1;
168  }
169 
170  context = exten = args.exten;
171  strsep(&context, "@");
172  if (ast_strlen_zero(context))
173  context = "default";
174 
175  if (!ast_strlen_zero(args.options))
176  ast_app_parse_options(hint_options, &opts, NULL, args.options);
177 
178  if (ast_test_flag(&opts, HINT_OPT_NAME))
179  res = ast_get_hint(NULL, 0, buf, len, chan, context, exten);
180  else
181  res = ast_get_hint(buf, len, NULL, 0, chan, context, exten);
182 
183  return !res; /* ast_get_hint returns non-zero on success */
184 }
185 
186 static enum ast_device_state custom_devstate_callback(const char *data)
187 {
188  char buf[256] = "";
189 
190  /* Ignore check_return warning from Coverity fow ast_db_get below */
191  ast_db_get(astdb_family, data, buf, sizeof(buf));
192 
193  return ast_devstate_val(buf);
194 }
195 
196 static char *handle_cli_devstate_list(struct ast_cli_entry *e, int cmd, struct ast_cli_args *a)
197 {
198  struct ast_db_entry *db_entry, *db_tree;
199 
200  switch (cmd) {
201  case CLI_INIT:
202  e->command = "devstate list";
203  e->usage =
204  "Usage: devstate list\n"
205  " List all custom device states that have been set by using\n"
206  " the DEVICE_STATE dialplan function.\n";
207  return NULL;
208  case CLI_GENERATE:
209  return NULL;
210  }
211 
212  if (a->argc != e->args)
213  return CLI_SHOWUSAGE;
214 
215  ast_cli(a->fd, "\n"
216  "---------------------------------------------------------------------\n"
217  "--- Custom Device States --------------------------------------------\n"
218  "---------------------------------------------------------------------\n"
219  "---\n");
220 
221  db_entry = db_tree = ast_db_gettree(astdb_family, NULL);
222  for (; db_entry; db_entry = db_entry->next) {
223  const char *dev_name = strrchr(db_entry->key, '/') + 1;
224  if (dev_name <= (const char *) 1)
225  continue;
226  ast_cli(a->fd, "--- Name: 'Custom:%s' State: '%s'\n"
227  "---\n", dev_name, db_entry->data);
228  }
229  ast_db_freetree(db_tree);
230  db_tree = NULL;
231 
232  ast_cli(a->fd,
233  "---------------------------------------------------------------------\n"
234  "---------------------------------------------------------------------\n"
235  "\n");
236 
237  return CLI_SUCCESS;
238 }
239 
240 static char *handle_cli_devstate_change(struct ast_cli_entry *e, int cmd, struct ast_cli_args *a)
241 {
242  size_t len;
243  const char *dev, *state;
244  enum ast_device_state state_val;
245 
246  switch (cmd) {
247  case CLI_INIT:
248  e->command = "devstate change";
249  e->usage =
250  "Usage: devstate change <device> <state>\n"
251  " Change a custom device to a new state.\n"
252  " The possible values for the state are:\n"
253  "UNKNOWN | NOT_INUSE | INUSE | BUSY | INVALID | UNAVAILABLE | RINGING\n"
254  "RINGINUSE | ONHOLD\n"
255  "\n"
256  "Examples:\n"
257  " devstate change Custom:mystate1 INUSE\n"
258  " devstate change Custom:mystate1 NOT_INUSE\n"
259  " \n";
260  return NULL;
261  case CLI_GENERATE:
262  {
263  static const char * const cmds[] = { "UNKNOWN", "NOT_INUSE", "INUSE", "BUSY",
264  "UNAVAILABLE", "RINGING", "RINGINUSE", "ONHOLD", NULL };
265 
266  if (a->pos == e->args + 1)
267  return ast_cli_complete(a->word, cmds, a->n);
268 
269  return NULL;
270  }
271  }
272 
273  if (a->argc != e->args + 2)
274  return CLI_SHOWUSAGE;
275 
276  len = strlen("Custom:");
277  dev = a->argv[e->args];
278  state = a->argv[e->args + 1];
279 
280  if (strncasecmp(dev, "Custom:", len)) {
281  ast_cli(a->fd, "The devstate command can only be used to set 'Custom:' device state!\n");
282  return CLI_FAILURE;
283  }
284 
285  dev += len;
286  if (ast_strlen_zero(dev))
287  return CLI_SHOWUSAGE;
288 
289  state_val = ast_devstate_val(state);
290 
291  if (state_val == AST_DEVICE_UNKNOWN)
292  return CLI_SHOWUSAGE;
293 
294  ast_cli(a->fd, "Changing %s to %s\n", dev, state);
295 
296  ast_db_put(astdb_family, dev, state);
297 
298  ast_devstate_changed(state_val, AST_DEVSTATE_CACHABLE, "Custom:%s", dev);
299 
300  return CLI_SUCCESS;
301 }
302 
303 static struct ast_cli_entry cli_funcdevstate[] = {
304  AST_CLI_DEFINE(handle_cli_devstate_list, "List currently known custom device states"),
305  AST_CLI_DEFINE(handle_cli_devstate_change, "Change a custom device state"),
306 };
307 
309  .name = "DEVICE_STATE",
310  .read = devstate_read,
311  .write = devstate_write,
312 };
313 
315  .name = "HINT",
316  .read = hint_read,
317 };
318 
319 static int unload_module(void)
320 {
321  int res = 0;
322 
323  res |= ast_custom_function_unregister(&devstate_function);
324  res |= ast_custom_function_unregister(&hint_function);
325  res |= ast_devstate_prov_del("Custom");
326  res |= ast_cli_unregister_multiple(cli_funcdevstate, ARRAY_LEN(cli_funcdevstate));
327 
328  return res;
329 }
330 
331 static int load_module(void)
332 {
333  int res = 0;
334  struct ast_db_entry *db_entry, *db_tree;
335 
336  /* Populate the device state cache on the system with all of the currently
337  * known custom device states. */
338  db_entry = db_tree = ast_db_gettree(astdb_family, NULL);
339  for (; db_entry; db_entry = db_entry->next) {
340  const char *dev_name = strrchr(db_entry->key, '/') + 1;
341  if (dev_name <= (const char *) 1)
342  continue;
344  AST_DEVSTATE_CACHABLE, "Custom:%s\n", dev_name);
345  }
346  ast_db_freetree(db_tree);
347  db_tree = NULL;
348 
349  res |= ast_custom_function_register(&devstate_function);
350  res |= ast_custom_function_register(&hint_function);
352  res |= ast_cli_register_multiple(cli_funcdevstate, ARRAY_LEN(cli_funcdevstate));
353 
354  return res;
355 }
356 
357 AST_MODULE_INFO(ASTERISK_GPL_KEY, AST_MODFLAG_LOAD_ORDER, "Gets or sets a device state in the dialplan",
358  .load = load_module,
359  .unload = unload_module,
360  .load_pri = AST_MODPRI_DEVSTATE_PROVIDER,
361 );
enum sip_cc_notify_state state
Definition: chan_sip.c:842
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:5362
static char exten[AST_MAX_EXTENSION]
Definition: chan_alsa.c:109
Main Channel structure associated with a channel.
Definition: channel.h:742
#define AST_CLI_DEFINE(fn, txt,...)
Definition: cli.h:191
ast_device_state
Device States.
Definition: devicestate.h:51
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 ARRAY_LEN(a)
Definition: isdn_lib.c:42
char * strsep(char **str, const char *delims)
static struct ast_app_option hint_options[128]
int ast_cli_unregister_multiple(struct ast_cli_entry *e, int len)
Unregister multiple commands.
Definition: cli.c:2177
int ast_db_get(const char *family, const char *key, char *out, int outlen)
Get key value specified by family/key.
Definition: db.c:348
#define ast_test_flag(p, flag)
Definition: utils.h:63
Device state management.
descriptor for a cli entry.
Definition: cli.h:165
const int argc
Definition: cli.h:154
#define LOG_WARNING
Definition: logger.h:144
void ast_db_freetree(struct ast_db_entry *entry)
Free structure created by ast_db_gettree()
Definition: db.c:656
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
static int hint_read(struct ast_channel *chan, const char *cmd, char *data, char *buf, size_t len)
#define AST_DECLARE_APP_ARGS(name, arglist)
Declare a structure to hold an application&#39;s arguments.
Definition: app.h:572
Definition: cli.h:146
int ast_devstate_prov_del(const char *label)
Remove device state provider.
Definition: devicestate.c:389
int ast_devstate_prov_add(const char *label, ast_devstate_prov_cb_type callback)
Add device state provider.
Definition: devicestate.c:371
#define AST_MODULE_INFO(keystr, flags_to_set, desc, fields...)
Definition: module.h:374
#define END_OPTIONS
Definition: app.h:663
int value
Definition: syslog.c:39
void ast_cli(int fd, const char *fmt,...)
Definition: cli.c:105
int ast_custom_function_unregister(struct ast_custom_function *acf)
Unregister a custom function.
Definition: pbx.c:3814
Utility functions.
int args
This gets set in ast_cli_register()
Definition: cli.h:179
static int load_module(void)
char * ast_cli_complete(const char *word, const char *const choices[], int pos)
Definition: cli.c:1535
static struct ast_custom_function hint_function
struct ast_db_entry * next
Definition: astdb.h:31
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:516
enum ast_device_state ast_devstate_val(const char *val)
Convert device state from text to integer value.
Definition: devicestate.c:244
General Asterisk PBX channel definitions.
const int fd
Definition: cli.h:153
static enum ast_device_state custom_devstate_callback(const char *data)
static force_inline int attribute_pure ast_strlen_zero(const char *s)
Definition: strings.h:63
const int n
Definition: cli.h:159
Data structure associated with a custom dialplan function.
Definition: pbx.h:95
A set of macros to manage forward-linked lists.
Core PBX routines and definitions.
const char *const * argv
Definition: cli.h:155
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:239
#define LOG_ERROR
Definition: logger.h:155
static struct @350 args
struct ast_db_entry * ast_db_gettree(const char *family, const char *keytree)
Get a list of values within the astdb tree If family is specified, only those keys will be returned...
Definition: db.c:631
#define CLI_SHOWUSAGE
Definition: cli.h:44
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)
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
Definition: astdb.h:30
static char * handle_cli_devstate_change(struct ast_cli_entry *e, int cmd, struct ast_cli_args *a)
#define CLI_FAILURE
Definition: cli.h:45
char data[0]
Definition: astdb.h:33
char * command
Definition: cli.h:180
static int unload_module(void)
const char * word
Definition: cli.h:157
static int devstate_read(struct ast_channel *chan, const char *cmd, char *data, char *buf, size_t len)
static const char astdb_family[]
Structure used to handle boolean flags.
Definition: utils.h:200
const char * usage
Definition: cli.h:171
#define CLI_SUCCESS
Definition: cli.h:43
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:223
int ast_cli_register_multiple(struct ast_cli_entry *e, int len)
Register multiple commands.
Definition: cli.c:2167
const int pos
Definition: cli.h:158
static int devstate_write(struct ast_channel *chan, const char *cmd, char *data, const char *value)
Application convenience functions, designed to give consistent look and feel to Asterisk apps...
const char * name
Definition: pbx.h:96
int ast_db_put(const char *family, const char *key, const char *value)
Store value addressed by family/key.
Definition: db.c:260
#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
#define ASTERISK_GPL_KEY
The text the key() function should return.
Definition: module.h:38
Persistant data storage (akin to *doze registry)
#define ast_custom_function_register(acf)
Register a custom function.
Definition: pbx.h:1164
#define BEGIN_OPTIONS
Definition: app.h:662
static struct ast_cli_entry cli_funcdevstate[]
#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
char * key
Definition: astdb.h:32