Asterisk - The Open Source Telephony Project  GIT-master-44aef04
pbx.h
Go to the documentation of this file.
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/channel.h"
27 #include "asterisk/sched.h"
28 #include "asterisk/devicestate.h"
29 #include "asterisk/presencestate.h"
30 #include "asterisk/chanvars.h"
31 #include "asterisk/hashtab.h"
32 #include "asterisk/stringfields.h"
33 #include "asterisk/xmldoc.h"
34 #include "asterisk/format.h"
35 
36 #if defined(__cplusplus) || defined(c_plusplus)
37 extern "C" {
38 #endif
39 
40 #define AST_MAX_APP 32 /*!< Max length of an application */
41 
42 #define AST_PBX_GOTO_FAILED -3
43 #define AST_PBX_KEEP 0
44 #define AST_PBX_REPLACE 1
45 
46 /*! \brief Special return values from applications to the PBX
47  * @{ */
48 #define AST_PBX_HANGUP -1 /*!< Jump to the 'h' exten */
49 #define AST_PBX_OK 0 /*!< No errors */
50 #define AST_PBX_ERROR 1 /*!< Jump to the 'e' exten */
51 #define AST_PBX_INCOMPLETE 12 /*!< Return to PBX matching, allowing more digits for the extension */
52 /*! @} */
53 
54 #define PRIORITY_HINT -1 /*!< Special Priority for a hint */
55 
56 /*!
57  * \brief Extension states
58  * \note States can be combined
59  * \ref AstExtState
60  */
62  AST_EXTENSION_REMOVED = -2, /*!< Extension removed */
63  AST_EXTENSION_DEACTIVATED = -1, /*!< Extension hint removed */
64  AST_EXTENSION_NOT_INUSE = 0, /*!< No device INUSE or BUSY */
65  AST_EXTENSION_INUSE = 1 << 0, /*!< One or more devices INUSE */
66  AST_EXTENSION_BUSY = 1 << 1, /*!< All devices BUSY */
67  AST_EXTENSION_UNAVAILABLE = 1 << 2, /*!< All devices UNAVAILABLE/UNREGISTERED */
68  AST_EXTENSION_RINGING = 1 << 3, /*!< All devices RINGING */
69  AST_EXTENSION_ONHOLD = 1 << 4, /*!< All devices ONHOLD */
70 };
71 
72 /*!
73  * \brief extension matchcid types
74  * \note matchcid in ast_exten retains 0/1, this adds 3rd state for functions to specify all
75  * \see ast_context_remove_extension_callerid
76  */
78  AST_EXT_MATCHCID_OFF = 0, /*!< Match only extensions with matchcid=0 */
79  AST_EXT_MATCHCID_ON = 1, /*!< Match only extensions with matchcid=1 AND cidmatch matches */
80  AST_EXT_MATCHCID_ANY = 2, /*!< Match both - used only in functions manipulating ast_exten's */
81 };
82 
83 struct ast_context;
84 struct ast_exten;
85 struct ast_include;
86 struct ast_ignorepat;
87 struct ast_sw;
88 
90  /*! The extension state update is a result of a device state changing on the extension. */
92  /*! The extension state update is a result of presence state changing on the extension. */
94 };
95 
99  char device_name[1];
100 };
101 
104  enum ast_extension_states exten_state;
105  struct ao2_container *device_state_info; /* holds ast_device_state_info, must be referenced by callback if stored */
106  enum ast_presence_state presence_state;
107  const char *presence_subtype;
108  const char *presence_message;
109 };
110 
111 /*! \brief Typedef for devicestate and hint callbacks */
112 typedef int (*ast_state_cb_type)(const char *context, const char *exten, struct ast_state_cb_info *info, void *data);
113 
114 /*! \brief Typedef for devicestate and hint callback removal indication callback */
115 typedef void (*ast_state_cb_destroy_type)(int id, void *data);
116 
117 /*! \brief Data structure associated with a custom dialplan function */
119  const char *name; /*!< Name */
121  AST_STRING_FIELD(synopsis); /*!< Synopsis text for 'show functions' */
122  AST_STRING_FIELD(desc); /*!< Description (help text) for 'show functions &lt;name&gt;' */
123  AST_STRING_FIELD(syntax); /*!< Syntax text for 'core show functions' */
124  AST_STRING_FIELD(arguments); /*!< Arguments description */
125  AST_STRING_FIELD(seealso); /*!< See also */
126  );
127  enum ast_doc_src docsrc; /*!< Where the documentation come from */
128  /*! Read function, if read is supported */
129  ast_acf_read_fn_t read; /*!< Read function, if read is supported */
130  /*! Read function, if read is supported. Note: only one of read or read2
131  * needs to be implemented. In new code, read2 should be implemented as
132  * the way forward, but they should return identical results, within the
133  * constraints of buffer size, if both are implemented. That is, if the
134  * read function is handed a 16-byte buffer, and the result is 17 bytes
135  * long, then the first 15 bytes (remember NULL terminator) should be
136  * the same for both the read and the read2 methods. */
138  /*! If no read2 function is provided, what maximum size? */
139  size_t read_max;
140  /*! Write function, if write is supported */
141  ast_acf_write_fn_t write; /*!< Write function, if write is supported */
142  struct ast_module *mod; /*!< Module this custom function belongs to */
143  unsigned int read_escalates:1; /*!< The read function is to be considered
144  * 'dangerous', and should not be run directly
145  * from external interfaces (AMI, ARI, etc.)
146  * \since 12 */
147  unsigned int write_escalates:1; /*!< The write function is to be considerd
148  * 'dangerous', and should not be run directly
149  * from external interfaces (AMI, ARI, etc.)
150  * \since 12 */
151 
153 };
154 
155 /*! \brief All switch functions have the same interface, so define a type for them */
156 typedef int (ast_switch_f)(struct ast_channel *chan, const char *context,
157  const char *exten, int priority, const char *callerid, const char *data);
158 
159 /*!< Data structure associated with an Asterisk switch */
160 struct ast_switch {
162  const char *name; /*!< Name of the switch */
163  const char *description; /*!< Description of the switch */
164 
169 };
170 
171 struct ast_timing {
172  int hastime; /*!< If time construct exists */
173  unsigned int monthmask; /*!< Mask for month */
174  unsigned int daymask; /*!< Mask for date */
175  unsigned int dowmask; /*!< Mask for day of week (sun-sat) */
176  unsigned int minmask[48]; /*!< Mask for minute */
177  char *timezone; /*!< NULL, or zoneinfo style timezone */
178 };
179 
180 /*!
181  * \brief Construct a timing bitmap, for use in time-based conditionals.
182  * \param i Pointer to an ast_timing structure.
183  * \param info Standard string containing a timerange, weekday range, monthday range, and month range, as well as an optional timezone.
184  * \retval Returns 1 on success or 0 on failure.
185  */
186 int ast_build_timing(struct ast_timing *i, const char *info);
187 
188 /*!
189  * \brief Evaluate a pre-constructed bitmap as to whether the current time falls within the range specified.
190  * \param i Pointer to an ast_timing structure.
191  * \retval Returns 1, if the time matches or 0, if the current time falls outside of the specified range.
192  */
193 int ast_check_timing(const struct ast_timing *i);
194 
195 /*!
196  * \brief Evaluate a pre-constructed bitmap as to whether a particular time falls within the range specified.
197  * \param i Pointer to an ast_timing structure.
198  * \param tv Specified time
199  * \retval Returns 1, if the time matches or 0, if the time falls outside of the specified range.
200  */
201 int ast_check_timing2(const struct ast_timing *i, const struct timeval tv);
202 
203 /*!
204  * \brief Deallocates memory structures associated with a timing bitmap.
205  * \param i Pointer to an ast_timing structure.
206  * \retval 0 success
207  * \retval non-zero failure (number suitable to pass to \see strerror)
208  */
209 int ast_destroy_timing(struct ast_timing *i);
210 
211 struct ast_pbx {
212  int dtimeoutms; /*!< Timeout between digits (milliseconds) */
213  int rtimeoutms; /*!< Timeout for response (milliseconds) */
214 };
215 
216 
217 /*!
218  * \brief Register an alternative dialplan switch
219  *
220  * \param sw switch to register
221  *
222  * This function registers a populated ast_switch structure with the
223  * asterisk switching architecture.
224  *
225  * \retval 0 success
226  * \retval non-zero failure
227  */
228 int ast_register_switch(struct ast_switch *sw);
229 
230 /*!
231  * \brief Unregister an alternative switch
232  *
233  * \param sw switch to unregister
234  *
235  * Unregisters a switch from asterisk.
236  *
237  * \return nothing
238  */
239 void ast_unregister_switch(struct ast_switch *sw);
240 
241 /*!
242  * \brief Look up an application
243  *
244  * \param app name of the app
245  *
246  * This function searches for the ast_app structure within
247  * the apps that are registered for the one with the name
248  * you passed in.
249  *
250  * \return the ast_app structure that matches on success, or NULL on failure
251  */
252 struct ast_app *pbx_findapp(const char *app);
253 
254 /*!
255  * \brief Execute an application
256  *
257  * \param c channel to execute on
258  * \param app which app to execute
259  * \param data the data passed into the app
260  *
261  * This application executes an application on a given channel. It
262  * saves the stack and executes the given application passing in
263  * the given data.
264  *
265  * \retval 0 success
266  * \retval -1 failure
267  */
268 int pbx_exec(struct ast_channel *c, struct ast_app *app, const char *data);
269 
270 /*!
271  * \brief Register a new context or find an existing one
272  *
273  * \param extcontexts pointer to the ast_context structure pointer
274  * \param exttable pointer to the hashtable that contains all the elements in extcontexts
275  * \param name name of the new context
276  * \param registrar registrar of the context
277  *
278  * This function allows you to play in two environments: the global contexts (active dialplan)
279  * or an external context set of your choosing. To act on the external set, make sure extcontexts
280  * and exttable are set; for the globals, make sure both extcontexts and exttable are NULL.
281  *
282  * This will first search for a context with your name. If it exists already, it will not
283  * create a new one. If it does not exist, it will create a new one with the given name
284  * and registrar.
285  *
286  * \return NULL on failure, and an ast_context structure on success
287  */
288 struct ast_context *ast_context_find_or_create(struct ast_context **extcontexts, struct ast_hashtab *exttable, const char *name, const char *registrar);
289 
290 /*!
291  * \brief Enable or disable autohints support on a context
292  *
293  * \param con pointer to the context
294  * \param enabled whether autohints are enabled
295  *
296  */
297 void ast_context_set_autohints(struct ast_context *con, int enabled);
298 
299 /*!
300  * \brief Merge the temporary contexts into a global contexts list and delete from the
301  * global list the ones that are being added
302  *
303  * \param extcontexts pointer to the ast_context structure
304  * \param exttable pointer to the ast_hashtab structure that contains all the elements in extcontexts
305  * \param registrar of the context; if it's set the routine will delete all contexts
306  * that belong to that registrar; if NULL only the contexts that are specified
307  * in extcontexts
308  */
309 void ast_merge_contexts_and_delete(struct ast_context **extcontexts, struct ast_hashtab *exttable, const char *registrar);
310 
311 /*!
312  * \brief Destroy a context by name
313  *
314  * \param context Name of the context to destroy
315  * \param registrar who registered it
316  *
317  * You can optionally leave out the registrar parameter. It will find it
318  * based on the context name.
319  *
320  * \retval -1 context not found
321  * \retval 0 Success
322  */
323 int ast_context_destroy_by_name(const char *context, const char *registrar);
324 
325 /*!
326  * \brief Destroy a context (matches the specified context or ANY context if NULL)
327  *
328  * \param con context to destroy
329  * \param registrar who registered it
330  *
331  * You can optionally leave out either parameter. It will find it
332  * based on either the ast_context or the registrar name.
333  *
334  * \return nothing
335  */
336 void ast_context_destroy(struct ast_context *con, const char *registrar);
337 
338 /*!
339  * \brief Find a context
340  *
341  * \param name name of the context to find
342  *
343  * Will search for the context with the given name.
344  *
345  * \return the ast_context on success, NULL on failure.
346  */
347 struct ast_context *ast_context_find(const char *name);
348 
349 /*!
350  * \brief The result codes when starting the PBX on a channel with ast_pbx_start.
351  * \note AST_PBX_CALL_LIMIT refers to the maxcalls call limit in asterisk.conf
352  * \see ast_pbx_start
353  */
358 };
359 
360 /*!
361  * \brief Create a new thread and start the PBX
362  *
363  * \param c channel to start the pbx on
364  *
365  * \see ast_pbx_run for a synchronous function to run the PBX in the
366  * current thread, as opposed to starting a new one.
367  *
368  * \retval Zero on success
369  * \retval non-zero on failure
370  */
372 
373 /*!
374  * \brief Execute the PBX in the current thread
375  *
376  * \param c channel to run the pbx on
377  *
378  * This executes the PBX on a given channel. It allocates a new
379  * PBX structure for the channel, and provides all PBX functionality.
380  * See ast_pbx_start for an asynchronous function to run the PBX in a
381  * new thread as opposed to the current one.
382  *
383  * \retval Zero on success
384  * \retval non-zero on failure
385  */
387 
388 /*!
389  * \brief Options for ast_pbx_run()
390  */
391 struct ast_pbx_args {
392  union {
393  /*! Pad this out so that we have plenty of room to add options
394  * but still maintain ABI compatibility over time. */
395  uint64_t __padding;
396  struct {
397  /*! Do not hangup the channel when the PBX is complete. */
398  unsigned int no_hangup_chan:1;
399  };
400  };
401 };
402 
403 /*!
404  * \brief Execute the PBX in the current thread
405  *
406  * \param c channel to run the pbx on
407  * \param args options for the pbx
408  *
409  * This executes the PBX on a given channel. It allocates a new
410  * PBX structure for the channel, and provides all PBX functionality.
411  * See ast_pbx_start for an asynchronous function to run the PBX in a
412  * new thread as opposed to the current one.
413  *
414  * \retval Zero on success
415  * \retval non-zero on failure
416  */
418 
419 /*!
420  * \brief Run the h exten from the given context.
421  * \since 11.0
422  *
423  * \param chan Channel to run the h exten on.
424  * \param context Context the h exten is in.
425  *
426  * \return Nothing
427  */
428 void ast_pbx_h_exten_run(struct ast_channel *chan, const char *context);
429 
430 /*!
431  * \brief Run all hangup handlers on the channel.
432  * \since 11.0
433  *
434  * \param chan Channel to run the hangup handlers on.
435  *
436  * \note Absolutely _NO_ channel locks should be held before calling this function.
437  *
438  * \retval Zero if no hangup handlers run.
439  * \retval non-zero if hangup handlers were run.
440  */
441 int ast_pbx_hangup_handler_run(struct ast_channel *chan);
442 
443 /*!
444  * \brief Init the hangup handler container on a channel.
445  * \since 11.0
446  *
447  * \param chan Channel to init the hangup handler container on.
448  *
449  * \return Nothing
450  */
451 void ast_pbx_hangup_handler_init(struct ast_channel *chan);
452 
453 /*!
454  * \brief Destroy the hangup handler container on a channel.
455  * \since 11.0
456  *
457  * \param chan Channel to destroy the hangup handler container on.
458  *
459  * \return Nothing
460  */
462 
463 /*!
464  * \brief Pop the top of the channel hangup handler stack.
465  * \since 11.0
466  *
467  * \param chan Channel to push the hangup handler onto.
468  *
469  * \retval TRUE if a handler was popped off of the stack.
470  */
471 int ast_pbx_hangup_handler_pop(struct ast_channel *chan);
472 
473 /*!
474  * \brief Push the given hangup handler onto the channel hangup handler stack.
475  * \since 11.0
476  *
477  * \param chan Channel to push the hangup handler onto.
478  * \param handler Gosub application parameter string.
479  *
480  * \return Nothing
481  */
482 void ast_pbx_hangup_handler_push(struct ast_channel *chan, const char *handler);
483 
484 /*!
485  * \brief Add and extension to an extension context.
486  *
487  * \param context context to add the extension to
488  * \param replace
489  * \param extension extension to add
490  * \param priority priority level of extension addition
491  * \param label extension label
492  * \param callerid pattern to match CallerID, or NULL to match any CallerID
493  * \param application application to run on the extension with that priority level
494  * \param data data to pass to the application
495  * \param datad a pointer to a function that will deallocate \c data when needed
496  * or NULL if \c data does not need to be freed.
497  * \param registrar who registered the extension
498  *
499  * \note On any failure, the function pointed to by \c datap will be called and passed the
500  * \c data pointer.
501  *
502  * \retval 0 success
503  * \retval -1 failure
504  */
505 int ast_add_extension(const char *context, int replace, const char *extension,
506  int priority, const char *label, const char *callerid,
507  const char *application, void *data, void (*datad)(void *), const char *registrar);
508 
509 /*!
510  * \brief Add an extension to an extension context, this time with an ast_context *.
511  *
512  * \param registrar_file optional configuration file that defines this extension
513  * \param registrar_line optional line number of configuration file that defines extension
514  *
515  * \note For details about the other arguments, check ast_add_extension()
516  */
517 int ast_add_extension2(struct ast_context *con, int replace, const char *extension,
518  int priority, const char *label, const char *callerid,
519  const char *application, void *data, void (*datad)(void *), const char *registrar,
520  const char *registrar_file, int registrar_line);
521 
522 /*!
523  * \brief Same as ast_add_extension2, but assumes you have already locked context
524  * \since 12.0.0
525  *
526  * \note con must be write locked prior to calling. For details about the arguments,
527  * check ast_add_extension()
528  */
529 int ast_add_extension2_nolock(struct ast_context *con, int replace, const char *extension,
530  int priority, const char *label, const char *callerid,
531  const char *application, void *data, void (*datad)(void *), const char *registrar,
532  const char *registrar_file, int registrar_line);
533 
534 /*!
535  * \brief Map devstate to an extension state.
536  *
537  * \param[in] devstate device state
538  *
539  * \return the extension state mapping.
540  */
542 
543 /*!
544  * \brief Uses hint and devicestate callback to get the state of an extension
545  *
546  * \param c this is not important
547  * \param context which context to look in
548  * \param exten which extension to get state
549  *
550  * \return extension state as defined in the ast_extension_states enum
551  */
552 int ast_extension_state(struct ast_channel *c, const char *context, const char *exten);
553 
554 /*!
555  * \brief Uses hint and devicestate callback to get the extended state of an extension
556  * \since 11
557  *
558  * \param c this is not important
559  * \param context which context to look in
560  * \param exten which extension to get state
561  * \param[out] device_state_info ptr to an ao2_container with extended state info, must be unref'd after use.
562  *
563  * \return extension state as defined in the ast_extension_states enum
564  */
565 int ast_extension_state_extended(struct ast_channel *c, const char *context, const char *exten,
566  struct ao2_container **device_state_info);
567 
568 /*!
569  * \brief Uses hint and presence state callback to get the presence state of an extension
570  *
571  * \param c this is not important
572  * \param context which context to look in
573  * \param exten which extension to get state
574  * \param[out] subtype Further information regarding the presence returned
575  * \param[out] message Custom message further describing current presence
576  *
577  * \note The subtype and message are dynamically allocated and must be freed by
578  * the caller of this function.
579  *
580  * \return returns the presence state value.
581  */
582 int ast_hint_presence_state(struct ast_channel *c, const char *context, const char *exten, char **subtype, char **message);
583 
584 /*!
585  * \brief Return string representation of the state of an extension
586  *
587  * \param extension_state is the numerical state delivered by ast_extension_state
588  *
589  * \return the state of an extension as string
590  */
591 const char *ast_extension_state2str(int extension_state);
592 
593 /*!
594  * \brief Add watcher for extension states with destructor.
595  * \since 1.8.9
596  * \since 10.1.0
597  *
598  * \param context which context to look in
599  * \param exten which extension to get state
600  * \param change_cb callback to call if state changed
601  * \param destroy_cb callback to call when the watcher is destroyed.
602  * \param data to pass to callbacks
603  *
604  * \note If context and exten are NULL then the added watcher is global.
605  * The change_cb is called for every extension's state change.
606  *
607  * \note The change_cb is called if the state of an extension is changed.
608  *
609  * \note The destroy_cb is called when the watcher is deleted so the
610  * watcher can release any associated resources.
611  *
612  * \retval -1 on failure
613  * \retval 0 Global watcher added successfully
614  * \retval ID on success
615  */
616 int ast_extension_state_add_destroy(const char *context, const char *exten,
617  ast_state_cb_type change_cb, ast_state_cb_destroy_type destroy_cb, void *data);
618 
619 /*!
620  * \brief Add watcher for extended extension states with destructor.
621  * \since 11
622  *
623  * \param context which context to look in
624  * \param exten which extension to get state
625  * \param change_cb callback to call if state changed
626  * \param destroy_cb callback to call when the watcher is destroyed.
627  * \param data to pass to callbacks
628  *
629  * \note If context and exten are NULL then the added watcher is global.
630  * The change_cb is called for every extension's state change.
631  *
632  * \note The change_cb is called if the state of an extension is changed.
633  * The extended state is passed to the callback in the device_state_info
634  * member of ast_state_cb_info.
635  *
636  * \note The destroy_cb is called when the watcher is deleted so the
637  * watcher can release any associated resources.
638  *
639  * \retval -1 on failure
640  * \retval 0 Global watcher added successfully
641  * \retval ID on success
642  */
643 int ast_extension_state_add_destroy_extended(const char *context, const char *exten,
644  ast_state_cb_type change_cb, ast_state_cb_destroy_type destroy_cb, void *data);
645 
646 /*!
647  * \brief Add watcher for extension states.
648  *
649  * \param context which context to look in
650  * \param exten which extension to get state
651  * \param change_cb callback to call if state changed
652  * \param data to pass to callback
653  *
654  * \note If context and exten are NULL then the added watcher is global.
655  * The change_cb is called for every extension's state change.
656  *
657  * \note The change_cb is called if the state of an extension is changed.
658  *
659  * \retval -1 on failure
660  * \retval 0 Global watcher added successfully
661  * \retval ID on success
662  */
663 int ast_extension_state_add(const char *context, const char *exten,
664  ast_state_cb_type change_cb, void *data);
665 
666 /*!
667  * \brief Add watcher for extended extension states.
668  * \since 11
669  *
670  * \param context which context to look in
671  * \param exten which extension to get state
672  * \param change_cb callback to call if state changed
673  * \param data to pass to callback
674  *
675  * \note If context and exten are NULL then the added watcher is global.
676  * The change_cb is called for every extension's state change.
677  *
678  * \note The change_cb is called if the state of an extension is changed.
679  * The extended state is passed to the callback in the device_state_info
680  * member of ast_state_cb_info.
681  *
682  * \retval -1 on failure
683  * \retval 0 Global watcher added successfully
684  * \retval ID on success
685  */
686 int ast_extension_state_add_extended(const char *context, const char *exten,
687  ast_state_cb_type change_cb, void *data);
688 
689 /*!
690  * \brief Deletes a state change watcher by ID
691  *
692  * \param id of the state watcher to delete (0 for global watcher)
693  * \param change_cb callback to call if state changed (Used if id == 0 (global))
694  *
695  * \retval 0 success
696  * \retval -1 failure
697  */
698 int ast_extension_state_del(int id, ast_state_cb_type change_cb);
699 
700 /*!
701  * \brief If an extension hint exists, return non-zero
702  *
703  * \param hint buffer for hint
704  * \param hintsize size of hint buffer, in bytes
705  * \param name buffer for name portion of hint
706  * \param namesize size of name buffer
707  * \param c Channel from which to return the hint. This is only important when the hint or name contains an expression to be expanded.
708  * \param context which context to look in
709  * \param exten which extension to search for
710  *
711  * \return If an extension within the given context with the priority PRIORITY_HINT
712  * is found, a non zero value will be returned.
713  * Otherwise, 0 is returned.
714  */
715 int ast_get_hint(char *hint, int hintsize, char *name, int namesize,
716  struct ast_channel *c, const char *context, const char *exten);
717 
718 /*!
719  * \brief If an extension hint exists, return non-zero
720  *
721  * \param hint buffer for hint
722  * \param hintsize Maximum size of hint buffer (<0 to prevent growth, >0 to limit growth to that number of bytes, or 0 for unlimited growth)
723  * \param name buffer for name portion of hint
724  * \param namesize Maximum size of name buffer (<0 to prevent growth, >0 to limit growth to that number of bytes, or 0 for unlimited growth)
725  * \param c Channel from which to return the hint. This is only important when the hint or name contains an expression to be expanded.
726  * \param context which context to look in
727  * \param exten which extension to search for
728  *
729  * \return If an extension within the given context with the priority PRIORITY_HINT
730  * is found, a non zero value will be returned.
731  * Otherwise, 0 is returned.
732  */
733 int ast_str_get_hint(struct ast_str **hint, ssize_t hintsize, struct ast_str **name, ssize_t namesize,
734  struct ast_channel *c, const char *context, const char *exten);
735 
736 /*!
737  * \brief Determine whether an extension exists
738  *
739  * \param c this is not important
740  * \param context which context to look in
741  * \param exten which extension to search for
742  * \param priority priority of the action within the extension
743  * \param callerid callerid to search for
744  *
745  * \note It is possible for autoservice to be started and stopped on c during this
746  * function call, it is important that c is not locked prior to calling this. Otherwise
747  * a deadlock may occur
748  *
749  * \return If an extension within the given context(or callerid) with the given priority
750  * is found a non zero value will be returned. Otherwise, 0 is returned.
751  */
752 int ast_exists_extension(struct ast_channel *c, const char *context, const char *exten,
753  int priority, const char *callerid);
754 
755 /*!
756  * \brief Find the priority of an extension that has the specified label
757  *
758  * \param c this is not important
759  * \param context which context to look in
760  * \param exten which extension to search for
761  * \param label label of the action within the extension to match to priority
762  * \param callerid callerid to search for
763  *
764  * \note It is possible for autoservice to be started and stopped on c during this
765  * function call, it is important that c is not locked prior to calling this. Otherwise
766  * a deadlock may occur
767  *
768  * \retval the priority which matches the given label in the extension
769  * \retval -1 if not found.
770  */
771 int ast_findlabel_extension(struct ast_channel *c, const char *context,
772  const char *exten, const char *label, const char *callerid);
773 
774 /*!
775  * \brief Find the priority of an extension that has the specified label
776  *
777  * \note It is possible for autoservice to be started and stopped on c during this
778  * function call, it is important that c is not locked prior to calling this. Otherwise
779  * a deadlock may occur
780  *
781  * \note This function is the same as ast_findlabel_extension, except that it accepts
782  * a pointer to an ast_context structure to specify the context instead of the
783  * name of the context. Otherwise, the functions behave the same.
784  */
785 int ast_findlabel_extension2(struct ast_channel *c, struct ast_context *con,
786  const char *exten, const char *label, const char *callerid);
787 
788 /*!
789  * \brief Looks for a valid matching extension
790  *
791  * \param c not really important
792  * \param context context to serach within
793  * \param exten extension to check
794  * \param priority priority of extension path
795  * \param callerid callerid of extension being searched for
796  *
797  * \note It is possible for autoservice to be started and stopped on c during this
798  * function call, it is important that c is not locked prior to calling this. Otherwise
799  * a deadlock may occur
800  *
801  * \return If "exten" *could be* a valid extension in this context with or without
802  * some more digits, return non-zero. Basically, when this returns 0, no matter
803  * what you add to exten, it's not going to be a valid extension anymore
804  */
805 int ast_canmatch_extension(struct ast_channel *c, const char *context,
806  const char *exten, int priority, const char *callerid);
807 
808 /*!
809  * \brief Looks to see if adding anything to this extension might match something. (exists ^ canmatch)
810  *
811  * \param c not really important XXX
812  * \param context context to serach within
813  * \param exten extension to check
814  * \param priority priority of extension path
815  * \param callerid callerid of extension being searched for
816  *
817  * \note It is possible for autoservice to be started and stopped on c during this
818  * function call, it is important that c is not locked prior to calling this. Otherwise
819  * a deadlock may occur
820  *
821  * \return If "exten" *could match* a valid extension in this context with
822  * some more digits, return non-zero. Does NOT return non-zero if this is
823  * an exact-match only. Basically, when this returns 0, no matter
824  * what you add to exten, it's not going to be a valid extension anymore
825  */
826 int ast_matchmore_extension(struct ast_channel *c, const char *context,
827  const char *exten, int priority, const char *callerid);
828 
829 /*!
830  * \brief Determine if a given extension matches a given pattern (in NXX format)
831  *
832  * \param pattern pattern to match
833  * \param extension extension to check against the pattern.
834  *
835  * Checks whether or not the given extension matches the given pattern.
836  *
837  * \retval 1 on match
838  * \retval 0 on failure
839  */
840 int ast_extension_match(const char *pattern, const char *extension);
841 
842 int ast_extension_close(const char *pattern, const char *data, int needmore);
843 
844 /*!
845  * \brief Determine if one extension should match before another
846  *
847  * \param a extension to compare with b
848  * \param b extension to compare with a
849  *
850  * Checks whether or extension a should match before extension b
851  *
852  * \retval 0 if the two extensions have equal matching priority
853  * \retval 1 on a > b
854  * \retval -1 on a < b
855  */
856 int ast_extension_cmp(const char *a, const char *b);
857 
858 /*!
859  * \brief Launch a new extension (i.e. new stack)
860  *
861  * \param c not important
862  * \param context which context to generate the extension within
863  * \param exten new extension to add
864  * \param priority priority of new extension
865  * \param callerid callerid of extension
866  * \param found
867  * \param combined_find_spawn
868  *
869  * This adds a new extension to the asterisk extension list.
870  *
871  * \note It is possible for autoservice to be started and stopped on c during this
872  * function call, it is important that c is not locked prior to calling this. Otherwise
873  * a deadlock may occur
874  *
875  * \retval 0 on success
876  * \retval -1 on failure.
877  */
878 int ast_spawn_extension(struct ast_channel *c, const char *context,
879  const char *exten, int priority, const char *callerid, int *found, int combined_find_spawn);
880 
881 /*!
882  * \brief Add a context include
883  *
884  * \param context context to add include to
885  * \param include new include to add
886  * \param registrar who's registering it
887  *
888  * Adds an include taking a char * string as the context parameter
889  *
890  * \retval 0 on success
891  * \retval -1 on error
892 */
893 int ast_context_add_include(const char *context, const char *include,
894  const char *registrar);
895 
896 /*!
897  * \brief Add a context include
898  *
899  * \param con context to add the include to
900  * \param value include value to add
901  * \param registrar who registered the context
902  *
903  * Adds an include taking a struct ast_context as the first parameter
904  *
905  * \retval 0 on success
906  * \retval -1 on failure
907  */
908 int ast_context_add_include2(struct ast_context *con, const char *include,
909  const char *registrar);
910 
911 /*!
912  * \brief Remove a context include
913  *
914  * \note See ast_context_add_include for information on arguments
915  *
916  * \retval 0 on success
917  * \retval -1 on failure
918  */
919 int ast_context_remove_include(const char *context, const char *include,
920  const char *registrar);
921 
922 /*!
923  * \brief Removes an include by an ast_context structure
924  *
925  * \note See ast_context_add_include2 for information on arguments
926  *
927  * \retval 0 on success
928  * \retval -1 on success
929  */
930 int ast_context_remove_include2(struct ast_context *con, const char *include,
931  const char *registrar);
932 
933 /*!
934  * \brief Verifies includes in an ast_contect structure
935  *
936  * \param con context in which to verify the includes
937  *
938  * \retval 0 if no problems found
939  * \retval -1 if there were any missing context
940  */
942 
943 /*!
944  * \brief Add a switch
945  *
946  * \param context context to which to add the switch
947  * \param sw switch to add
948  * \param data data to pass to switch
949  * \param eval whether to evaluate variables when running switch
950  * \param registrar whoever registered the switch
951  *
952  * This function registers a switch with the asterisk switch architecture
953  *
954  * \retval 0 on success
955  * \retval -1 on failure
956  */
957 int ast_context_add_switch(const char *context, const char *sw, const char *data,
958  int eval, const char *registrar);
959 
960 /*!
961  * \brief Adds a switch (first param is a ast_context)
962  *
963  * \note See ast_context_add_switch() for argument information, with the exception of
964  * the first argument. In this case, it's a pointer to an ast_context structure
965  * as opposed to the name.
966  */
967 int ast_context_add_switch2(struct ast_context *con, const char *sw, const char *data,
968  int eval, const char *registrar);
969 
970 /*!
971  * \brief Remove a switch
972  *
973  * Removes a switch with the given parameters
974  *
975  * \retval 0 on success
976  * \retval -1 on failure
977  */
978 int ast_context_remove_switch(const char *context, const char *sw,
979  const char *data, const char *registrar);
980 
981 int ast_context_remove_switch2(struct ast_context *con, const char *sw,
982  const char *data, const char *registrar);
983 
984 /*!
985  * \brief Simply remove extension from context
986  *
987  * \param context context to remove extension from
988  * \param extension which extension to remove
989  * \param priority priority of extension to remove (0 to remove all)
990  * \param registrar registrar of the extension
991  *
992  * This function removes an extension from a given context.
993  *
994  * \retval 0 on success
995  * \retval -1 on failure
996  *
997  * @{
998  */
999 int ast_context_remove_extension(const char *context, const char *extension, int priority,
1000  const char *registrar);
1001 
1002 int ast_context_remove_extension2(struct ast_context *con, const char *extension,
1003  int priority, const char *registrar, int already_locked);
1004 
1005 int ast_context_remove_extension_callerid(const char *context, const char *extension,
1006  int priority, const char *callerid, int matchcid, const char *registrar);
1007 
1008 int ast_context_remove_extension_callerid2(struct ast_context *con, const char *extension,
1009  int priority, const char *callerid, int matchcid, const char *registrar,
1010  int already_locked);
1011 /*! @} */
1012 
1013 /*!
1014  * \brief Add an ignorepat
1015  *
1016  * \param context which context to add the ignorpattern to
1017  * \param ignorepat ignorepattern to set up for the extension
1018  * \param registrar registrar of the ignore pattern
1019  *
1020  * Adds an ignore pattern to a particular context.
1021  *
1022  * \retval 0 on success
1023  * \retval -1 on failure
1024  */
1025 int ast_context_add_ignorepat(const char *context, const char *ignorepat, const char *registrar);
1026 
1027 int ast_context_add_ignorepat2(struct ast_context *con, const char *ignorepat, const char *registrar);
1028 
1029 /*
1030  * \brief Remove an ignorepat
1031  *
1032  * \param context context from which to remove the pattern
1033  * \param ignorepat the pattern to remove
1034  * \param registrar the registrar of the ignore pattern
1035  *
1036  * This removes the given ignorepattern
1037  *
1038  * \retval 0 on success
1039  * \retval -1 on failure
1040  */
1041 int ast_context_remove_ignorepat(const char *context, const char *ignorepat, const char *registrar);
1042 
1043 int ast_context_remove_ignorepat2(struct ast_context *con, const char *ignorepat, const char *registrar);
1044 
1045 /*!
1046  * \brief Checks to see if a number should be ignored
1047  *
1048  * \param context context to search within
1049  * \param pattern to check whether it should be ignored or not
1050  *
1051  * Check if a number should be ignored with respect to dialtone cancellation.
1052  *
1053  * \retval 0 if the pattern should not be ignored
1054  * \retval non-zero if the pattern should be ignored
1055  */
1056 int ast_ignore_pattern(const char *context, const char *pattern);
1057 
1058 /* Locking functions for outer modules, especially for completion functions */
1059 
1060 /*!
1061  * \brief Write locks the context list
1062  *
1063  * \retval 0 on success
1064  * \retval -1 on error
1065  */
1066 int ast_wrlock_contexts(void);
1067 
1068 /*!
1069  * \brief Read locks the context list
1070  *
1071  * \retval 0 on success
1072  * \retval -1 on error
1073  */
1074 int ast_rdlock_contexts(void);
1075 
1076 /*!
1077  * \brief Unlocks contexts
1078  *
1079  * \retval 0 on success
1080  * \retval -1 on failure
1081  */
1082 int ast_unlock_contexts(void);
1083 
1084 /*!
1085  * \brief Write locks a given context
1086  *
1087  * \param con context to lock
1088  *
1089  * \retval 0 on success
1090  * \retval -1 on failure
1091  */
1092 int ast_wrlock_context(struct ast_context *con);
1093 
1094 /*!
1095  * \brief Read locks a given context
1096  *
1097  * \param con context to lock
1098  *
1099  * \retval 0 on success
1100  * \retval -1 on failure
1101  */
1102 int ast_rdlock_context(struct ast_context *con);
1103 
1104 /*!
1105  * \retval Unlocks the given context
1106  *
1107  * \param con context to unlock
1108  *
1109  * \retval 0 on success
1110  * \retval -1 on failure
1111  */
1112 int ast_unlock_context(struct ast_context *con);
1113 
1114 /*!
1115  * \brief locks the macrolock in the given context
1116  *
1117  * \param macrocontext name of the macro-context to lock
1118  *
1119  * Locks the given macro-context to ensure only one thread (call) can execute it at a time
1120  *
1121  * \retval 0 on success
1122  * \retval -1 on failure
1123  */
1124 int ast_context_lockmacro(const char *macrocontext);
1125 
1126 /*!
1127  * \brief Unlocks the macrolock in the given context
1128  *
1129  * \param macrocontext name of the macro-context to unlock
1130  *
1131  * Unlocks the given macro-context so that another thread (call) can execute it
1132  *
1133  * \retval 0 on success
1134  * \retval -1 on failure
1135  */
1136 int ast_context_unlockmacro(const char *macrocontext);
1137 
1138 /*!
1139  * \brief Set the channel to next execute the specified dialplan location.
1140  * \see ast_async_parseable_goto, ast_async_goto_if_exists
1141  *
1142  * \note Do _NOT_ hold any channel locks when calling this function.
1143  */
1144 int ast_async_goto(struct ast_channel *chan, const char *context, const char *exten, int priority);
1145 
1146 /*!
1147  * \brief Set the channel to next execute the specified dialplan location.
1148  */
1149 int ast_async_goto_by_name(const char *chan, const char *context, const char *exten, int priority);
1150 
1152  AST_OUTGOING_NO_WAIT = 0, /*!< Don't wait for originated call to answer */
1153  AST_OUTGOING_WAIT = 1, /*!< Wait for originated call to answer */
1154  AST_OUTGOING_WAIT_COMPLETE = 2, /*!< Wait for originated call to answer and hangup */
1155 };
1156 
1157 /*!
1158  * \brief Synchronously or asynchronously make an outbound call and send it to a
1159  * particular extension
1160  *
1161  * \param type The channel technology to create
1162  * \param cap The format capabilities for the channel
1163  * \param addr Address data to pass to the channel technology driver
1164  * \param timeout How long we should attempt to dial the outbound channel
1165  * \param context The destination context for the outbound channel
1166  * \param exten The destination extension for the outbound channel
1167  * \param priority The destination priority for the outbound channel
1168  * \param reason Optional. If provided, the dialed status of the outgoing channel.
1169  * Codes are AST_CONTROL_xxx values. Valid only if synchronous is non-zero.
1170  * \param synchronous defined by the ast_pbx_outgoing_sync enum.
1171  * If \c AST_OUTGOING_NO_WAIT then don't wait for anything.
1172  * If \c AST_OUTGOING_WAIT then block until the outbound channel answers or
1173  * the call fails.
1174  * If \c AST_OUTGOING_WAIT_COMPLETE then wait for the call to complete or
1175  * fail.
1176  * If \c AST_OUTGOING_WAIT or \c AST_OUTGOING_WAIT_COMPLETE is specified,
1177  * the call doesn't answer, and \c failed@context exists then run a channel
1178  * named \c OutgoingSpoolFailed at \c failed@context.
1179  * \param cid_num The caller ID number to set on the outbound channel
1180  * \param cid_name The caller ID name to set on the outbound channel
1181  * \param vars Variables to set on the outbound channel
1182  * \param account The accountcode for the outbound channel
1183  * \param locked_channel Optional. The outbound channel that was created if success
1184  * is returned. Otherwise it is set to NULL. This is returned both locked
1185  * and reference bumped.
1186  * \param early_media If non-zero the channel "answers" when progress is indicated.
1187  * \param assignedids Optional. The uniqueid(s) to assign the channel(s) that are created.
1188  *
1189  * \retval 0 on success
1190  * \retval -1 on failure
1191  */
1192 int ast_pbx_outgoing_exten(const char *type, struct ast_format_cap *cap, const char *addr,
1193  int timeout, const char *context, const char *exten, int priority, int *reason,
1194  int synchronous, const char *cid_num, const char *cid_name, struct ast_variable *vars,
1195  const char *account, struct ast_channel **locked_channel, int early_media,
1196  const struct ast_assigned_ids *assignedids);
1197 
1198 int ast_pbx_outgoing_exten_predial(const char *type, struct ast_format_cap *cap, const char *addr,
1199  int timeout, const char *context, const char *exten, int priority, int *reason,
1200  int synchronous, const char *cid_num, const char *cid_name, struct ast_variable *vars,
1201  const char *account, struct ast_channel **locked_channel, int early_media,
1202  const struct ast_assigned_ids *assignedids, const char *predial_callee);
1203 
1204 /*!
1205  * \brief Synchronously or asynchronously make an outbound call and execute an
1206  * application on the channel.
1207  *
1208  * Note that when the application stops executing, the channel is hungup.
1209  *
1210  * \param type The channel technology to create
1211  * \param cap The format capabilities for the channel
1212  * \param addr Address data to pass to the channel technology driver
1213  * \param timeout How long we should attempt to dial the outbound channel
1214  * \param app The name of the application to execute
1215  * \param appdata Data to pass to the application
1216  * \param reason Optional. If provided, the dialed status of the outgoing channel.
1217  * Codes are AST_CONTROL_xxx values. Valid only if synchronous is non-zero.
1218  * \param synchronous defined by the ast_pbx_outgoing_sync enum.
1219  * If \c AST_OUTGOING_NO_WAIT then don't wait for anything.
1220  * If \c AST_OUTGOING_WAIT then block until the outbound channel answers or
1221  * the call fails.
1222  * If \c AST_OUTGOING_WAIT_COMPLETE then wait for the call to complete or
1223  * fail.
1224  * \param cid_num The caller ID number to set on the outbound channel
1225  * \param cid_name The caller ID name to set on the outbound channel
1226  * \param vars Variables to set on the outbound channel
1227  * \param account The accountcode for the outbound channel
1228  * \param locked_channel Optional. The outbound channel that was created if success
1229  * is returned. Otherwise it is set to NULL. This is returned both locked
1230  * and reference bumped.
1231  * \param assignedids Optional. The uniqueid(s) to assign the channel(s) that are created.
1232  *
1233  * \retval 0 on success
1234  * \retval -1 on failure
1235  */
1236 int ast_pbx_outgoing_app(const char *type, struct ast_format_cap *cap, const char *addr,
1237  int timeout, const char *app, const char *appdata, int *reason, int synchronous,
1238  const char *cid_num, const char *cid_name, struct ast_variable *vars,
1239  const char *account, struct ast_channel **locked_channel,
1240  const struct ast_assigned_ids *assignedids);
1241 
1242 int ast_pbx_outgoing_app_predial(const char *type, struct ast_format_cap *cap, const char *addr,
1243  int timeout, const char *app, const char *appdata, int *reason, int synchronous,
1244  const char *cid_num, const char *cid_name, struct ast_variable *vars,
1245  const char *account, struct ast_channel **locked_channel,
1246  const struct ast_assigned_ids *assignedids, const char *predial_callee);
1247 
1248 /*!
1249  * \brief Evaluate a condition
1250  *
1251  * \retval 0 if the condition is NULL or of zero length
1252  * \retval int If the string is an integer, the integer representation of
1253  * the integer is returned
1254  * \retval 1 Any other non-empty string
1255  */
1256 int pbx_checkcondition(const char *condition);
1257 
1258 /*! @name
1259  * Functions for returning values from structures */
1260 /*! @{ */
1261 const char *ast_get_context_name(struct ast_context *con);
1262 const char *ast_get_extension_name(struct ast_exten *exten);
1263 struct ast_context *ast_get_extension_context(struct ast_exten *exten);
1264 const char *ast_get_include_name(const struct ast_include *include);
1265 const char *ast_get_ignorepat_name(const struct ast_ignorepat *ip);
1266 const char *ast_get_switch_name(const struct ast_sw *sw);
1267 const char *ast_get_switch_data(const struct ast_sw *sw);
1268 int ast_get_switch_eval(const struct ast_sw *sw);
1269 
1270 /*! @} */
1271 
1272 /*! @name Other Extension stuff */
1273 /*! @{ */
1274 int ast_get_extension_priority(struct ast_exten *exten);
1275 int ast_get_extension_matchcid(struct ast_exten *e);
1276 const char *ast_get_extension_cidmatch(struct ast_exten *e);
1277 const char *ast_get_extension_app(struct ast_exten *e);
1278 const char *ast_get_extension_label(struct ast_exten *e);
1279 void *ast_get_extension_app_data(struct ast_exten *e);
1280 /*! @} */
1281 
1282 /*! @name Registrar info functions ... */
1283 /*! @{ */
1284 const char *ast_get_context_registrar(struct ast_context *c);
1285 const char *ast_get_extension_registrar(struct ast_exten *e);
1286 const char *ast_get_include_registrar(const struct ast_include *i);
1287 const char *ast_get_ignorepat_registrar(const struct ast_ignorepat *ip);
1288 const char *ast_get_switch_registrar(const struct ast_sw *sw);
1289 /*! @} */
1290 
1291 /*!
1292  * \brief Get name of configuration file used by registrar to register this extension
1293  *
1294  * \retval NULL if registrar did not indicate config file when registering the extension
1295  * \retval name of the file used to register the extension
1296  */
1297 const char *ast_get_extension_registrar_file(struct ast_exten *e);
1298 
1299 /*!
1300  * \brief Get line number of configuration file used by registrar to register this extension
1301  *
1302  * \retval 0 if the line wasn't indicated when the extension was registered
1303  * \retval positive integer indicating what line in the config file was responsible for
1304  * registering the extension.
1305  */
1307 
1308 /*! @name Walking functions ... */
1309 /*! @{ */
1310 struct ast_context *ast_walk_contexts(struct ast_context *con);
1312  struct ast_exten *priority);
1313 struct ast_exten *ast_walk_extension_priorities(struct ast_exten *exten,
1314  struct ast_exten *priority);
1315 const struct ast_include *ast_walk_context_includes(const struct ast_context *con,
1316  const struct ast_include *inc);
1317 const struct ast_ignorepat *ast_walk_context_ignorepats(const struct ast_context *con,
1318  const struct ast_ignorepat *ip);
1319 const struct ast_sw *ast_walk_context_switches(const struct ast_context *con,
1320  const struct ast_sw *sw);
1321 /*! @} */
1322 
1323 /*! @name Iterator functions ... */
1324 /*! @{ */
1325 int ast_context_includes_count(const struct ast_context *con);
1326 const struct ast_include *ast_context_includes_get(const struct ast_context *con, int idx);
1327 int ast_context_ignorepats_count(const struct ast_context *con);
1328 const struct ast_ignorepat *ast_context_ignorepats_get(const struct ast_context *con, int idx);
1329 int ast_context_switches_count(const struct ast_context *con);
1330 const struct ast_sw *ast_context_switches_get(const struct ast_context *con, int idx);
1331 /*! @} */
1332 
1333 /*!
1334  * \brief Create a human-readable string, specifying all variables and their corresponding values.
1335  * \param chan Channel from which to read variables
1336  * \param buf Dynamic string in which to place the result (should be allocated with ast_str_create).
1337  * \see ast_str_create
1338  * \note Will lock the channel.
1339  */
1340 int pbx_builtin_serialize_variables(struct ast_channel *chan, struct ast_str **buf);
1341 
1342 /*!
1343  * \brief Return a pointer to the value of the corresponding channel variable.
1344  * \note Will lock the channel.
1345  *
1346  * \note This function will return a pointer to the buffer inside the channel
1347  * variable. This value should only be accessed with the channel locked. If
1348  * the value needs to be kept around, it should be done by using the following
1349  * thread-safe code:
1350  * \code
1351  * const char *var;
1352  *
1353  * ast_channel_lock(chan);
1354  * if ((var = pbx_builtin_getvar_helper(chan, "MYVAR"))) {
1355  * var = ast_strdupa(var);
1356  * }
1357  * ast_channel_unlock(chan);
1358  * \endcode
1359  */
1360 const char *pbx_builtin_getvar_helper(struct ast_channel *chan, const char *name);
1361 
1362 /*!
1363  * \brief Add a variable to the channel variable stack, without removing any previously set value.
1364  * \note Will lock the channel.
1365  */
1366 void pbx_builtin_pushvar_helper(struct ast_channel *chan, const char *name, const char *value);
1367 
1368 /*!
1369  * \brief Add a variable to the channel variable stack, removing the most recently set value for the same name.
1370  * \note Will lock the channel. May also be used to set a channel dialplan function to a particular value.
1371  * \see ast_func_write
1372  * \return -1 if the dialplan function fails to be set
1373  * \version 1.8 changed the function to return an error code
1374  */
1375 int pbx_builtin_setvar_helper(struct ast_channel *chan, const char *name, const char *value);
1376 
1377 /*!
1378  * \brief Retrieve the value of a builtin variable or variable from the channel variable stack.
1379  * \note Will lock the channel.
1380  */
1381 void pbx_retrieve_variable(struct ast_channel *c, const char *var, char **ret, char *workspace, int workspacelen, struct varshead *headp);
1382 void pbx_builtin_clear_globals(void);
1383 
1384 /*!
1385  * \brief Parse and set a single channel variable, where the name and value are separated with an '=' character.
1386  * \note Will lock the channel.
1387  */
1388 int pbx_builtin_setvar(struct ast_channel *chan, const char *data);
1389 
1390 /*!
1391  * \brief Parse and set multiple channel variables, where the pairs are separated by the ',' character, and name and value are separated with an '=' character.
1392  * \note Will lock the channel.
1393  */
1394 int pbx_builtin_setvar_multiple(struct ast_channel *chan, const char *data);
1395 
1396 int pbx_builtin_raise_exception(struct ast_channel *chan, const char *data);
1397 
1398 /*! @name Substitution routines, using static string buffers
1399  * @{ */
1400 void pbx_substitute_variables_helper(struct ast_channel *c, const char *cp1, char *cp2, int count);
1401 void pbx_substitute_variables_varshead(struct varshead *headp, const char *cp1, char *cp2, int count);
1402 void pbx_substitute_variables_helper_full(struct ast_channel *c, struct varshead *headp, const char *cp1, char *cp2, int cp2_size, size_t *used);
1403 /*! @} */
1404 /*! @} */
1405 
1406 /*! @name Substitution routines, using dynamic string buffers */
1407 
1408 /*!
1409  * \param buf Result will be placed in this buffer.
1410  * \param maxlen -1 if the buffer should not grow, 0 if the buffer may grow to any size, and >0 if the buffer should grow only to that number of bytes.
1411  * \param chan Channel variables from which to extract values, and channel to pass to any dialplan functions.
1412  * \param headp If no channel is specified, a channel list from which to extract variable values
1413  * \param var Variable name to retrieve.
1414  */
1415 const char *ast_str_retrieve_variable(struct ast_str **buf, ssize_t maxlen, struct ast_channel *chan, struct varshead *headp, const char *var);
1416 
1417 /*!
1418  * \param buf Result will be placed in this buffer.
1419  * \param maxlen -1 if the buffer should not grow, 0 if the buffer may grow to any size, and >0 if the buffer should grow only to that number of bytes.
1420  * \param chan Channel variables from which to extract values, and channel to pass to any dialplan functions.
1421  * \param templ Variable template to expand.
1422  */
1423 void ast_str_substitute_variables(struct ast_str **buf, ssize_t maxlen, struct ast_channel *chan, const char *templ);
1424 
1425 /*!
1426  * \param buf Result will be placed in this buffer.
1427  * \param maxlen -1 if the buffer should not grow, 0 if the buffer may grow to any size, and >0 if the buffer should grow only to that number of bytes.
1428  * \param headp If no channel is specified, a channel list from which to extract variable values
1429  * \param templ Variable template to expand.
1430  */
1431 void ast_str_substitute_variables_varshead(struct ast_str **buf, ssize_t maxlen, struct varshead *headp, const char *templ);
1432 
1433 /*!
1434  * \param buf Result will be placed in this buffer.
1435  * \param maxlen -1 if the buffer should not grow, 0 if the buffer may grow to any size, and >0 if the buffer should grow only to that number of bytes.
1436  * \param c Channel variables from which to extract values, and channel to pass to any dialplan functions.
1437  * \param headp If no channel is specified, a channel list from which to extract variable values
1438  * \param templ Variable template to expand.
1439  * \param used Number of bytes read from the template. (May be NULL)
1440  */
1441 void ast_str_substitute_variables_full(struct ast_str **buf, ssize_t maxlen, struct ast_channel *c, struct varshead *headp, const char *templ, size_t *used);
1442 /*! @} */
1443 
1444 int ast_extension_patmatch(const char *pattern, const char *data);
1445 
1446 /*! Set "autofallthrough" flag, if newval is <0, does not actually set. If
1447  set to 1, sets to auto fall through. If newval set to 0, sets to no auto
1448  fall through (reads extension instead). Returns previous value. */
1449 int pbx_set_autofallthrough(int newval);
1450 
1451 /*! Set "extenpatternmatchnew" flag, if newval is <0, does not actually set. If
1452  set to 1, sets to use the new Trie-based pattern matcher. If newval set to 0, sets to use
1453  the old linear-search algorithm. Returns previous value. */
1454 int pbx_set_extenpatternmatchnew(int newval);
1455 
1456 /*! Set "overrideswitch" field. If set and of nonzero length, all contexts
1457  * will be tried directly through the named switch prior to any other
1458  * matching within that context.
1459  * \since 1.6.1
1460  */
1461 void pbx_set_overrideswitch(const char *newval);
1462 
1463 /*!
1464  * \note This function will handle locking the channel as needed.
1465  */
1466 int ast_goto_if_exists(struct ast_channel *chan, const char *context, const char *exten, int priority);
1467 
1468 /*!
1469  * \note This function will handle locking the channel as needed.
1470  */
1471 int ast_parseable_goto(struct ast_channel *chan, const char *goto_string);
1472 
1473 /*!
1474  * \note This function will handle locking the channel as needed.
1475  */
1476 int ast_async_parseable_goto(struct ast_channel *chan, const char *goto_string);
1477 
1478 /*!
1479  * \note This function will handle locking the channel as needed.
1480  */
1481 int ast_explicit_goto(struct ast_channel *chan, const char *context, const char *exten, int priority);
1482 
1483 /*!
1484  * \note This function will handle locking the channel as needed.
1485  */
1486 int ast_async_goto_if_exists(struct ast_channel *chan, const char *context, const char *exten, int priority);
1487 
1488 struct ast_custom_function* ast_custom_function_find(const char *name);
1489 
1490 /*!
1491  * \brief Unregister a custom function
1492  */
1494 
1495 /*!
1496  * \brief Description of the ways in which a function may escalate privileges.
1497  */
1503 };
1504 
1505 /*!
1506  * \brief Register a custom function
1507  */
1508 #define ast_custom_function_register(acf) __ast_custom_function_register(acf, AST_MODULE_SELF)
1509 
1510 /*!
1511  * \brief Register a custom function which requires escalated privileges.
1512  *
1513  * Examples would be SHELL() (for which a read needs permission to execute
1514  * arbitrary code) or FILE() (for which write needs permission to change files
1515  * on the filesystem).
1516  */
1517 #define ast_custom_function_register_escalating(acf, escalation) __ast_custom_function_register_escalating(acf, escalation, AST_MODULE_SELF)
1518 
1519 /*!
1520  * \brief Register a custom function
1521  */
1523 
1524 /*!
1525  * \brief Register a custom function which requires escalated privileges.
1526  *
1527  * Examples would be SHELL() (for which a read needs permission to execute
1528  * arbitrary code) or FILE() (for which write needs permission to change files
1529  * on the filesystem).
1530  */
1532 
1533 /*!
1534  * \brief Retrieve the number of active calls
1535  */
1536 int ast_active_calls(void);
1537 
1538 /*!
1539  * \brief Retrieve the total number of calls processed through the PBX since last restart
1540  */
1541 int ast_processed_calls(void);
1542 
1543 /*!
1544  * \brief executes a read operation on a function
1545  *
1546  * \param chan Channel to execute on
1547  * \param function Data containing the function call string (will be modified)
1548  * \param workspace A pointer to safe memory to use for a return value
1549  * \param len the number of bytes in workspace
1550  *
1551  * This application executes a function in read mode on a given channel.
1552  *
1553  * \retval 0 success
1554  * \retval non-zero failure
1555  */
1556 int ast_func_read(struct ast_channel *chan, const char *function, char *workspace, size_t len);
1557 
1558 /*!
1559  * \brief executes a read operation on a function
1560  *
1561  * \param chan Channel to execute on
1562  * \param function Data containing the function call string (will be modified)
1563  * \param str A dynamic string buffer into which to place the result.
1564  * \param maxlen <0 if the dynamic buffer should not grow; >0 if the dynamic buffer should be limited to that number of bytes; 0 if the dynamic buffer has no upper limit
1565  *
1566  * This application executes a function in read mode on a given channel.
1567  *
1568  * \retval 0 success
1569  * \retval non-zero failure
1570  */
1571 int ast_func_read2(struct ast_channel *chan, const char *function, struct ast_str **str, ssize_t maxlen);
1572 
1573 /*!
1574  * \brief executes a write operation on a function
1575  *
1576  * \param chan Channel to execute on
1577  * \param function Data containing the function call string (will be modified)
1578  * \param value A value parameter to pass for writing
1579  *
1580  * This application executes a function in write mode on a given channel.
1581  *
1582  * \retval 0 success
1583  * \retval non-zero failure
1584  */
1585 int ast_func_write(struct ast_channel *chan, const char *function, const char *value);
1586 
1587 /*!
1588  * \details
1589  * When looking up extensions, we can have different requests
1590  * identified by the 'action' argument, as follows.
1591  *
1592  * \note that the coding is such that the low 4 bits are the
1593  * third argument to extension_match_core.
1594  */
1596  E_MATCHMORE = 0x00, /* extension can match but only with more 'digits' */
1597  E_CANMATCH = 0x01, /* extension can match with or without more 'digits' */
1598  E_MATCH = 0x02, /* extension is an exact match */
1599  E_MATCH_MASK = 0x03, /* mask for the argument to extension_match_core() */
1600  E_SPAWN = 0x12, /* want to spawn an extension. Requires exact match */
1601  E_FINDLABEL = 0x22 /* returns the priority for a given label. Requires exact match */
1602 };
1603 
1604 #define STATUS_NO_CONTEXT 1
1605 #define STATUS_NO_EXTENSION 2
1606 #define STATUS_NO_PRIORITY 3
1607 #define STATUS_NO_LABEL 4
1608 #define STATUS_SUCCESS 5
1609 
1610 #ifdef LOW_MEMORY
1611 #define AST_PBX_MAX_STACK 128
1612 #else
1613 #define AST_PBX_MAX_STACK 512
1614 #endif
1615 
1616 /* request and result for pbx_find_extension */
1617 struct pbx_find_info {
1618 #if 0
1619  const char *context;
1620  const char *exten;
1621  int priority;
1622 #endif
1623 
1624  char *incstack[AST_PBX_MAX_STACK]; /* filled during the search */
1625  int stacklen; /* modified during the search */
1626  int status; /* set on return */
1627  struct ast_switch *swo; /* set on return */
1628  const char *data; /* set on return */
1629  const char *foundcontext; /* set on return */
1630 };
1631 
1632 struct ast_exten *pbx_find_extension(struct ast_channel *chan,
1633  struct ast_context *bypass, struct pbx_find_info *q,
1634  const char *context, const char *exten, int priority,
1635  const char *label, const char *callerid, enum ext_match_t action);
1636 
1637 /*! \brief hashtable functions for contexts */
1638 /*! @{ */
1639 int ast_hashtab_compare_contexts(const void *ah_a, const void *ah_b);
1640 unsigned int ast_hashtab_hash_contexts(const void *obj);
1641 /*! @} */
1642 
1643 /*!
1644  * \brief Command completion for the list of installed applications.
1645  *
1646  * This can be called from a CLI command completion function that wants to
1647  * complete from the list of available applications.
1648  */
1649 char *ast_complete_applications(const char *line, const char *word, int state);
1650 
1651 /*!
1652  * \brief Enable/disable the execution of 'dangerous' functions from external
1653  * protocols (AMI, etc.).
1654  *
1655  * These dialplan functions (such as \c SHELL) provide an opportunity for
1656  * privilege escalation. They are okay to invoke from the dialplan, but external
1657  * protocols with permission controls should not normally invoke them.
1658  *
1659  * This function can globally enable/disable the execution of dangerous
1660  * functions from external protocols.
1661  *
1662  * \param new_live_dangerously If true, enable the execution of escalating
1663  * functions from external protocols.
1664  */
1665 void pbx_live_dangerously(int new_live_dangerously);
1666 
1667 /*!
1668  * \brief Inhibit (in the current thread) the execution of dialplan functions
1669  * which cause privilege escalations. If pbx_live_dangerously() has been
1670  * called, this function has no effect.
1671  *
1672  * \return 0 if successfuly marked current thread.
1673  * \return Non-zero if marking current thread failed.
1674  */
1676 
1677 /*!
1678  * \brief Swap the current thread escalation inhibit setting.
1679  * \since 11.24.0
1680  *
1681  * \param inhibit New setting. Non-zero to inhibit.
1682  *
1683  * \retval 1 if dangerous function execution was inhibited.
1684  * \retval 0 if dangerous function execution was allowed.
1685  * \retval -1 on error.
1686  */
1687 int ast_thread_inhibit_escalations_swap(int inhibit);
1688 
1689 #if defined(__cplusplus) || defined(c_plusplus)
1690 }
1691 #endif
1692 
1693 #endif /* _ASTERISK_PBX_H */
const char * name
Definition: pbx.h:119
ast_include: include= support in extensions.conf
Definition: pbx_include.c:37
static const char synopsis[]
Definition: app_mysql.c:64
int ast_hashtab_compare_contexts(const void *ah_a, const void *ah_b)
hashtable functions for contexts
Definition: ael_main.c:589
static const char type[]
Definition: chan_ooh323.c:109
int hastime
Definition: pbx.h:172
int ast_unlock_context(struct ast_context *con)
Definition: pbx.c:8530
Options for ast_pbx_run()
Definition: pbx.h:391
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:4141
void ast_pbx_h_exten_run(struct ast_channel *chan, const char *context)
Run the h exten from the given context.
Definition: pbx.c:4209
const char * ast_get_switch_name(const struct ast_sw *sw)
Definition: pbx_sw.c:48
const char * ast_get_switch_registrar(const struct ast_sw *sw)
Definition: pbx_sw.c:63
int ast_extension_state_add_destroy_extended(const char *context, const char *exten, ast_state_cb_type change_cb, ast_state_cb_destroy_type destroy_cb, void *data)
Add watcher for extended extension states with destructor.
Definition: pbx.c:3831
int ast_matchmore_extension(struct ast_channel *c, const char *context, const char *exten, int priority, const char *callerid)
Looks to see if adding anything to this extension might match something. (exists ^ canmatch) ...
Definition: pbx.c:4199
int ast_func_read(struct ast_channel *chan, const char *function, char *workspace, size_t len)
executes a read operation on a function
static char exten[AST_MAX_EXTENSION]
Definition: chan_alsa.c:118
Main Channel structure associated with a channel.
int ast_check_timing2(const struct ast_timing *i, const struct timeval tv)
Evaluate a pre-constructed bitmap as to whether a particular time falls within the range specified...
Definition: pbx_timing.c:251
ast_device_state
Device States.
Definition: devicestate.h:52
unsigned int daymask
Definition: pbx.h:174
int ast_get_extension_priority(struct ast_exten *exten)
Definition: pbx.c:8558
ast_extension_states
Extension states.
Definition: pbx.h:61
ast_exten: An extension The dialplan is saved as a linked list with each context having it&#39;s own link...
Definition: pbx.c:237
int ast_extension_state_add_extended(const char *context, const char *exten, ast_state_cb_type change_cb, void *data)
Add watcher for extended extension states.
Definition: pbx.c:3837
int ast_context_remove_include(const char *context, const char *include, const char *registrar)
Remove a context include.
Definition: pbx.c:4840
const char * presence_message
Definition: pbx.h:108
int ast_context_remove_ignorepat(const char *context, const char *ignorepat, const char *registrar)
Definition: pbx.c:6837
int ast_active_calls(void)
Retrieve the number of active calls.
Definition: pbx.c:4764
const struct ast_sw * ast_walk_context_switches(const struct ast_context *con, const struct ast_sw *sw)
Definition: pbx.c:8623
void pbx_builtin_clear_globals(void)
const char * ast_get_extension_registrar(struct ast_exten *e)
Definition: pbx.c:8571
const char * ast_get_context_name(struct ast_context *con)
Definition: ael_main.c:421
ast_switch_f * exec
Definition: pbx.h:167
int pbx_exec(struct ast_channel *c, struct ast_app *app, const char *data)
Execute an application.
Definition: pbx_app.c:471
const char * ast_get_ignorepat_registrar(const struct ast_ignorepat *ip)
Definition: pbx_ignorepat.c:47
int __ast_custom_function_register_escalating(struct ast_custom_function *acf, enum ast_custom_function_escalation escalation, struct ast_module *mod)
Register a custom function which requires escalated privileges.
int ast_findlabel_extension2(struct ast_channel *c, struct ast_context *con, const char *exten, const char *label, const char *callerid)
Find the priority of an extension that has the specified label.
Definition: extconf.c:4978
Device state management.
int ast_context_lockmacro(const char *macrocontext)
locks the macrolock in the given context
Definition: pbx.c:5162
int ast_extension_state_del(int id, ast_state_cb_type change_cb)
Deletes a state change watcher by ID.
Definition: pbx.c:3858
char buf[BUFSIZE]
Definition: eagi_proxy.c:66
int ast_func_read2(struct ast_channel *chan, const char *function, struct ast_str **str, ssize_t maxlen)
executes a read operation on a function
Channel Variables.
ast_switch_f * matchmore
Definition: pbx.h:168
char device_name[1]
Definition: pbx.h:99
enum ast_pbx_result ast_pbx_start(struct ast_channel *c)
Create a new thread and start the PBX.
Definition: pbx.c:4712
int ast_extension_cmp(const char *a, const char *b)
Determine if one extension should match before another.
Definition: pbx.c:2183
void ast_pbx_hangup_handler_init(struct ast_channel *chan)
Init the hangup handler container on a channel.
int ast_context_switches_count(const struct ast_context *con)
Definition: pbx.c:8652
const char * ast_get_extension_app(struct ast_exten *e)
Definition: pbx.c:8596
uint64_t __padding
Definition: pbx.h:395
ast_custom_function_escalation
Description of the ways in which a function may escalate privileges.
Definition: pbx.h:1498
char * ast_complete_applications(const char *line, const char *word, int state)
Command completion for the list of installed applications.
Definition: pbx_app.c:429
static int timeout
Definition: cdr_mysql.c:86
Generic (perhaps overly so) hashtable implementation Hash Table support in Asterisk.
Structure for variables, used for configurations and for channel variables.
int ast_context_add_switch2(struct ast_context *con, const char *sw, const char *data, int eval, const char *registrar)
Adds a switch (first param is a ast_context)
Definition: ael_main.c:370
#define var
Definition: ast_expr2f.c:614
int pbx_checkcondition(const char *condition)
Evaluate a condition.
Definition: pbx.c:8321
void ast_str_substitute_variables(struct ast_str **buf, ssize_t maxlen, struct ast_channel *chan, const char *templ)
struct ast_context * ast_walk_contexts(struct ast_context *con)
Definition: conf2ael.c:618
static const char desc[]
Definition: cdr_mysql.c:73
Structure to pass both assignedid values to channel drivers.
Definition: channel.h:605
int ast_ignore_pattern(const char *context, const char *pattern)
Checks to see if a number should be ignored.
Definition: pbx.c:6921
int ast_pbx_outgoing_exten_predial(const char *type, struct ast_format_cap *cap, const char *addr, int timeout, const char *context, const char *exten, int priority, int *reason, int synchronous, const char *cid_num, const char *cid_name, struct ast_variable *vars, const char *account, struct ast_channel **locked_channel, int early_media, const struct ast_assigned_ids *assignedids, const char *predial_callee)
Definition: pbx.c:7961
void ast_unregister_switch(struct ast_switch *sw)
Unregister an alternative switch.
Definition: pbx_switch.c:76
void * ast_get_extension_app_data(struct ast_exten *e)
Definition: pbx.c:8601
int ast_rdlock_contexts(void)
Read locks the context list.
Definition: pbx.c:8507
const char * ast_get_extension_label(struct ast_exten *e)
Definition: pbx.c:8553
const char * ast_get_include_registrar(const struct ast_include *i)
Definition: pbx_include.c:60
int ast_pbx_hangup_handler_pop(struct ast_channel *chan)
Pop the top of the channel hangup handler stack.
#define AST_DECLARE_STRING_FIELDS(field_list)
Declare the fields needed in a structure.
Definition: stringfields.h:337
int ast_explicit_goto(struct ast_channel *chan, const char *context, const char *exten, int priority)
Definition: pbx.c:6987
struct ast_module * mod
Definition: pbx.h:142
int ast_wrlock_contexts(void)
Write locks the context list.
Definition: pbx.c:8502
static struct test_val c
int ast_context_remove_extension_callerid2(struct ast_context *con, const char *extension, int priority, const char *callerid, int matchcid, const char *registrar, int already_locked)
Definition: pbx.c:4987
int ast_context_remove_include2(struct ast_context *con, const char *include, const char *registrar)
Removes an include by an ast_context structure.
Definition: pbx.c:4863
const char * str
Definition: app_jack.c:147
const char * args
void pbx_builtin_pushvar_helper(struct ast_channel *chan, const char *name, const char *value)
Add a variable to the channel variable stack, without removing any previously set value...
const char * data
const char * ast_get_context_registrar(struct ast_context *c)
Definition: pbx.c:8566
unsigned int write_escalates
Definition: pbx.h:147
int value
Definition: syslog.c:37
int ast_str_get_hint(struct ast_str **hint, ssize_t hintsize, struct ast_str **name, ssize_t namesize, struct ast_channel *c, const char *context, const char *exten)
If an extension hint exists, return non-zero.
Definition: pbx.c:4159
int ast_hint_presence_state(struct ast_channel *c, const char *context, const char *exten, char **subtype, char **message)
Uses hint and presence state callback to get the presence state of an extension.
Definition: pbx.c:3226
int ast_pbx_outgoing_exten(const char *type, struct ast_format_cap *cap, const char *addr, int timeout, const char *context, const char *exten, int priority, int *reason, int synchronous, const char *cid_num, const char *cid_name, struct ast_variable *vars, const char *account, struct ast_channel **locked_channel, int early_media, const struct ast_assigned_ids *assignedids)
Synchronously or asynchronously make an outbound call and send it to a particular extension...
Definition: pbx.c:7951
static int priority
static char cid_num[AST_MAX_EXTENSION]
Definition: chan_mgcp.c:164
ast_doc_src
From where the documentation come from, this structure is useful for use it inside application/functi...
Definition: xmldoc.h:30
int ast_context_add_include(const char *context, const char *include, const char *registrar)
Add a context include.
Definition: pbx.c:6706
ast_switch_f * exists
Definition: pbx.h:165
ast_switch_f * canmatch
Definition: pbx.h:166
int ast_custom_function_unregister(struct ast_custom_function *acf)
Unregister a custom function.
int ast_canmatch_extension(struct ast_channel *c, const char *context, const char *exten, int priority, const char *callerid)
Looks for a valid matching extension.
Definition: pbx.c:4194
const char * pbx_builtin_getvar_helper(struct ast_channel *chan, const char *name)
Return a pointer to the value of the corresponding channel variable.
int ast_context_remove_extension(const char *context, const char *extension, int priority, const char *registrar)
Simply remove extension from context.
Definition: pbx.c:4952
Media Format API.
int ast_context_destroy_by_name(const char *context, const char *registrar)
Destroy a context by name.
Definition: pbx.c:8244
const char * name
Definition: pbx.h:162
unsigned int monthmask
Definition: pbx.h:173
int ast_context_remove_switch(const char *context, const char *sw, const char *data, const char *registrar)
Remove a switch.
Definition: pbx.c:4898
int ast_get_switch_eval(const struct ast_sw *sw)
Definition: pbx_sw.c:58
const struct ast_include * ast_walk_context_includes(const struct ast_context *con, const struct ast_include *inc)
Definition: conf2ael.c:657
int ast_context_add_include2(struct ast_context *con, const char *include, const char *registrar)
Add a context include.
Definition: ael_main.c:359
Definition: pbx.h:211
const struct ast_sw * ast_context_switches_get(const struct ast_context *con, int idx)
Definition: pbx.c:8657
struct ast_channel * causing_channel
Definition: pbx.h:98
struct ast_context * ast_context_find(const char *name)
Find a context.
Definition: extconf.c:4174
ast_sw: Switch statement in extensions.conf
Definition: pbx_sw.c:37
General Asterisk PBX channel definitions.
int pbx_builtin_raise_exception(struct ast_channel *chan, const char *data)
Definition: pbx_builtins.c:672
ast_state_cb_update_reason
Definition: pbx.h:89
int ast_context_add_ignorepat(const char *context, const char *ignorepat, const char *registrar)
Add an ignorepat.
Definition: pbx.c:6877
ast_presence_state
Definition: presencestate.h:26
Data structure associated with a custom dialplan function.
Definition: pbx.h:118
int(* ast_acf_write_fn_t)(struct ast_channel *chan, const char *function, char *data, const char *value)
Typedef for a custom write function.
Definition: channel.h:587
enum ast_pbx_result ast_pbx_run_args(struct ast_channel *c, struct ast_pbx_args *args)
Execute the PBX in the current thread.
Definition: pbx.c:4739
void(* ast_state_cb_destroy_type)(int id, void *data)
Typedef for devicestate and hint callback removal indication callback.
Definition: pbx.h:115
int ast_parseable_goto(struct ast_channel *chan, const char *goto_string)
Definition: pbx.c:8859
int pbx_set_extenpatternmatchnew(int newval)
Definition: pbx.c:4781
Definition: pbx.h:1600
unsigned int read_escalates
Definition: pbx.h:143
Scheduler Routines (derived from cheops)
#define AST_STRING_FIELD(name)
Declare a string field.
Definition: stringfields.h:299
structure to hold extensions
ast_ext_matchcid_types
extension matchcid types
Definition: pbx.h:77
const char * ast_extension_state2str(int extension_state)
Return string representation of the state of an extension.
Definition: pbx.c:3126
const char * presence_subtype
Definition: pbx.h:107
size_t read_max
Definition: pbx.h:139
enum ast_device_state device_state
Definition: pbx.h:97
int ast_extension_state_add_destroy(const char *context, const char *exten, ast_state_cb_type change_cb, ast_state_cb_destroy_type destroy_cb, void *data)
Add watcher for extension states with destructor.
Definition: pbx.c:3819
ast_acf_write_fn_t write
Definition: pbx.h:141
void ast_str_substitute_variables_full(struct ast_str **buf, ssize_t maxlen, struct ast_channel *c, struct varshead *headp, const char *templ, size_t *used)
int pbx_set_autofallthrough(int newval)
Definition: pbx.c:4774
const char * ast_get_extension_cidmatch(struct ast_exten *e)
Definition: pbx.c:8591
int ast_exists_extension(struct ast_channel *c, const char *context, const char *exten, int priority, const char *callerid)
Determine whether an extension exists.
Definition: pbx.c:4179
int() ast_switch_f(struct ast_channel *chan, const char *context, const char *exten, int priority, const char *callerid, const char *data)
All switch functions have the same interface, so define a type for them.
Definition: pbx.h:156
ast_pbx_result
The result codes when starting the PBX on a channel with ast_pbx_start.
Definition: pbx.h:354
#define AST_PBX_MAX_STACK
Definition: pbx.h:1613
int ast_extension_state_extended(struct ast_channel *c, const char *context, const char *exten, struct ao2_container **device_state_info)
Uses hint and devicestate callback to get the extended state of an extension.
Definition: pbx.c:3176
const char * ast_get_ignorepat_name(const struct ast_ignorepat *ip)
Definition: pbx_ignorepat.c:42
struct ao2_container * device_state_info
Definition: pbx.h:105
int ast_context_includes_count(const struct ast_context *con)
Definition: pbx.c:8697
Presence state management.
struct ast_custom_function * ast_custom_function_find(const char *name)
Definition: ael_main.c:173
int ast_processed_calls(void)
Retrieve the total number of calls processed through the PBX since last restart.
Definition: pbx.c:4769
unsigned int dowmask
Definition: pbx.h:175
ast_pbx_outgoing_sync
Definition: pbx.h:1151
ast_acf_read2_fn_t read2
Definition: pbx.h:137
The descriptor of a dynamic string XXX storage will be optimized later if needed We use the ts field ...
Definition: strings.h:584
Format capabilities structure, holds formats + preference order + etc.
Definition: format_cap.c:54
void ast_str_substitute_variables_varshead(struct ast_str **buf, ssize_t maxlen, struct varshead *headp, const char *templ)
void pbx_retrieve_variable(struct ast_channel *c, const char *var, char **ret, char *workspace, int workspacelen, struct varshead *headp)
Retrieve the value of a builtin variable or variable from the channel variable stack.
void ast_merge_contexts_and_delete(struct ast_context **extcontexts, struct ast_hashtab *exttable, const char *registrar)
Merge the temporary contexts into a global contexts list and delete from the global list the ones tha...
Definition: conf2ael.c:639
int ast_check_timing(const struct ast_timing *i)
Evaluate a pre-constructed bitmap as to whether the current time falls within the range specified...
Definition: extconf.c:4002
ast_ignorepat: Ignore patterns in dial plan
Definition: pbx_ignorepat.c:37
int ast_unlock_contexts(void)
Unlocks contexts.
Definition: pbx.c:8512
int ast_findlabel_extension(struct ast_channel *c, const char *context, const char *exten, const char *label, const char *callerid)
Find the priority of an extension that has the specified label.
Definition: pbx.c:4184
def info(msg)
static int len(struct ast_channel *chan, const char *cmd, char *data, char *buf, size_t buflen)
int ast_thread_inhibit_escalations_swap(int inhibit)
Swap the current thread escalation inhibit setting.
int ast_extension_patmatch(const char *pattern, const char *data)
int pbx_builtin_setvar_multiple(struct ast_channel *chan, const char *data)
Parse and set multiple channel variables, where the pairs are separated by the &#39;,&#39; character...
int ast_context_remove_extension_callerid(const char *context, const char *extension, int priority, const char *callerid, int matchcid, const char *registrar)
Definition: pbx.c:4957
const char * ast_get_extension_name(struct ast_exten *exten)
Definition: pbx.c:8548
int ast_wrlock_context(struct ast_context *con)
Write locks a given context.
Definition: pbx.c:8520
int ast_goto_if_exists(struct ast_channel *chan, const char *context, const char *exten, int priority)
Definition: pbx.c:8793
int ast_pbx_outgoing_app(const char *type, struct ast_format_cap *cap, const char *addr, int timeout, const char *app, const char *appdata, int *reason, int synchronous, const char *cid_num, const char *cid_name, struct ast_variable *vars, const char *account, struct ast_channel **locked_channel, const struct ast_assigned_ids *assignedids)
Synchronously or asynchronously make an outbound call and execute an application on the channel...
Definition: pbx.c:8015
struct ast_exten * ast_walk_context_extensions(struct ast_context *con, struct ast_exten *priority)
Definition: ael_main.c:427
#define AST_LIST_ENTRY(type)
Declare a forward link structure inside a list entry.
Definition: linkedlists.h:409
static char * registrar
Definition: pbx_ael.c:78
enum ast_extension_states ast_devstate_to_extenstate(enum ast_device_state devstate)
Map devstate to an extension state.
Definition: pbx.c:3006
int ast_destroy_timing(struct ast_timing *i)
Deallocates memory structures associated with a timing bitmap.
Definition: pbx_timing.c:285
static int matchcid(const char *cidpattern, const char *callerid)
Definition: pbx.c:2473
int ast_extension_match(const char *pattern, const char *extension)
Determine if a given extension matches a given pattern (in NXX format)
Definition: extconf.c:4297
unsigned int ast_hashtab_hash_contexts(const void *obj)
Definition: ael_main.c:596
void pbx_live_dangerously(int new_live_dangerously)
Enable/disable the execution of &#39;dangerous&#39; functions from external protocols (AMI, etc.).
int ast_register_switch(struct ast_switch *sw)
Register an alternative dialplan switch.
Definition: pbx_switch.c:58
void ast_pbx_hangup_handler_push(struct ast_channel *chan, const char *handler)
Push the given hangup handler onto the channel hangup handler stack.
int ast_extension_close(const char *pattern, const char *data, int needmore)
Definition: pbx.c:2418
Asterisk XML Documentation API.
const char * ast_get_switch_data(const struct ast_sw *sw)
Definition: pbx_sw.c:53
int pbx_builtin_setvar(struct ast_channel *chan, const char *data)
Parse and set a single channel variable, where the name and value are separated with an &#39;=&#39; character...
int ast_async_goto_if_exists(struct ast_channel *chan, const char *context, const char *exten, int priority)
Definition: pbx.c:8798
int ast_build_timing(struct ast_timing *i, const char *info)
Construct a timing bitmap, for use in time-based conditionals.
Definition: extconf.c:3808
int ast_spawn_extension(struct ast_channel *c, const char *context, const char *exten, int priority, const char *callerid, int *found, int combined_find_spawn)
Launch a new extension (i.e. new stack)
Definition: pbx.c:4204
static char cid_name[AST_MAX_EXTENSION]
Definition: chan_mgcp.c:165
#define AST_RWLIST_ENTRY
Definition: linkedlists.h:414
const struct ast_ignorepat * ast_walk_context_ignorepats(const struct ast_context *con, const struct ast_ignorepat *ip)
Definition: pbx.c:8707
int(* ast_acf_read2_fn_t)(struct ast_channel *chan, const char *cmd, char *data, struct ast_str **str, ssize_t len)
Typedef for a custom read2 function.
Definition: channel.h:581
int ast_pbx_hangup_handler_run(struct ast_channel *chan)
Run all hangup handlers on the channel.
static int replace(struct ast_channel *chan, const char *cmd, char *data, struct ast_str **buf, ssize_t len)
Definition: func_strings.c:790
int ast_async_parseable_goto(struct ast_channel *chan, const char *goto_string)
Definition: pbx.c:8864
int pbx_builtin_setvar_helper(struct ast_channel *chan, const char *name, const char *value)
Add a variable to the channel variable stack, removing the most recently set value for the same name...
int(* ast_acf_read_fn_t)(struct ast_channel *chan, const char *function, char *data, char *buf, size_t len)
Typedef for a custom read function.
Definition: channel.h:575
const char * ast_get_include_name(const struct ast_include *include)
Definition: pbx_include.c:50
int ast_add_extension2(struct ast_context *con, int replace, const char *extension, int priority, const char *label, const char *callerid, const char *application, void *data, void(*datad)(void *), const char *registrar, const char *registrar_file, int registrar_line)
Add an extension to an extension context, this time with an ast_context *.
Definition: pbx.c:7299
const char * ast_str_retrieve_variable(struct ast_str **buf, ssize_t maxlen, struct ast_channel *chan, struct varshead *headp, const char *var)
char * timezone
Definition: pbx.h:177
int ast_add_extension(const char *context, int replace, const char *extension, int priority, const char *label, const char *callerid, const char *application, void *data, void(*datad)(void *), const char *registrar)
Add and extension to an extension context.
Definition: pbx.c:6970
int dtimeoutms
Definition: pbx.h:212
Definition: pbx.h:1598
ast_acf_read_fn_t read
Definition: pbx.h:129
struct ast_exten * ast_walk_extension_priorities(struct ast_exten *exten, struct ast_exten *priority)
Definition: extconf.c:4063
int ast_extension_state(struct ast_channel *c, const char *context, const char *exten)
Uses hint and devicestate callback to get the state of an extension.
Definition: pbx.c:3170
ast_app: A registered application
Definition: pbx_app.c:45
ext_match_t
Definition: extconf.h:215
static void handler(const char *name, int response_code, struct ast_variable *get_params, struct ast_variable *path_vars, struct ast_variable *headers, struct ast_json *body, struct ast_ari_response *response)
Definition: test_ari.c:59
void ast_pbx_hangup_handler_destroy(struct ast_channel *chan)
Destroy the hangup handler container on a channel.
int ast_async_goto(struct ast_channel *chan, const char *context, const char *exten, int priority)
Set the channel to next execute the specified dialplan location.
Definition: pbx.c:7011
void pbx_substitute_variables_helper(struct ast_channel *c, const char *cp1, char *cp2, int count)
Definition: ael_main.c:211
int ast_get_extension_registrar_line(struct ast_exten *e)
Get line number of configuration file used by registrar to register this extension.
Definition: pbx.c:8581
void pbx_set_overrideswitch(const char *newval)
Definition: pbx.c:4788
int ast_thread_inhibit_escalations(void)
Inhibit (in the current thread) the execution of dialplan functions which cause privilege escalations...
enum ast_pbx_result ast_pbx_run(struct ast_channel *c)
Execute the PBX in the current thread.
Definition: pbx.c:4759
int ast_context_remove_extension2(struct ast_context *con, const char *extension, int priority, const char *registrar, int already_locked)
This functionc locks given context, search for the right extension and fires out all peer in this ext...
Definition: pbx.c:4982
int __ast_custom_function_register(struct ast_custom_function *acf, struct ast_module *mod)
Register a custom function.
void ast_context_destroy(struct ast_context *con, const char *registrar)
Destroy a context (matches the specified context or ANY context if NULL)
Definition: conf2ael.c:625
int ast_context_ignorepats_count(const struct ast_context *con)
Definition: pbx.c:8740
int ast_pbx_outgoing_app_predial(const char *type, struct ast_format_cap *cap, const char *addr, int timeout, const char *app, const char *appdata, int *reason, int synchronous, const char *cid_num, const char *cid_name, struct ast_variable *vars, const char *account, struct ast_channel **locked_channel, const struct ast_assigned_ids *assignedids, const char *predial_callee)
Definition: pbx.c:8025
static struct test_val b
void pbx_substitute_variables_helper_full(struct ast_channel *c, struct varshead *headp, const char *cp1, char *cp2, int cp2_size, size_t *used)
enum queue_result id
Definition: app_queue.c:1507
int ast_context_verify_includes(struct ast_context *con)
Verifies includes in an ast_contect structure.
Definition: conf2ael.c:632
int ast_context_add_ignorepat2(struct ast_context *con, const char *ignorepat, const char *registrar)
Definition: ael_main.c:348
Generic container type.
int(* ast_state_cb_type)(const char *context, const char *exten, struct ast_state_cb_info *info, void *data)
Typedef for devicestate and hint callbacks.
Definition: pbx.h:112
static char context[AST_MAX_CONTEXT]
Definition: chan_alsa.c:116
struct ast_context * ast_context_find_or_create(struct ast_context **extcontexts, struct ast_hashtab *exttable, const char *name, const char *registrar)
Register a new context or find an existing one.
Definition: pbx.c:6198
int ast_extension_state_add(const char *context, const char *exten, ast_state_cb_type change_cb, void *data)
Add watcher for extension states.
Definition: pbx.c:3825
void ast_context_set_autohints(struct ast_context *con, int enabled)
Enable or disable autohints support on a context.
Definition: pbx.c:6272
int ast_context_add_switch(const char *context, const char *sw, const char *data, int eval, const char *registrar)
Add a switch.
Definition: pbx.c:6771
struct ast_app * pbx_findapp(const char *app)
Look up an application.
Definition: ael_main.c:165
static const char app[]
Definition: app_mysql.c:62
int ast_get_extension_matchcid(struct ast_exten *e)
Definition: pbx.c:8586
unsigned int no_hangup_chan
Definition: pbx.h:398
struct ast_exten * pbx_find_extension(struct ast_channel *chan, struct ast_context *bypass, struct pbx_find_info *q, const char *context, const char *exten, int priority, const char *label, const char *callerid, enum ext_match_t action)
Definition: ael_main.c:152
int ast_context_remove_switch2(struct ast_context *con, const char *sw, const char *data, const char *registrar)
This function locks given context, removes switch, unlock context and return.
Definition: pbx.c:4920
int ast_func_write(struct ast_channel *chan, const char *function, const char *value)
executes a write operation on a function
ast_context: An extension context - must remain in sync with fake_context
Definition: pbx.c:284
int ast_context_remove_ignorepat2(struct ast_context *con, const char *ignorepat, const char *registrar)
Definition: pbx.c:6850
int ast_context_unlockmacro(const char *macrocontext)
Unlocks the macrolock in the given context.
Definition: pbx.c:5184
const struct ast_include * ast_context_includes_get(const struct ast_context *con, int idx)
Definition: pbx.c:8702
int ast_async_goto_by_name(const char *chan, const char *context, const char *exten, int priority)
Set the channel to next execute the specified dialplan location.
Definition: pbx.c:7044
int ast_add_extension2_nolock(struct ast_context *con, int replace, const char *extension, int priority, const char *label, const char *callerid, const char *application, void *data, void(*datad)(void *), const char *registrar, const char *registrar_file, int registrar_line)
Same as ast_add_extension2, but assumes you have already locked context.
Definition: pbx.c:7308
void pbx_substitute_variables_varshead(struct varshead *headp, const char *cp1, char *cp2, int count)
jack_status_t status
Definition: app_jack.c:146
struct ast_context * ast_get_extension_context(struct ast_exten *exten)
Definition: pbx.c:8543
int ast_rdlock_context(struct ast_context *con)
Read locks a given context.
Definition: pbx.c:8525
const struct ast_ignorepat * ast_context_ignorepats_get(const struct ast_context *con, int idx)
Definition: pbx.c:8745
short word
int pbx_builtin_serialize_variables(struct ast_channel *chan, struct ast_str **buf)
Create a human-readable string, specifying all variables and their corresponding values.
const char * ast_get_extension_registrar_file(struct ast_exten *e)
Get name of configuration file used by registrar to register this extension.
Definition: pbx.c:8576
int rtimeoutms
Definition: pbx.h:213
static int enabled
Definition: dnsmgr.c:91
const char * description
Definition: pbx.h:163
static struct test_val a