git migration: Refactor the ASTERISK_FILE_VERSION macro
[asterisk/asterisk.git] / funcs / func_devstate.c
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_REGISTER_FILE()
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 {
106         ast_copy_string(buf, ast_devstate_str(ast_device_state(data)), len);
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
144 AST_APP_OPTIONS(hint_options, BEGIN_OPTIONS
145         AST_APP_OPTION('n', HINT_OPT_NAME),
146 END_OPTIONS );
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;
151         AST_DECLARE_APP_ARGS(args,
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
163         AST_STANDARD_APP_ARGS(args, data);
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
308 static struct ast_custom_function devstate_function = {
309         .name = "DEVICE_STATE",
310         .read = devstate_read,
311         .write = devstate_write,
312 };
313
314 static struct ast_custom_function hint_function = {
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;
343                 ast_devstate_changed(ast_devstate_val(db_entry->data),
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);
351         res |= ast_devstate_prov_add("Custom", custom_devstate_callback);
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         .support_level = AST_MODULE_SUPPORT_CORE,
359         .load = load_module,
360         .unload = unload_module,
361         .load_pri = AST_MODPRI_DEVSTATE_PROVIDER,
362 );