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_FILE_VERSION(__FILE__, "$Revision$")
  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, "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         ast_db_get(astdb_family, data, buf, sizeof(buf));
 191
 192         return ast_devstate_val(buf);
 193 }
 194
 195 static char *handle_cli_devstate_list(struct ast_cli_entry *e, int cmd, struct ast_cli_args *a)
 196 {
 197         struct ast_db_entry *db_entry, *db_tree;
 198
 199         switch (cmd) {
 200         case CLI_INIT:
 201                 e->command = "devstate list";
 202                 e->usage =
 203                         "Usage: devstate list\n"
 204                         "       List all custom device states that have been set by using\n"
 205                         "       the DEVICE_STATE dialplan function.\n";
 206                 return NULL;
 207         case CLI_GENERATE:
 208                 return NULL;
 209         }
 210
 211         if (a->argc != e->args)
 212                 return CLI_SHOWUSAGE;
 213
 214         ast_cli(a->fd, "\n"
 215                 "---------------------------------------------------------------------\n"
 216                 "--- Custom Device States --------------------------------------------\n"
 217                 "---------------------------------------------------------------------\n"
 218                 "---\n");
 219
 220         db_entry = db_tree = ast_db_gettree(astdb_family, NULL);
 221         for (; db_entry; db_entry = db_entry->next) {
 222                 const char *dev_name = strrchr(db_entry->key, '/') + 1;
 223                 if (dev_name <= (const char *) 1)
 224                         continue;
 225                 ast_cli(a->fd, "--- Name: 'Custom:%s'  State: '%s'\n"
 226                                "---\n", dev_name, db_entry->data);
 227         }
 228         ast_db_freetree(db_tree);
 229         db_tree = NULL;
 230
 231         ast_cli(a->fd,
 232                 "---------------------------------------------------------------------\n"
 233                 "---------------------------------------------------------------------\n"
 234                 "\n");
 235
 236         return CLI_SUCCESS;
 237 }
 238
 239 static char *handle_cli_devstate_change(struct ast_cli_entry *e, int cmd, struct ast_cli_args *a)
 240 {
 241     size_t len;
 242         const char *dev, *state;
 243         enum ast_device_state state_val;
 244
 245         switch (cmd) {
 246         case CLI_INIT:
 247                 e->command = "devstate change";
 248                 e->usage =
 249                         "Usage: devstate change <device> <state>\n"
 250                         "       Change a custom device to a new state.\n"
 251                         "       The possible values for the state are:\n"
 252                         "UNKNOWN | NOT_INUSE | INUSE | BUSY | INVALID | UNAVAILABLE | RINGING\n"
 253                         "RINGINUSE | ONHOLD\n",
 254                         "\n"
 255                         "Examples:\n"
 256                         "       devstate change Custom:mystate1 INUSE\n"
 257                         "       devstate change Custom:mystate1 NOT_INUSE\n"
 258                         "       \n";
 259                 return NULL;
 260         case CLI_GENERATE:
 261         {
 262                 static const char * const cmds[] = { "UNKNOWN", "NOT_INUSE", "INUSE", "BUSY",
 263                                                      "UNAVAILABLE", "RINGING", "RINGINUSE", "ONHOLD", NULL };
 264
 265                 if (a->pos == e->args + 1)
 266                         return ast_cli_complete(a->word, cmds, a->n);
 267
 268                 return NULL;
 269         }
 270         }
 271
 272         if (a->argc != e->args + 2)
 273                 return CLI_SHOWUSAGE;
 274
 275         len = strlen("Custom:");
 276         dev = a->argv[e->args];
 277         state = a->argv[e->args + 1];
 278
 279         if (strncasecmp(dev, "Custom:", len)) {
 280                 ast_cli(a->fd, "The devstate command can only be used to set 'Custom:' device state!\n");
 281                 return CLI_FAILURE;
 282         }
 283
 284         dev += len;
 285         if (ast_strlen_zero(dev))
 286                 return CLI_SHOWUSAGE;
 287
 288         state_val = ast_devstate_val(state);
 289
 290         if (state_val == AST_DEVICE_UNKNOWN)
 291                 return CLI_SHOWUSAGE;
 292
 293         ast_cli(a->fd, "Changing %s to %s\n", dev, state);
 294
 295         ast_db_put(astdb_family, dev, state);
 296
 297         ast_devstate_changed(state_val, "Custom:%s", dev);
 298
 299         return CLI_SUCCESS;
 300 }
 301
 302 static struct ast_cli_entry cli_funcdevstate[] = {
 303         AST_CLI_DEFINE(handle_cli_devstate_list, "List currently known custom device states"),
 304         AST_CLI_DEFINE(handle_cli_devstate_change, "Change a custom device state"),
 305 };
 306
 307 static struct ast_custom_function devstate_function = {
 308         .name = "DEVICE_STATE",
 309         .read = devstate_read,
 310         .write = devstate_write,
 311 };
 312
 313 static struct ast_custom_function hint_function = {
 314         .name = "HINT",
 315         .read = hint_read,
 316 };
 317
 318 static int unload_module(void)
 319 {
 320         int res = 0;
 321
 322         res |= ast_custom_function_unregister(&devstate_function);
 323         res |= ast_custom_function_unregister(&hint_function);
 324         res |= ast_devstate_prov_del("Custom");
 325         res |= ast_cli_unregister_multiple(cli_funcdevstate, ARRAY_LEN(cli_funcdevstate));
 326
 327         return res;
 328 }
 329
 330 static int load_module(void)
 331 {
 332         int res = 0;
 333         struct ast_db_entry *db_entry, *db_tree;
 334
 335         /* Populate the device state cache on the system with all of the currently
 336          * known custom device states. */
 337         db_entry = db_tree = ast_db_gettree(astdb_family, NULL);
 338         for (; db_entry; db_entry = db_entry->next) {
 339                 const char *dev_name = strrchr(db_entry->key, '/') + 1;
 340                 if (dev_name <= (const char *) 1)
 341                         continue;
 342                 ast_devstate_changed(ast_devstate_val(db_entry->data),
 343                         "Custom:%s\n", dev_name);
 344         }
 345         ast_db_freetree(db_tree);
 346         db_tree = NULL;
 347
 348         res |= ast_custom_function_register(&devstate_function);
 349         res |= ast_custom_function_register(&hint_function);
 350         res |= ast_devstate_prov_add("Custom", custom_devstate_callback);
 351         res |= ast_cli_register_multiple(cli_funcdevstate, ARRAY_LEN(cli_funcdevstate));
 352
 353         return res;
 354 }
 355
 356 AST_MODULE_INFO(ASTERISK_GPL_KEY, AST_MODFLAG_LOAD_ORDER, "Gets or sets a device state in the dialplan",
 357         .load = load_module,
 358         .unload = unload_module,
 359         .load_pri = AST_MODPRI_DEVSTATE_PROVIDER,
 360 );