Asterisk - The Open Source Telephony Project GIT-master-2de1a68
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#include "asterisk/module.h"
40#include "asterisk/channel.h"
41#include "asterisk/pbx.h"
42#include "asterisk/utils.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.</para>
94 <example title="Hint for extension 1234">
95 same => n,NoOp(Hint for Extension 1234 is ${HINT(1234)})
96 </example>
97 </description>
98 </function>
99 ***/
100
101
102static const char astdb_family[] = "CustomDevstate";
103
104static int devstate_read(struct ast_channel *chan, const char *cmd, char *data, char *buf, size_t len)
105{
107
108 return 0;
109}
110
111static 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
134
135 ast_devstate_changed(state_val, AST_DEVSTATE_CACHABLE, "Custom:%s", data);
136
137 return 0;
138}
139
140enum {
141 HINT_OPT_NAME = (1 << 0),
142};
143
147
148static 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);
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, "@");
173 context = "default";
174
175 if (!ast_strlen_zero(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
186static 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
196static 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
240static 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
297
298 ast_devstate_changed(state_val, AST_DEVSTATE_CACHABLE, "Custom:%s", dev);
299
300 return CLI_SUCCESS;
301}
302
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
319static int unload_module(void)
320{
321 int res = 0;
322
325 res |= ast_devstate_prov_del("Custom");
327
328 return res;
329}
330
331static 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", dev_name);
345 }
346 ast_db_freetree(db_tree);
347 db_tree = NULL;
348
353
354 return res;
355}
356
357AST_MODULE_INFO(ASTERISK_GPL_KEY, AST_MODFLAG_LOAD_ORDER, "Gets or sets a device state in the dialplan",
358 .support_level = AST_MODULE_SUPPORT_CORE,
359 .load = load_module,
360 .unload = unload_module,
Persistent data storage (akin to *doze registry)
int ast_db_put(const char *family, const char *key, const char *value)
Store value addressed by family/key.
Definition: main/db.c:342
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:427
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:610
void ast_db_freetree(struct ast_db_entry *entry)
Free structure created by ast_db_gettree()
Definition: main/db.c:677
Asterisk main include file. File version handling, generic pbx functions.
#define ast_log
Definition: astobj2.c:42
enum cc_state state
Definition: ccss.c:393
General Asterisk PBX channel definitions.
Standard Command Line Interface.
#define CLI_SHOWUSAGE
Definition: cli.h:45
#define CLI_SUCCESS
Definition: cli.h:44
int ast_cli_unregister_multiple(struct ast_cli_entry *e, int len)
Unregister multiple commands.
Definition: clicompat.c:30
#define AST_CLI_DEFINE(fn, txt,...)
Definition: cli.h:197
void ast_cli(int fd, const char *fmt,...)
Definition: clicompat.c:6
char * ast_cli_complete(const char *word, const char *const choices[], int pos)
Definition: main/cli.c:1843
@ CLI_INIT
Definition: cli.h:152
@ CLI_GENERATE
Definition: cli.h:153
#define CLI_FAILURE
Definition: cli.h:46
#define ast_cli_register_multiple(e, len)
Register multiple commands.
Definition: cli.h:265
Device state management.
int ast_devstate_prov_del(const char *label)
Remove device state provider.
Definition: devicestate.c:418
@ AST_DEVSTATE_CACHABLE
Definition: devicestate.h:70
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
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
int ast_devstate_prov_add(const char *label, ast_devstate_prov_cb_type callback)
Add device state provider.
Definition: devicestate.c:391
ast_device_state
Device States.
Definition: devicestate.h:52
@ AST_DEVICE_UNKNOWN
Definition: devicestate.h:53
char buf[BUFSIZE]
Definition: eagi_proxy.c:66
static int devstate_write(struct ast_channel *chan, const char *cmd, char *data, const char *value)
static char * handle_cli_devstate_change(struct ast_cli_entry *e, int cmd, struct ast_cli_args *a)
static struct ast_cli_entry cli_funcdevstate[]
static int hint_read(struct ast_channel *chan, const char *cmd, char *data, char *buf, size_t len)
@ HINT_OPT_NAME
static enum ast_device_state custom_devstate_callback(const char *data)
static struct ast_custom_function devstate_function
static struct ast_custom_function hint_function
static char * handle_cli_devstate_list(struct ast_cli_entry *e, int cmd, struct ast_cli_args *a)
static const char astdb_family[]
static int load_module(void)
static int unload_module(void)
static int devstate_read(struct ast_channel *chan, const char *cmd, char *data, char *buf, size_t len)
static const struct ast_app_option hint_options[128]
static int len(struct ast_channel *chan, const char *cmd, char *data, char *buf, size_t buflen)
Application convenience functions, designed to give consistent look and feel to Asterisk apps.
#define AST_APP_ARG(name)
Define an application argument.
#define END_OPTIONS
#define AST_APP_OPTIONS(holder, options...)
Declares an array of options for an application.
#define AST_DECLARE_APP_ARGS(name, arglist)
Declare a structure to hold an application's arguments.
#define BEGIN_OPTIONS
#define AST_STANDARD_APP_ARGS(args, parse)
Performs the 'standard' argument separation process for an application.
#define AST_APP_OPTION(option, flagno)
Declares an application option that does not accept an argument.
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:3056
char * strsep(char **str, const char *delims)
#define LOG_ERROR
#define LOG_WARNING
A set of macros to manage forward-linked lists.
Asterisk module definitions.
@ AST_MODFLAG_LOAD_ORDER
Definition: module.h:317
#define AST_MODULE_INFO(keystr, flags_to_set, desc, fields...)
Definition: module.h:543
@ AST_MODPRI_DEVSTATE_PROVIDER
Definition: module.h:329
@ AST_MODULE_SUPPORT_CORE
Definition: module.h:121
#define ASTERISK_GPL_KEY
The text the key() function should return.
Definition: module.h:46
Core PBX routines and definitions.
#define ast_custom_function_register(acf)
Register a custom function.
Definition: pbx.h:1558
int ast_custom_function_unregister(struct ast_custom_function *acf)
Unregister a custom function.
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:4137
#define NULL
Definition: resample.c:96
static force_inline int attribute_pure ast_strlen_zero(const char *s)
Definition: strings.h:65
void ast_copy_string(char *dst, const char *src, size_t size)
Size-limited null-terminating string copy.
Definition: strings.h:425
Main Channel structure associated with a channel.
descriptor for a cli entry.
Definition: cli.h:171
int args
This gets set in ast_cli_register()
Definition: cli.h:185
char * command
Definition: cli.h:186
const char * usage
Definition: cli.h:177
Data structure associated with a custom dialplan function.
Definition: pbx.h:118
const char * name
Definition: pbx.h:119
Definition: astdb.h:31
struct ast_db_entry * next
Definition: astdb.h:32
char * key
Definition: astdb.h:33
char data[0]
Definition: astdb.h:34
Structure used to handle boolean flags.
Definition: utils.h:199
int value
Definition: syslog.c:37
const char * args
static struct test_options options
static struct test_val a
Utility functions.
#define ast_test_flag(p, flag)
Definition: utils.h:63
#define ARRAY_LEN(a)
Definition: utils.h:666