include/asterisk/pbx.h

   1 /*
   2  * Asterisk -- An open source telephony toolkit.
   3  *
   4  * Copyright (C) 1999 - 2006, Digium, Inc.
   5  *
   6  * Mark Spencer <markster@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  * \brief Core PBX routines and definitions.
  21  */
  22
  23 #ifndef _ASTERISK_PBX_H
  24 #define _ASTERISK_PBX_H
  25
  26 #include "asterisk/sched.h"
  27 #include "asterisk/chanvars.h"
  28 #include "asterisk/hashtab.h"
  29
  30 #if defined(__cplusplus) || defined(c_plusplus)
  31 extern "C" {
  32 #endif
  33
  34 #define AST_MAX_APP     32      /*!< Max length of an application */
  35
  36 #define AST_PBX_KEEP    0
  37 #define AST_PBX_REPLACE 1
  38
  39 /*! \brief Special return values from applications to the PBX { */
  40 #define AST_PBX_HANGUP          -1      /*!< Jump to the 'h' exten */
  41 #define AST_PBX_OK              0       /*!< No errors */
  42 #define AST_PBX_ERROR           1       /*!< Jump to the 'e' exten */
  43 #define AST_PBX_KEEPALIVE       10      /*!< Destroy the thread, but don't hang up the channel */
  44 #define AST_PBX_NO_HANGUP_PEER  11
  45 #define AST_PBX_INCOMPLETE      12      /*!< Return to PBX matching, allowing more digits for the extension */
  46 /*! } */
  47
  48 #define PRIORITY_HINT   -1      /*!< Special Priority for a hint */
  49
  50 /*! \brief Extension states
  51         \note States can be combined
  52         - \ref AstExtState
  53 */
  54 enum ast_extension_states {
  55         AST_EXTENSION_REMOVED = -2,     /*!< Extension removed */
  56         AST_EXTENSION_DEACTIVATED = -1, /*!< Extension hint removed */
  57         AST_EXTENSION_NOT_INUSE = 0,    /*!< No device INUSE or BUSY  */
  58         AST_EXTENSION_INUSE = 1 << 0,   /*!< One or more devices INUSE */
  59         AST_EXTENSION_BUSY = 1 << 1,    /*!< All devices BUSY */
  60         AST_EXTENSION_UNAVAILABLE = 1 << 2, /*!< All devices UNAVAILABLE/UNREGISTERED */
  61         AST_EXTENSION_RINGING = 1 << 3, /*!< All devices RINGING */
  62         AST_EXTENSION_ONHOLD = 1 << 4,  /*!< All devices ONHOLD */
  63 };
  64
  65
  66 struct ast_context;
  67 struct ast_exten;
  68 struct ast_include;
  69 struct ast_ignorepat;
  70 struct ast_sw;
  71
  72 /*! \brief Typedef for devicestate and hint callbacks */
  73 typedef int (*ast_state_cb_type)(char *context, char* id, enum ast_extension_states state, void *data);
  74
  75 /*! \brief Data structure associated with a custom dialplan function */
  76 struct ast_custom_function {
  77         const char *name;               /*!< Name */
  78         const char *synopsis;           /*!< Short description for "show functions" */
  79         const char *desc;               /*!< Help text that explains it all */
  80         const char *syntax;             /*!< Syntax description */
  81         int (*read)(struct ast_channel *, const char *, char *, char *, size_t);        /*!< Read function, if read is supported */
  82         int (*write)(struct ast_channel *, const char *, char *, const char *);         /*!< Write function, if write is supported */
  83         struct ast_module *mod;         /*!< Module this custom function belongs to */
  84         AST_RWLIST_ENTRY(ast_custom_function) acflist;
  85 };
  86
  87 /*! \brief All switch functions have the same interface, so define a type for them */
  88 typedef int (ast_switch_f)(struct ast_channel *chan, const char *context,
  89         const char *exten, int priority, const char *callerid, const char *data);
  90
  91 /*!< Data structure associated with an Asterisk switch */
  92 struct ast_switch {
  93         AST_LIST_ENTRY(ast_switch) list;
  94         const char *name;                       /*!< Name of the switch */
  95         const char *description;                /*!< Description of the switch */
  96
  97         ast_switch_f *exists;
  98         ast_switch_f *canmatch;
  99         ast_switch_f *exec;
 100         ast_switch_f *matchmore;
 101 };
 102
 103 struct ast_timing {
 104         int hastime;                            /*!< If time construct exists */
 105         unsigned int monthmask;                 /*!< Mask for month */
 106         unsigned int daymask;                   /*!< Mask for date */
 107         unsigned int dowmask;                   /*!< Mask for day of week (mon-sun) */
 108         unsigned int minmask[24];               /*!< Mask for minute */
 109 };
 110
 111 int ast_build_timing(struct ast_timing *i, const char *info);
 112 int ast_check_timing(const struct ast_timing *i);
 113
 114 struct ast_pbx {
 115         int dtimeoutms;                         /*!< Timeout between digits (milliseconds) */
 116         int rtimeoutms;                         /*!< Timeout for response (milliseconds) */
 117 };
 118
 119
 120 /*!
 121  * \brief Register an alternative dialplan switch
 122  *
 123  * \param sw switch to register
 124  *
 125  * This function registers a populated ast_switch structure with the
 126  * asterisk switching architecture.
 127  *
 128  * \return 0 on success, and other than 0 on failure
 129  */
 130 int ast_register_switch(struct ast_switch *sw);
 131
 132 /*!
 133  * \brief Unregister an alternative switch
 134  *
 135  * \param sw switch to unregister
 136  *
 137  * Unregisters a switch from asterisk.
 138  *
 139  * \return nothing
 140  */
 141 void ast_unregister_switch(struct ast_switch *sw);
 142
 143 /*!
 144  * \brief Look up an application
 145  *
 146  * \param app name of the app
 147  *
 148  * This function searches for the ast_app structure within
 149  * the apps that are registered for the one with the name
 150  * you passed in.
 151  *
 152  * \return the ast_app structure that matches on success, or NULL on failure
 153  */
 154 struct ast_app *pbx_findapp(const char *app);
 155
 156 /*!
 157  * \brief Execute an application
 158  *
 159  * \param c channel to execute on
 160  * \param app which app to execute
 161  * \param data the data passed into the app
 162  *
 163  * This application executes an application on a given channel.  It
 164  * saves the stack and executes the given application passing in
 165  * the given data.
 166  *
 167  * \return 0 on success, and -1 on failure
 168  */
 169 int pbx_exec(struct ast_channel *c, struct ast_app *app, void *data);
 170
 171 /*!
 172  * \brief Register a new context or find an existing one
 173  *
 174  * \param extcontexts pointer to the ast_context structure pointer
 175  * \param exttable pointer to the hashtable that contains all the elements in extcontexts
 176  * \param name name of the new context
 177  * \param registrar registrar of the context
 178  *
 179  * This function allows you to play in two environments: the global contexts (active dialplan)
 180  * or an external context set of your choosing. To act on the external set, make sure extcontexts
 181  * and exttable are set; for the globals, make sure both extcontexts and exttable are NULL.
 182  *
 183  * This will first search for a context with your name.  If it exists already, it will not
 184  * create a new one.  If it does not exist, it will create a new one with the given name
 185  * and registrar.
 186  *
 187  * \return NULL on failure, and an ast_context structure on success
 188  */
 189 struct ast_context *ast_context_find_or_create(struct ast_context **extcontexts, struct ast_hashtab *exttable, const char *name, const char *registrar);
 190
 191 /*!
 192  * \brief Merge the temporary contexts into a global contexts list and delete from the
 193  *        global list the ones that are being added
 194  *
 195  * \param extcontexts pointer to the ast_context structure
 196  * \param exttable pointer to the ast_hashtab structure that contains all the elements in extcontexts
 197  * \param registrar of the context; if it's set the routine will delete all contexts
 198  *        that belong to that registrar; if NULL only the contexts that are specified
 199  *        in extcontexts
 200  */
 201 void ast_merge_contexts_and_delete(struct ast_context **extcontexts, struct ast_hashtab *exttable, const char *registrar);
 202
 203 /*!
 204  * \brief Destroy a context (matches the specified context (or ANY context if NULL)
 205  *
 206  * \param con context to destroy
 207  * \param registrar who registered it
 208  *
 209  * You can optionally leave out either parameter.  It will find it
 210  * based on either the ast_context or the registrar name.
 211  *
 212  * \return nothing
 213  */
 214 void ast_context_destroy(struct ast_context *con, const char *registrar);
 215
 216 /*!
 217  * \brief Find a context
 218  *
 219  * \param name name of the context to find
 220  *
 221  * Will search for the context with the given name.
 222  *
 223  * \return the ast_context on success, NULL on failure.
 224  */
 225 struct ast_context *ast_context_find(const char *name);
 226
 227 /*! \brief The result codes when starting the PBX on a channelwith \see ast_pbx_start.
 228         AST_PBX_CALL_LIMIT refers to the maxcalls call limit in asterisk.conf
 229  */
 230 enum ast_pbx_result {
 231         AST_PBX_SUCCESS = 0,
 232         AST_PBX_FAILED = -1,
 233         AST_PBX_CALL_LIMIT = -2,
 234 };
 235
 236 /*!
 237  * \brief Create a new thread and start the PBX
 238  *
 239  * \param c channel to start the pbx on
 240  *
 241  * \see ast_pbx_run for a synchronous function to run the PBX in the
 242  * current thread, as opposed to starting a new one.
 243  *
 244  * \retval Zero on success
 245  * \retval non-zero on failure
 246  */
 247 enum ast_pbx_result ast_pbx_start(struct ast_channel *c);
 248
 249 /*!
 250  * \brief Execute the PBX in the current thread
 251  *
 252  * \param c channel to run the pbx on
 253  *
 254  * This executes the PBX on a given channel. It allocates a new
 255  * PBX structure for the channel, and provides all PBX functionality.
 256  * See ast_pbx_start for an asynchronous function to run the PBX in a
 257  * new thread as opposed to the current one.
 258  *
 259  * \retval Zero on success
 260  * \retval non-zero on failure
 261  */
 262 enum ast_pbx_result ast_pbx_run(struct ast_channel *c);
 263
 264 /*!
 265  * \brief Add and extension to an extension context.
 266  *
 267  * \param context context to add the extension to
 268  * \param replace
 269  * \param extension extension to add
 270  * \param priority priority level of extension addition
 271  * \param label extension label
 272  * \param callerid pattern to match CallerID, or NULL to match any CallerID
 273  * \param application application to run on the extension with that priority level
 274  * \param data data to pass to the application
 275  * \param datad
 276  * \param registrar who registered the extension
 277  *
 278  * \retval 0 success
 279  * \retval -1 failure
 280  */
 281 int ast_add_extension(const char *context, int replace, const char *extension,
 282         int priority, const char *label, const char *callerid,
 283         const char *application, void *data, void (*datad)(void *), const char *registrar);
 284
 285 /*!
 286  * \brief Add an extension to an extension context, this time with an ast_context *.
 287  *
 288  * \note For details about the arguments, check ast_add_extension()
 289  */
 290 int ast_add_extension2(struct ast_context *con, int replace, const char *extension,
 291         int priority, const char *label, const char *callerid,
 292         const char *application, void *data, void (*datad)(void *), const char *registrar);
 293
 294
 295 /*!
 296  * \brief Uses hint and devicestate callback to get the state of an extension
 297  *
 298  * \param c this is not important
 299  * \param context which context to look in
 300  * \param exten which extension to get state
 301  *
 302  * \return extension state as defined in the ast_extension_states enum
 303  */
 304 int ast_extension_state(struct ast_channel *c, const char *context, const char *exten);
 305
 306 /*!
 307  * \brief Return string representation of the state of an extension
 308  *
 309  * \param extension_state is the numerical state delivered by ast_extension_state
 310  *
 311  * \return the state of an extension as string
 312  */
 313 const char *ast_extension_state2str(int extension_state);
 314
 315 /*!
 316  * \brief Registers a state change callback
 317  *
 318  * \param context which context to look in
 319  * \param exten which extension to get state
 320  * \param callback callback to call if state changed
 321  * \param data to pass to callback
 322  *
 323  * The callback is called if the state of an extension is changed.
 324  *
 325  * \retval -1 on failure
 326  * \retval ID on success
 327  */
 328 int ast_extension_state_add(const char *context, const char *exten,
 329                             ast_state_cb_type callback, void *data);
 330
 331 /*!
 332  * \brief Deletes a registered state change callback by ID
 333  *
 334  * \param id of the callback to delete
 335  * \param callback callback
 336  *
 337  * Removes the callback from list of callbacks
 338  *
 339  * \retval 0 success
 340  * \retval -1 failure
 341  */
 342 int ast_extension_state_del(int id, ast_state_cb_type callback);
 343
 344 /*!
 345  * \brief If an extension hint exists, return non-zero
 346  *
 347  * \param hint buffer for hint
 348  * \param maxlen size of hint buffer
 349  * \param name buffer for name portion of hint
 350  * \param maxnamelen size of name buffer
 351  * \param c this is not important
 352  * \param context which context to look in
 353  * \param exten which extension to search for
 354  *
 355  * \return If an extension within the given context with the priority PRIORITY_HINT
 356  * is found a non zero value will be returned.
 357  * Otherwise, 0 is returned.
 358  */
 359 int ast_get_hint(char *hint, int maxlen, char *name, int maxnamelen,
 360         struct ast_channel *c, const char *context, const char *exten);
 361
 362 /*!
 363  * \brief Determine whether an extension exists
 364  *
 365  * \param c this is not important
 366  * \param context which context to look in
 367  * \param exten which extension to search for
 368  * \param priority priority of the action within the extension
 369  * \param callerid callerid to search for
 370  *
 371  * \return If an extension within the given context(or callerid) with the given priority
 372  *         is found a non zero value will be returned. Otherwise, 0 is returned.
 373  */
 374 int ast_exists_extension(struct ast_channel *c, const char *context, const char *exten,
 375         int priority, const char *callerid);
 376
 377 /*!
 378  * \brief Find the priority of an extension that has the specified label
 379  *
 380  * \param c this is not important
 381  * \param context which context to look in
 382  * \param exten which extension to search for
 383  * \param label label of the action within the extension to match to priority
 384  * \param callerid callerid to search for
 385  *
 386  * \retval the priority which matches the given label in the extension
 387  * \retval -1 if not found.
 388  */
 389 int ast_findlabel_extension(struct ast_channel *c, const char *context,
 390         const char *exten, const char *label, const char *callerid);
 391
 392 /*!
 393  * \brief Find the priority of an extension that has the specified label
 394  *
 395  * \note This function is the same as ast_findlabel_extension, except that it accepts
 396  * a pointer to an ast_context structure to specify the context instead of the
 397  * name of the context. Otherwise, the functions behave the same.
 398  */
 399 int ast_findlabel_extension2(struct ast_channel *c, struct ast_context *con,
 400         const char *exten, const char *label, const char *callerid);
 401
 402 /*!
 403  * \brief Looks for a valid matching extension
 404  *
 405  * \param c not really important
 406  * \param context context to serach within
 407  * \param exten extension to check
 408  * \param priority priority of extension path
 409  * \param callerid callerid of extension being searched for
 410  *
 411  * \return If "exten" *could be* a valid extension in this context with or without
 412  * some more digits, return non-zero.  Basically, when this returns 0, no matter
 413  * what you add to exten, it's not going to be a valid extension anymore
 414  */
 415 int ast_canmatch_extension(struct ast_channel *c, const char *context,
 416         const char *exten, int priority, const char *callerid);
 417
 418 /*!
 419  * \brief Looks to see if adding anything to this extension might match something. (exists ^ canmatch)
 420  *
 421  * \param c not really important XXX
 422  * \param context context to serach within
 423  * \param exten extension to check
 424  * \param priority priority of extension path
 425  * \param callerid callerid of extension being searched for
 426  *
 427  * \return If "exten" *could match* a valid extension in this context with
 428  * some more digits, return non-zero.  Does NOT return non-zero if this is
 429  * an exact-match only.  Basically, when this returns 0, no matter
 430  * what you add to exten, it's not going to be a valid extension anymore
 431  */
 432 int ast_matchmore_extension(struct ast_channel *c, const char *context,
 433         const char *exten, int priority, const char *callerid);
 434
 435 /*!
 436  * \brief Determine if a given extension matches a given pattern (in NXX format)
 437  *
 438  * \param pattern pattern to match
 439  * \param extension extension to check against the pattern.
 440  *
 441  * Checks whether or not the given extension matches the given pattern.
 442  *
 443  * \retval 1 on match
 444  * \retval 0 on failure
 445  */
 446 int ast_extension_match(const char *pattern, const char *extension);
 447
 448 int ast_extension_close(const char *pattern, const char *data, int needmore);
 449
 450 /*!
 451  * \brief Determine if one extension should match before another
 452  *
 453  * \param a extension to compare with b
 454  * \param b extension to compare with a
 455  *
 456  * Checks whether or extension a should match before extension b
 457  *
 458  * \retval 0 if the two extensions have equal matching priority
 459  * \retval 1 on a > b
 460  * \retval -1 on a < b
 461  */
 462 int ast_extension_cmp(const char *a, const char *b);
 463
 464 /*!
 465  * \brief Launch a new extension (i.e. new stack)
 466  *
 467  * \param c not important
 468  * \param context which context to generate the extension within
 469  * \param exten new extension to add
 470  * \param priority priority of new extension
 471  * \param callerid callerid of extension
 472  * \param found
 473  * \param combined_find_spawn
 474  *
 475  * This adds a new extension to the asterisk extension list.
 476  *
 477  * \retval 0 on success
 478  * \retval -1 on failure.
 479  */
 480 int ast_spawn_extension(struct ast_channel *c, const char *context,
 481       const char *exten, int priority, const char *callerid, int *found, int combined_find_spawn);
 482
 483 /*!
 484  * \brief Add a context include
 485  *
 486  * \param context context to add include to
 487  * \param include new include to add
 488  * \param registrar who's registering it
 489  *
 490  * Adds an include taking a char * string as the context parameter
 491  *
 492  * \retval 0 on success
 493  * \retval -1 on error
 494 */
 495 int ast_context_add_include(const char *context, const char *include,
 496         const char *registrar);
 497
 498 /*!
 499  * \brief Add a context include
 500  *
 501  * \param con context to add the include to
 502  * \param include include to add
 503  * \param registrar who registered the context
 504  *
 505  * Adds an include taking a struct ast_context as the first parameter
 506  *
 507  * \retval 0 on success
 508  * \retval -1 on failure
 509  */
 510 int ast_context_add_include2(struct ast_context *con, const char *include,
 511         const char *registrar);
 512
 513 /*!
 514  * \brief Remove a context include
 515  *
 516  * \note See ast_context_add_include for information on arguments
 517  *
 518  * \retval 0 on success
 519  * \retval -1 on failure
 520  */
 521 int ast_context_remove_include(const char *context, const char *include,
 522         const char *registrar);
 523
 524 /*!
 525  * \brief Removes an include by an ast_context structure
 526  *
 527  * \note See ast_context_add_include2 for information on arguments
 528  *
 529  * \retval 0 on success
 530  * \retval -1 on success
 531  */
 532 int ast_context_remove_include2(struct ast_context *con, const char *include,
 533         const char *registrar);
 534
 535 /*!
 536  * \brief Verifies includes in an ast_contect structure
 537  *
 538  * \param con context in which to verify the includes
 539  *
 540  * \retval 0 if no problems found
 541  * \retval -1 if there were any missing context
 542  */
 543 int ast_context_verify_includes(struct ast_context *con);
 544
 545 /*!
 546  * \brief Add a switch
 547  *
 548  * \param context context to which to add the switch
 549  * \param sw switch to add
 550  * \param data data to pass to switch
 551  * \param eval whether to evaluate variables when running switch
 552  * \param registrar whoever registered the switch
 553  *
 554  * This function registers a switch with the asterisk switch architecture
 555  *
 556  * \retval 0 on success
 557  * \retval -1 on failure
 558  */
 559 int ast_context_add_switch(const char *context, const char *sw, const char *data,
 560         int eval, const char *registrar);
 561
 562 /*!
 563  * \brief Adds a switch (first param is a ast_context)
 564  *
 565  * \note See ast_context_add_switch() for argument information, with the exception of
 566  *       the first argument. In this case, it's a pointer to an ast_context structure
 567  *       as opposed to the name.
 568  */
 569 int ast_context_add_switch2(struct ast_context *con, const char *sw, const char *data,
 570         int eval, const char *registrar);
 571
 572 /*!
 573  * \brief Remove a switch
 574  *
 575  * Removes a switch with the given parameters
 576  *
 577  * \retval 0 on success
 578  * \retval -1 on failure
 579  */
 580 int ast_context_remove_switch(const char *context, const char *sw,
 581         const char *data, const char *registrar);
 582
 583 int ast_context_remove_switch2(struct ast_context *con, const char *sw,
 584         const char *data, const char *registrar);
 585
 586 /*!
 587  * \brief Simply remove extension from context
 588  *
 589  * \param context context to remove extension from
 590  * \param extension which extension to remove
 591  * \param priority priority of extension to remove (0 to remove all)
 592  * \param callerid NULL to remove all; non-NULL to match a single record per priority
 593  * \param matchcid non-zero to match callerid element (if non-NULL); 0 to match default case
 594  * \param registrar registrar of the extension
 595  *
 596  * This function removes an extension from a given context.
 597  *
 598  * \retval 0 on success
 599  * \retval -1 on failure
 600  */
 601 int ast_context_remove_extension(const char *context, const char *extension, int priority,
 602         const char *registrar);
 603
 604 int ast_context_remove_extension2(struct ast_context *con, const char *extension,
 605         int priority, const char *registrar, int already_locked);
 606
 607 int ast_context_remove_extension_callerid(const char *context, const char *extension,
 608         int priority, const char *callerid, int matchcid, const char *registrar);
 609
 610 int ast_context_remove_extension_callerid2(struct ast_context *con, const char *extension,
 611         int priority, const char *callerid, int matchcid, const char *registrar,
 612         int already_locked);
 613
 614 /*!
 615  * \brief Add an ignorepat
 616  *
 617  * \param context which context to add the ignorpattern to
 618  * \param ignorepat ignorepattern to set up for the extension
 619  * \param registrar registrar of the ignore pattern
 620  *
 621  * Adds an ignore pattern to a particular context.
 622  *
 623  * \retval 0 on success
 624  * \retval -1 on failure
 625  */
 626 int ast_context_add_ignorepat(const char *context, const char *ignorepat, const char *registrar);
 627
 628 int ast_context_add_ignorepat2(struct ast_context *con, const char *ignorepat, const char *registrar);
 629
 630 /*
 631  * \brief Remove an ignorepat
 632  *
 633  * \param context context from which to remove the pattern
 634  * \param ignorepat the pattern to remove
 635  * \param registrar the registrar of the ignore pattern
 636  *
 637  * This removes the given ignorepattern
 638  *
 639  * \retval 0 on success
 640  * \retval -1 on failure
 641  */
 642 int ast_context_remove_ignorepat(const char *context, const char *ignorepat, const char *registrar);
 643
 644 int ast_context_remove_ignorepat2(struct ast_context *con, const char *ignorepat, const char *registrar);
 645
 646 /*!
 647  * \brief Checks to see if a number should be ignored
 648  *
 649  * \param context context to search within
 650  * \param pattern to check whether it should be ignored or not
 651  *
 652  * Check if a number should be ignored with respect to dialtone cancellation.
 653  *
 654  * \retval 0 if the pattern should not be ignored
 655  * \retval non-zero if the pattern should be ignored
 656  */
 657 int ast_ignore_pattern(const char *context, const char *pattern);
 658
 659 /* Locking functions for outer modules, especially for completion functions */
 660
 661 /*!
 662  * \brief Write locks the context list
 663  *
 664  * \retval 0 on success
 665  * \retval -1 on error
 666  */
 667 int ast_wrlock_contexts(void);
 668
 669 /*!
 670  * \brief Read locks the context list
 671  *
 672  * \retval 0 on success
 673  * \retval -1 on error
 674  */
 675 int ast_rdlock_contexts(void);
 676
 677 /*!
 678  * \brief Unlocks contexts
 679  *
 680  * \retval 0 on success
 681  * \retval -1 on failure
 682  */
 683 int ast_unlock_contexts(void);
 684
 685 /*!
 686  * \brief Write locks a given context
 687  *
 688  * \param con context to lock
 689  *
 690  * \retval 0 on success
 691  * \retval -1 on failure
 692  */
 693 int ast_wrlock_context(struct ast_context *con);
 694
 695 /*!
 696  * \brief Read locks a given context
 697  *
 698  * \param con context to lock
 699  *
 700  * \retval 0 on success
 701  * \retval -1 on failure
 702  */
 703 int ast_rdlock_context(struct ast_context *con);
 704
 705 /*!
 706  * \retval Unlocks the given context
 707  *
 708  * \param con context to unlock
 709  *
 710  * \retval 0 on success
 711  * \retval -1 on failure
 712  */
 713 int ast_unlock_context(struct ast_context *con);
 714
 715 /*!
 716  * \brief locks the macrolock in the given given context
 717  *
 718  * \param macrocontext name of the macro-context to lock
 719  *
 720  * Locks the given macro-context to ensure only one thread (call) can execute it at a time
 721  *
 722  * \retval 0 on success
 723  * \retval -1 on failure
 724  */
 725 int ast_context_lockmacro(const char *macrocontext);
 726
 727 /*!
 728  * \brief Unlocks the macrolock in the given context
 729  *
 730  * \param macrocontext name of the macro-context to unlock
 731  *
 732  * Unlocks the given macro-context so that another thread (call) can execute it
 733  *
 734  * \retval 0 on success
 735  * \retval -1 on failure
 736  */
 737 int ast_context_unlockmacro(const char *macrocontext);
 738
 739 int ast_async_goto(struct ast_channel *chan, const char *context, const char *exten, int priority);
 740
 741 int ast_async_goto_by_name(const char *chan, const char *context, const char *exten, int priority);
 742
 743 /*! Synchronously or asynchronously make an outbound call and send it to a
 744    particular extension */
 745 int ast_pbx_outgoing_exten(const char *type, int format, void *data, int timeout, const char *context, const char *exten, int priority, int *reason, int sync, const char *cid_num, const char *cid_name, struct ast_variable *vars, const char *account, struct ast_channel **locked_channel);
 746
 747 /*! Synchronously or asynchronously make an outbound call and send it to a
 748    particular application with given extension */
 749 int ast_pbx_outgoing_app(const char *type, int format, void *data, int timeout, const char *app, const char *appdata, int *reason, int sync, const char *cid_num, const char *cid_name, struct ast_variable *vars, const char *account, struct ast_channel **locked_channel);
 750
 751 /*!
 752  * \brief Evaluate a condition
 753  *
 754  * \retval 0 if the condition is NULL or of zero length
 755  * \retval int If the string is an integer, the integer representation of
 756  *             the integer is returned
 757  * \retval 1 Any other non-empty string
 758  */
 759 int pbx_checkcondition(const char *condition);
 760
 761 /*! @name
 762  * Functions for returning values from structures */
 763 /*! @{ */
 764 const char *ast_get_context_name(struct ast_context *con);
 765 const char *ast_get_extension_name(struct ast_exten *exten);
 766 struct ast_context *ast_get_extension_context(struct ast_exten *exten);
 767 const char *ast_get_include_name(struct ast_include *include);
 768 const char *ast_get_ignorepat_name(struct ast_ignorepat *ip);
 769 const char *ast_get_switch_name(struct ast_sw *sw);
 770 const char *ast_get_switch_data(struct ast_sw *sw);
 771 int ast_get_switch_eval(struct ast_sw *sw);
 772
 773 /*! @} */
 774
 775 /*! @name Other Extension stuff */
 776 /*! @{ */
 777 int ast_get_extension_priority(struct ast_exten *exten);
 778 int ast_get_extension_matchcid(struct ast_exten *e);
 779 const char *ast_get_extension_cidmatch(struct ast_exten *e);
 780 const char *ast_get_extension_app(struct ast_exten *e);
 781 const char *ast_get_extension_label(struct ast_exten *e);
 782 void *ast_get_extension_app_data(struct ast_exten *e);
 783 /*! @} */
 784
 785 /*! @name Registrar info functions ... */
 786 /*! @{ */
 787 const char *ast_get_context_registrar(struct ast_context *c);
 788 const char *ast_get_extension_registrar(struct ast_exten *e);
 789 const char *ast_get_include_registrar(struct ast_include *i);
 790 const char *ast_get_ignorepat_registrar(struct ast_ignorepat *ip);
 791 const char *ast_get_switch_registrar(struct ast_sw *sw);
 792 /*! @} */
 793
 794 /* Walking functions ... */
 795 struct ast_context *ast_walk_contexts(struct ast_context *con);
 796 struct ast_exten *ast_walk_context_extensions(struct ast_context *con,
 797         struct ast_exten *priority);
 798 struct ast_exten *ast_walk_extension_priorities(struct ast_exten *exten,
 799         struct ast_exten *priority);
 800 struct ast_include *ast_walk_context_includes(struct ast_context *con,
 801         struct ast_include *inc);
 802 struct ast_ignorepat *ast_walk_context_ignorepats(struct ast_context *con,
 803         struct ast_ignorepat *ip);
 804 struct ast_sw *ast_walk_context_switches(struct ast_context *con, struct ast_sw *sw);
 805
 806 /*!
 807  * \note Will lock the channel.
 808  */
 809 int pbx_builtin_serialize_variables(struct ast_channel *chan, struct ast_str **buf);
 810
 811 /*!
 812  * \note Will lock the channel.
 813  *
 814  * \note This function will return a pointer to the buffer inside the channel
 815  * variable.  This value should only be accessed with the channel locked.  If
 816  * the value needs to be kept around, it should be done by using the following
 817  * thread-safe code:
 818  * \code
 819  *              const char *var;
 820  *
 821  *              ast_channel_lock(chan);
 822  *              if ((var = pbx_builtin_getvar_helper(chan, "MYVAR"))) {
 823  *                      var = ast_strdupa(var);
 824  *              }
 825  *              ast_channel_unlock(chan);
 826  * \endcode
 827  */
 828 const char *pbx_builtin_getvar_helper(struct ast_channel *chan, const char *name);
 829
 830 /*!
 831  * \note Will lock the channel.
 832  */
 833 void pbx_builtin_pushvar_helper(struct ast_channel *chan, const char *name, const char *value);
 834
 835 /*!
 836  * \note Will lock the channel.
 837  */
 838 void pbx_builtin_setvar_helper(struct ast_channel *chan, const char *name, const char *value);
 839
 840 /*!
 841  * \note Will lock the channel.
 842  */
 843 void pbx_retrieve_variable(struct ast_channel *c, const char *var, char **ret, char *workspace, int workspacelen, struct varshead *headp);
 844 void pbx_builtin_clear_globals(void);
 845
 846 /*!
 847  * \note Will lock the channel.
 848  */
 849 int pbx_builtin_setvar(struct ast_channel *chan, void *data);
 850 int pbx_builtin_setvar_multiple(struct ast_channel *chan, void *data);
 851
 852 int pbx_builtin_raise_exception(struct ast_channel *chan, void *data);
 853
 854 void pbx_substitute_variables_helper(struct ast_channel *c,const char *cp1,char *cp2,int count);
 855 void pbx_substitute_variables_varshead(struct varshead *headp, const char *cp1, char *cp2, int count);
 856
 857 int ast_extension_patmatch(const char *pattern, const char *data);
 858
 859 /*! Set "autofallthrough" flag, if newval is <0, does not acutally set.  If
 860   set to 1, sets to auto fall through.  If newval set to 0, sets to no auto
 861   fall through (reads extension instead).  Returns previous value. */
 862 int pbx_set_autofallthrough(int newval);
 863
 864 /*! Set "extenpatternmatchnew" flag, if newval is <0, does not acutally set.  If
 865   set to 1, sets to use the new Trie-based pattern matcher.  If newval set to 0, sets to use
 866   the old linear-search algorithm.  Returns previous value. */
 867 int pbx_set_extenpatternmatchnew(int newval);
 868
 869 /*! Set "overrideswitch" field.  If set and of nonzero length, all contexts
 870  * will be tried directly through the named switch prior to any other
 871  * matching within that context. */
 872 void pbx_set_overrideswitch(const char *newval);
 873
 874 /*!
 875  * \note This function will handle locking the channel as needed.
 876  */
 877 int ast_goto_if_exists(struct ast_channel *chan, const char *context, const char *exten, int priority);
 878
 879 /*!
 880  * \note I can find neither parsable nor parseable at dictionary.com,
 881  *       but google gives me 169000 hits for parseable and only 49,800
 882  *       for parsable
 883  *
 884  * \note This function will handle locking the channel as needed.
 885  */
 886 int ast_parseable_goto(struct ast_channel *chan, const char *goto_string);
 887
 888 /*!
 889  * \note This function will handle locking the channel as needed.
 890  */
 891 int ast_async_parseable_goto(struct ast_channel *chan, const char *goto_string);
 892
 893 /*!
 894  * \note This function will handle locking the channel as needed.
 895  */
 896 int ast_explicit_goto(struct ast_channel *chan, const char *context, const char *exten, int priority);
 897
 898 /*!
 899  * \note This function will handle locking the channel as needed.
 900  */
 901 int ast_async_goto_if_exists(struct ast_channel *chan, const char *context, const char *exten, int priority);
 902
 903 struct ast_custom_function* ast_custom_function_find(const char *name);
 904
 905 /*!
 906  * \brief Unregister a custom function
 907  */
 908 int ast_custom_function_unregister(struct ast_custom_function *acf);
 909
 910 /*!
 911  * \brief Register a custom function
 912  */
 913 #define ast_custom_function_register(acf) __ast_custom_function_register(acf, ast_module_info->self)
 914
 915 /*!
 916  * \brief Register a custom function
 917  */
 918 int __ast_custom_function_register(struct ast_custom_function *acf, struct ast_module *mod);
 919
 920 /*!
 921  * \brief Retrieve the number of active calls
 922  */
 923 int ast_active_calls(void);
 924
 925 /*!
 926  * \brief Retrieve the total number of calls processed through the PBX since last restart
 927  */
 928 int ast_processed_calls(void);
 929
 930 /*!
 931  * \brief executes a read operation on a function
 932  *
 933  * \param chan Channel to execute on
 934  * \param function Data containing the function call string (will be modified)
 935  * \param workspace A pointer to safe memory to use for a return value
 936  * \param len the number of bytes in workspace
 937  *
 938  * This application executes a function in read mode on a given channel.
 939  *
 940  * \return zero on success, non-zero on failure
 941  */
 942 int ast_func_read(struct ast_channel *chan, const char *function, char *workspace, size_t len);
 943
 944 /*!
 945  * \brief executes a write operation on a function
 946  *
 947  * \param chan Channel to execute on
 948  * \param function Data containing the function call string (will be modified)
 949  * \param value A value parameter to pass for writing
 950  *
 951  * This application executes a function in write mode on a given channel.
 952  *
 953  * \return zero on success, non-zero on failure
 954  */
 955 int ast_func_write(struct ast_channel *chan, const char *function, const char *value);
 956
 957 /*!
 958  * When looking up extensions, we can have different requests
 959  * identified by the 'action' argument, as follows.
 960  * Note that the coding is such that the low 4 bits are the
 961  * third argument to extension_match_core.
 962  */
 963
 964 enum ext_match_t {
 965         E_MATCHMORE =   0x00,   /* extension can match but only with more 'digits' */
 966         E_CANMATCH =    0x01,   /* extension can match with or without more 'digits' */
 967         E_MATCH =       0x02,   /* extension is an exact match */
 968         E_MATCH_MASK =  0x03,   /* mask for the argument to extension_match_core() */
 969         E_SPAWN =       0x12,   /* want to spawn an extension. Requires exact match */
 970         E_FINDLABEL =   0x22    /* returns the priority for a given label. Requires exact match */
 971 };
 972
 973 #define STATUS_NO_CONTEXT       1
 974 #define STATUS_NO_EXTENSION     2
 975 #define STATUS_NO_PRIORITY      3
 976 #define STATUS_NO_LABEL         4
 977 #define STATUS_SUCCESS          5
 978 #define AST_PBX_MAX_STACK  128
 979
 980 /* request and result for pbx_find_extension */
 981 struct pbx_find_info {
 982 #if 0
 983         const char *context;
 984         const char *exten;
 985         int priority;
 986 #endif
 987
 988         char *incstack[AST_PBX_MAX_STACK];      /* filled during the search */
 989         int stacklen;                   /* modified during the search */
 990         int status;                     /* set on return */
 991         struct ast_switch *swo;         /* set on return */
 992         const char *data;               /* set on return */
 993         const char *foundcontext;       /* set on return */
 994 };
 995
 996 struct ast_exten *pbx_find_extension(struct ast_channel *chan,
 997                                                                          struct ast_context *bypass, struct pbx_find_info *q,
 998                                                                          const char *context, const char *exten, int priority,
 999                                                                          const char *label, const char *callerid, enum ext_match_t action);
1000
1001 /*! \brief Function in pbx.c that propably should be somewhere else, but not in res_agi, since it's a loadable module */
1002 const char *ast_agi_state(struct ast_channel *chan);
1003
1004
1005 /* every time a write lock is obtained for contexts,
1006    a counter is incremented. You can check this via the
1007    following func */
1008
1009 int ast_wrlock_contexts_version(void);
1010
1011
1012 /* hashtable functions for contexts */
1013 int ast_hashtab_compare_contexts(const void *ah_a, const void *ah_b);
1014 unsigned int ast_hashtab_hash_contexts(const void *obj);
1015
1016 #if defined(__cplusplus) || defined(c_plusplus)
1017 }
1018 #endif
1019
1020 #endif /* _ASTERISK_PBX_H */