Wed Jan 8 2020 09:49:49

Asterisk developer's documentation


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/chanvars.h"
30 #include "asterisk/hashtab.h"
31 #include "asterisk/stringfields.h"
32 #include "asterisk/xmldoc.h"
33 #include "asterisk/frame_defs.h"
34 
35 #if defined(__cplusplus) || defined(c_plusplus)
36 extern "C" {
37 #endif
38 
39 #define AST_MAX_APP 32 /*!< Max length of an application */
40 
41 #define AST_PBX_GOTO_FAILED -3
42 #define AST_PBX_KEEP 0
43 #define AST_PBX_REPLACE 1
44 
45 /*! \brief Special return values from applications to the PBX
46  * @{ */
47 #define AST_PBX_HANGUP -1 /*!< Jump to the 'h' exten */
48 #define AST_PBX_OK 0 /*!< No errors */
49 #define AST_PBX_ERROR 1 /*!< Jump to the 'e' exten */
50 #define AST_PBX_INCOMPLETE 12 /*!< Return to PBX matching, allowing more digits for the extension */
51 /*! @} */
52 
53 #define PRIORITY_HINT -1 /*!< Special Priority for a hint */
54 
55 /*!
56  * \brief Extension states
57  * \note States can be combined
58  * \ref AstExtState
59  */
61  AST_EXTENSION_REMOVED = -2, /*!< Extension removed */
62  AST_EXTENSION_DEACTIVATED = -1, /*!< Extension hint removed */
63  AST_EXTENSION_NOT_INUSE = 0, /*!< No device INUSE or BUSY */
64  AST_EXTENSION_INUSE = 1 << 0, /*!< One or more devices INUSE */
65  AST_EXTENSION_BUSY = 1 << 1, /*!< All devices BUSY */
66  AST_EXTENSION_UNAVAILABLE = 1 << 2, /*!< All devices UNAVAILABLE/UNREGISTERED */
67  AST_EXTENSION_RINGING = 1 << 3, /*!< All devices RINGING */
68  AST_EXTENSION_ONHOLD = 1 << 4, /*!< All devices ONHOLD */
69 };
70 
71 /*!
72  * \brief extension matchcid types
73  * \note matchcid in ast_exten retains 0/1, this adds 3rd state for functions to specify all
74  * \see ast_context_remove_extension_callerid
75  */
77  AST_EXT_MATCHCID_OFF = 0, /*!< Match only extensions with matchcid=0 */
78  AST_EXT_MATCHCID_ON = 1, /*!< Match only extensions with matchcid=1 AND cidmatch matches */
79  AST_EXT_MATCHCID_ANY = 2, /*!< Match both - used only in functions manipulating ast_exten's */
80 };
81 
82 struct ast_context;
83 struct ast_exten;
84 struct ast_include;
85 struct ast_ignorepat;
86 struct ast_sw;
87 
88 /*! \brief Typedef for devicestate and hint callbacks */
89 typedef int (*ast_state_cb_type)(char *context, char *id, enum ast_extension_states state, void *data);
90 
91 /*! \brief Typedef for devicestate and hint callback removal indication callback */
92 typedef void (*ast_state_cb_destroy_type)(int id, void *data);
93 
94 /*! \brief Data structure associated with a custom dialplan function */
96  const char *name; /*!< Name */
98  AST_STRING_FIELD(synopsis); /*!< Synopsis text for 'show functions' */
99  AST_STRING_FIELD(desc); /*!< Description (help text) for 'show functions &lt;name&gt;' */
100  AST_STRING_FIELD(syntax); /*!< Syntax text for 'core show functions' */
101  AST_STRING_FIELD(arguments); /*!< Arguments description */
102  AST_STRING_FIELD(seealso); /*!< See also */
103  );
104  enum ast_doc_src docsrc; /*!< Where the documentation come from */
105  /*! Read function, if read is supported */
106  ast_acf_read_fn_t read; /*!< Read function, if read is supported */
107  /*! Read function, if read is supported. Note: only one of read or read2
108  * needs to be implemented. In new code, read2 should be implemented as
109  * the way forward, but they should return identical results, within the
110  * constraints of buffer size, if both are implemented. That is, if the
111  * read function is handed a 16-byte buffer, and the result is 17 bytes
112  * long, then the first 15 bytes (remember NULL terminator) should be
113  * the same for both the read and the read2 methods. */
115  /*! If no read2 function is provided, what maximum size? */
116  size_t read_max;
117  /*! Write function, if write is supported */
118  ast_acf_write_fn_t write; /*!< Write function, if write is supported */
119  struct ast_module *mod; /*!< Module this custom function belongs to */
121 };
122 
123 /*! \brief All switch functions have the same interface, so define a type for them */
124 typedef int (ast_switch_f)(struct ast_channel *chan, const char *context,
125  const char *exten, int priority, const char *callerid, const char *data);
126 
127 /*!< Data structure associated with an Asterisk switch */
128 struct ast_switch {
129  AST_LIST_ENTRY(ast_switch) list;
130  const char *name; /*!< Name of the switch */
131  const char *description; /*!< Description of the switch */
132 
137 };
138 
139 struct ast_timing {
140  int hastime; /*!< If time construct exists */
141  unsigned int monthmask; /*!< Mask for month */
142  unsigned int daymask; /*!< Mask for date */
143  unsigned int dowmask; /*!< Mask for day of week (sun-sat) */
144  unsigned int minmask[48]; /*!< Mask for minute */
145  char *timezone; /*!< NULL, or zoneinfo style timezone */
146 };
147 
148 /*!
149  * \brief Construct a timing bitmap, for use in time-based conditionals.
150  * \param i Pointer to an ast_timing structure.
151  * \param info Standard string containing a timerange, weekday range, monthday range, and month range, as well as an optional timezone.
152  * \retval Returns 1 on success or 0 on failure.
153  */
154 int ast_build_timing(struct ast_timing *i, const char *info);
155 
156 /*!
157  * \brief Evaluate a pre-constructed bitmap as to whether the current time falls within the range specified.
158  * \param i Pointer to an ast_timing structure.
159  * \retval Returns 1, if the time matches or 0, if the current time falls outside of the specified range.
160  */
161 int ast_check_timing(const struct ast_timing *i);
162 
163 /*!
164  * \brief Evaluate a pre-constructed bitmap as to whether a particular time falls within the range specified.
165  * \param i Pointer to an ast_timing structure.
166  * \param tv Specified time
167  * \retval Returns 1, if the time matches or 0, if the time falls outside of the specified range.
168  */
169 int ast_check_timing2(const struct ast_timing *i, const struct timeval tv);
170 
171 /*!
172  * \brief Deallocates memory structures associated with a timing bitmap.
173  * \param i Pointer to an ast_timing structure.
174  * \retval 0 success
175  * \retval non-zero failure (number suitable to pass to \see strerror)
176  */
177 int ast_destroy_timing(struct ast_timing *i);
178 
179 struct ast_pbx {
180  int dtimeoutms; /*!< Timeout between digits (milliseconds) */
181  int rtimeoutms; /*!< Timeout for response (milliseconds) */
182 };
183 
184 
185 /*!
186  * \brief Register an alternative dialplan switch
187  *
188  * \param sw switch to register
189  *
190  * This function registers a populated ast_switch structure with the
191  * asterisk switching architecture.
192  *
193  * \retval 0 success
194  * \retval non-zero failure
195  */
196 int ast_register_switch(struct ast_switch *sw);
197 
198 /*!
199  * \brief Unregister an alternative switch
200  *
201  * \param sw switch to unregister
202  *
203  * Unregisters a switch from asterisk.
204  *
205  * \return nothing
206  */
207 void ast_unregister_switch(struct ast_switch *sw);
208 
209 /*!
210  * \brief Look up an application
211  *
212  * \param app name of the app
213  *
214  * This function searches for the ast_app structure within
215  * the apps that are registered for the one with the name
216  * you passed in.
217  *
218  * \return the ast_app structure that matches on success, or NULL on failure
219  */
220 struct ast_app *pbx_findapp(const char *app);
221 
222 /*!
223  * \brief Execute an application
224  *
225  * \param c channel to execute on
226  * \param app which app to execute
227  * \param data the data passed into the app
228  *
229  * This application executes an application on a given channel. It
230  * saves the stack and executes the given application passing in
231  * the given data.
232  *
233  * \retval 0 success
234  * \retval -1 failure
235  */
236 int pbx_exec(struct ast_channel *c, struct ast_app *app, const char *data);
237 
238 /*!
239  * \brief Register a new context or find an existing one
240  *
241  * \param extcontexts pointer to the ast_context structure pointer
242  * \param exttable pointer to the hashtable that contains all the elements in extcontexts
243  * \param name name of the new context
244  * \param registrar registrar of the context
245  *
246  * This function allows you to play in two environments: the global contexts (active dialplan)
247  * or an external context set of your choosing. To act on the external set, make sure extcontexts
248  * and exttable are set; for the globals, make sure both extcontexts and exttable are NULL.
249  *
250  * This will first search for a context with your name. If it exists already, it will not
251  * create a new one. If it does not exist, it will create a new one with the given name
252  * and registrar.
253  *
254  * \return NULL on failure, and an ast_context structure on success
255  */
256 struct ast_context *ast_context_find_or_create(struct ast_context **extcontexts, struct ast_hashtab *exttable, const char *name, const char *registrar);
257 
258 /*!
259  * \brief Merge the temporary contexts into a global contexts list and delete from the
260  * global list the ones that are being added
261  *
262  * \param extcontexts pointer to the ast_context structure
263  * \param exttable pointer to the ast_hashtab structure that contains all the elements in extcontexts
264  * \param registrar of the context; if it's set the routine will delete all contexts
265  * that belong to that registrar; if NULL only the contexts that are specified
266  * in extcontexts
267  */
268 void ast_merge_contexts_and_delete(struct ast_context **extcontexts, struct ast_hashtab *exttable, const char *registrar);
269 
270 /*!
271  * \brief Destroy a context (matches the specified context (or ANY context if NULL)
272  *
273  * \param con context to destroy
274  * \param registrar who registered it
275  *
276  * You can optionally leave out either parameter. It will find it
277  * based on either the ast_context or the registrar name.
278  *
279  * \return nothing
280  */
281 void ast_context_destroy(struct ast_context *con, const char *registrar);
282 
283 /*!
284  * \brief Find a context
285  *
286  * \param name name of the context to find
287  *
288  * Will search for the context with the given name.
289  *
290  * \return the ast_context on success, NULL on failure.
291  */
292 struct ast_context *ast_context_find(const char *name);
293 
294 /*!
295  * \brief The result codes when starting the PBX on a channel with ast_pbx_start.
296  * \note AST_PBX_CALL_LIMIT refers to the maxcalls call limit in asterisk.conf
297  * \see ast_pbx_start
298  */
303 };
304 
305 /*!
306  * \brief Create a new thread and start the PBX
307  *
308  * \param c channel to start the pbx on
309  *
310  * \see ast_pbx_run for a synchronous function to run the PBX in the
311  * current thread, as opposed to starting a new one.
312  *
313  * \retval Zero on success
314  * \retval non-zero on failure
315  */
317 
318 /*!
319  * \brief Execute the PBX in the current thread
320  *
321  * \param c channel to run the pbx on
322  *
323  * This executes the PBX on a given channel. It allocates a new
324  * PBX structure for the channel, and provides all PBX functionality.
325  * See ast_pbx_start for an asynchronous function to run the PBX in a
326  * new thread as opposed to the current one.
327  *
328  * \retval Zero on success
329  * \retval non-zero on failure
330  */
331 enum ast_pbx_result ast_pbx_run(struct ast_channel *c);
332 
333 /*!
334  * \brief Options for ast_pbx_run()
335  */
336 struct ast_pbx_args {
337  union {
338  /*! Pad this out so that we have plenty of room to add options
339  * but still maintain ABI compatibility over time. */
340  uint64_t __padding;
341  struct {
342  /*! Do not hangup the channel when the PBX is complete. */
343  unsigned int no_hangup_chan:1;
344  };
345  };
346 };
347 
348 /*!
349  * \brief Execute the PBX in the current thread
350  *
351  * \param c channel to run the pbx on
352  * \param args options for the pbx
353  *
354  * This executes the PBX on a given channel. It allocates a new
355  * PBX structure for the channel, and provides all PBX functionality.
356  * See ast_pbx_start for an asynchronous function to run the PBX in a
357  * new thread as opposed to the current one.
358  *
359  * \retval Zero on success
360  * \retval non-zero on failure
361  */
363 
364 /*!
365  * \brief Add and extension to an extension context.
366  *
367  * \param context context to add the extension to
368  * \param replace
369  * \param extension extension to add
370  * \param priority priority level of extension addition
371  * \param label extension label
372  * \param callerid pattern to match CallerID, or NULL to match any CallerID
373  * \param application application to run on the extension with that priority level
374  * \param data data to pass to the application
375  * \param datad
376  * \param registrar who registered the extension
377  *
378  * \retval 0 success
379  * \retval -1 failure
380  */
381 int ast_add_extension(const char *context, int replace, const char *extension,
382  int priority, const char *label, const char *callerid,
383  const char *application, void *data, void (*datad)(void *), const char *registrar);
384 
385 /*!
386  * \brief Add an extension to an extension context, this time with an ast_context *.
387  *
388  * \note For details about the arguments, check ast_add_extension()
389  */
390 int ast_add_extension2(struct ast_context *con, int replace, const char *extension,
391  int priority, const char *label, const char *callerid,
392  const char *application, void *data, void (*datad)(void *), const char *registrar);
393 
394 /*!
395  * \brief Map devstate to an extension state.
396  *
397  * \param[in] devstate device state
398  *
399  * \return the extension state mapping.
400  */
402 
403 /*!
404  * \brief Uses hint and devicestate callback to get the state of an extension
405  *
406  * \param c this is not important
407  * \param context which context to look in
408  * \param exten which extension to get state
409  *
410  * \return extension state as defined in the ast_extension_states enum
411  */
412 int ast_extension_state(struct ast_channel *c, const char *context, const char *exten);
413 
414 /*!
415  * \brief Return string representation of the state of an extension
416  *
417  * \param extension_state is the numerical state delivered by ast_extension_state
418  *
419  * \return the state of an extension as string
420  */
421 const char *ast_extension_state2str(int extension_state);
422 
423 /*!
424  * \brief Registers a state change callback with destructor.
425  * \since 1.8.9
426  * \since 10.1.0
427  *
428  * \param context which context to look in
429  * \param exten which extension to get state
430  * \param change_cb callback to call if state changed
431  * \param destroy_cb callback to call when registration destroyed.
432  * \param data to pass to callback
433  *
434  * \note The change_cb is called if the state of an extension is changed.
435  *
436  * \note The destroy_cb is called when the registration is
437  * deleted so the registerer can release any associated
438  * resources.
439  *
440  * \retval -1 on failure
441  * \retval ID on success
442  */
443 int ast_extension_state_add_destroy(const char *context, const char *exten,
444  ast_state_cb_type change_cb, ast_state_cb_destroy_type destroy_cb, void *data);
445 
446 /*!
447  * \brief Registers a state change callback
448  *
449  * \param context which context to look in
450  * \param exten which extension to get state
451  * \param change_cb callback to call if state changed
452  * \param data to pass to callback
453  *
454  * \note The change_cb is called if the state of an extension is changed.
455  *
456  * \retval -1 on failure
457  * \retval ID on success
458  */
459 int ast_extension_state_add(const char *context, const char *exten,
460  ast_state_cb_type change_cb, void *data);
461 
462 /*!
463  * \brief Deletes a registered state change callback by ID
464  *
465  * \param id of the registered state callback to delete
466  * \param change_cb callback to call if state changed (Used if id == 0 (global))
467  *
468  * \retval 0 success
469  * \retval -1 failure
470  */
471 int ast_extension_state_del(int id, ast_state_cb_type change_cb);
472 
473 /*!
474  * \brief If an extension hint exists, return non-zero
475  *
476  * \param hint buffer for hint
477  * \param hintsize size of hint buffer, in bytes
478  * \param name buffer for name portion of hint
479  * \param namesize size of name buffer
480  * \param c Channel from which to return the hint. This is only important when the hint or name contains an expression to be expanded.
481  * \param context which context to look in
482  * \param exten which extension to search for
483  *
484  * \return If an extension within the given context with the priority PRIORITY_HINT
485  * is found, a non zero value will be returned.
486  * Otherwise, 0 is returned.
487  */
488 int ast_get_hint(char *hint, int hintsize, char *name, int namesize,
489  struct ast_channel *c, const char *context, const char *exten);
490 
491 /*!
492  * \brief If an extension hint exists, return non-zero
493  *
494  * \param hint buffer for hint
495  * \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)
496  * \param name buffer for name portion of hint
497  * \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)
498  * \param c Channel from which to return the hint. This is only important when the hint or name contains an expression to be expanded.
499  * \param context which context to look in
500  * \param exten which extension to search for
501  *
502  * \return If an extension within the given context with the priority PRIORITY_HINT
503  * is found, a non zero value will be returned.
504  * Otherwise, 0 is returned.
505  */
506 int ast_str_get_hint(struct ast_str **hint, ssize_t hintsize, struct ast_str **name, ssize_t namesize,
507  struct ast_channel *c, const char *context, const char *exten);
508 
509 /*!
510  * \brief Determine whether an extension exists
511  *
512  * \param c this is not important
513  * \param context which context to look in
514  * \param exten which extension to search for
515  * \param priority priority of the action within the extension
516  * \param callerid callerid to search for
517  *
518  * \note It is possible for autoservice to be started and stopped on c during this
519  * function call, it is important that c is not locked prior to calling this. Otherwise
520  * a deadlock may occur
521  *
522  * \return If an extension within the given context(or callerid) with the given priority
523  * is found a non zero value will be returned. Otherwise, 0 is returned.
524  */
525 int ast_exists_extension(struct ast_channel *c, const char *context, const char *exten,
526  int priority, const char *callerid);
527 
528 /*!
529  * \brief Find the priority of an extension that has the specified label
530  *
531  * \param c this is not important
532  * \param context which context to look in
533  * \param exten which extension to search for
534  * \param label label of the action within the extension to match to priority
535  * \param callerid callerid to search for
536  *
537  * \note It is possible for autoservice to be started and stopped on c during this
538  * function call, it is important that c is not locked prior to calling this. Otherwise
539  * a deadlock may occur
540  *
541  * \retval the priority which matches the given label in the extension
542  * \retval -1 if not found.
543  */
544 int ast_findlabel_extension(struct ast_channel *c, const char *context,
545  const char *exten, const char *label, const char *callerid);
546 
547 /*!
548  * \brief Find the priority of an extension that has the specified label
549  *
550  * \note It is possible for autoservice to be started and stopped on c during this
551  * function call, it is important that c is not locked prior to calling this. Otherwise
552  * a deadlock may occur
553  *
554  * \note This function is the same as ast_findlabel_extension, except that it accepts
555  * a pointer to an ast_context structure to specify the context instead of the
556  * name of the context. Otherwise, the functions behave the same.
557  */
558 int ast_findlabel_extension2(struct ast_channel *c, struct ast_context *con,
559  const char *exten, const char *label, const char *callerid);
560 
561 /*!
562  * \brief Looks for a valid matching extension
563  *
564  * \param c not really important
565  * \param context context to serach within
566  * \param exten extension to check
567  * \param priority priority of extension path
568  * \param callerid callerid of extension being searched for
569  *
570  * \note It is possible for autoservice to be started and stopped on c during this
571  * function call, it is important that c is not locked prior to calling this. Otherwise
572  * a deadlock may occur
573  *
574  * \return If "exten" *could be* a valid extension in this context with or without
575  * some more digits, return non-zero. Basically, when this returns 0, no matter
576  * what you add to exten, it's not going to be a valid extension anymore
577  */
578 int ast_canmatch_extension(struct ast_channel *c, const char *context,
579  const char *exten, int priority, const char *callerid);
580 
581 /*!
582  * \brief Looks to see if adding anything to this extension might match something. (exists ^ canmatch)
583  *
584  * \param c not really important XXX
585  * \param context context to serach within
586  * \param exten extension to check
587  * \param priority priority of extension path
588  * \param callerid callerid of extension being searched for
589  *
590  * \note It is possible for autoservice to be started and stopped on c during this
591  * function call, it is important that c is not locked prior to calling this. Otherwise
592  * a deadlock may occur
593  *
594  * \return If "exten" *could match* a valid extension in this context with
595  * some more digits, return non-zero. Does NOT return non-zero if this is
596  * an exact-match only. Basically, when this returns 0, no matter
597  * what you add to exten, it's not going to be a valid extension anymore
598  */
599 int ast_matchmore_extension(struct ast_channel *c, const char *context,
600  const char *exten, int priority, const char *callerid);
601 
602 /*!
603  * \brief Determine if a given extension matches a given pattern (in NXX format)
604  *
605  * \param pattern pattern to match
606  * \param extension extension to check against the pattern.
607  *
608  * Checks whether or not the given extension matches the given pattern.
609  *
610  * \retval 1 on match
611  * \retval 0 on failure
612  */
613 int ast_extension_match(const char *pattern, const char *extension);
614 
615 int ast_extension_close(const char *pattern, const char *data, int needmore);
616 
617 /*!
618  * \brief Determine if one extension should match before another
619  *
620  * \param a extension to compare with b
621  * \param b extension to compare with a
622  *
623  * Checks whether or extension a should match before extension b
624  *
625  * \retval 0 if the two extensions have equal matching priority
626  * \retval 1 on a > b
627  * \retval -1 on a < b
628  */
629 int ast_extension_cmp(const char *a, const char *b);
630 
631 /*!
632  * \brief Launch a new extension (i.e. new stack)
633  *
634  * \param c not important
635  * \param context which context to generate the extension within
636  * \param exten new extension to add
637  * \param priority priority of new extension
638  * \param callerid callerid of extension
639  * \param found
640  * \param combined_find_spawn
641  *
642  * This adds a new extension to the asterisk extension list.
643  *
644  * \note It is possible for autoservice to be started and stopped on c during this
645  * function call, it is important that c is not locked prior to calling this. Otherwise
646  * a deadlock may occur
647  *
648  * \retval 0 on success
649  * \retval -1 on failure.
650  */
651 int ast_spawn_extension(struct ast_channel *c, const char *context,
652  const char *exten, int priority, const char *callerid, int *found, int combined_find_spawn);
653 
654 /*!
655  * \brief Add a context include
656  *
657  * \param context context to add include to
658  * \param include new include to add
659  * \param registrar who's registering it
660  *
661  * Adds an include taking a char * string as the context parameter
662  *
663  * \retval 0 on success
664  * \retval -1 on error
665 */
666 int ast_context_add_include(const char *context, const char *include,
667  const char *registrar);
668 
669 /*!
670  * \brief Add a context include
671  *
672  * \param con context to add the include to
673  * \param include include to add
674  * \param registrar who registered the context
675  *
676  * Adds an include taking a struct ast_context as the first parameter
677  *
678  * \retval 0 on success
679  * \retval -1 on failure
680  */
681 int ast_context_add_include2(struct ast_context *con, const char *include,
682  const char *registrar);
683 
684 /*!
685  * \brief Remove a context include
686  *
687  * \note See ast_context_add_include for information on arguments
688  *
689  * \retval 0 on success
690  * \retval -1 on failure
691  */
692 int ast_context_remove_include(const char *context, const char *include,
693  const char *registrar);
694 
695 /*!
696  * \brief Removes an include by an ast_context structure
697  *
698  * \note See ast_context_add_include2 for information on arguments
699  *
700  * \retval 0 on success
701  * \retval -1 on success
702  */
703 int ast_context_remove_include2(struct ast_context *con, const char *include,
704  const char *registrar);
705 
706 /*!
707  * \brief Verifies includes in an ast_contect structure
708  *
709  * \param con context in which to verify the includes
710  *
711  * \retval 0 if no problems found
712  * \retval -1 if there were any missing context
713  */
715 
716 /*!
717  * \brief Add a switch
718  *
719  * \param context context to which to add the switch
720  * \param sw switch to add
721  * \param data data to pass to switch
722  * \param eval whether to evaluate variables when running switch
723  * \param registrar whoever registered the switch
724  *
725  * This function registers a switch with the asterisk switch architecture
726  *
727  * \retval 0 on success
728  * \retval -1 on failure
729  */
730 int ast_context_add_switch(const char *context, const char *sw, const char *data,
731  int eval, const char *registrar);
732 
733 /*!
734  * \brief Adds a switch (first param is a ast_context)
735  *
736  * \note See ast_context_add_switch() for argument information, with the exception of
737  * the first argument. In this case, it's a pointer to an ast_context structure
738  * as opposed to the name.
739  */
740 int ast_context_add_switch2(struct ast_context *con, const char *sw, const char *data,
741  int eval, const char *registrar);
742 
743 /*!
744  * \brief Remove a switch
745  *
746  * Removes a switch with the given parameters
747  *
748  * \retval 0 on success
749  * \retval -1 on failure
750  */
751 int ast_context_remove_switch(const char *context, const char *sw,
752  const char *data, const char *registrar);
753 
754 int ast_context_remove_switch2(struct ast_context *con, const char *sw,
755  const char *data, const char *registrar);
756 
757 /*!
758  * \brief Simply remove extension from context
759  *
760  * \param context context to remove extension from
761  * \param extension which extension to remove
762  * \param priority priority of extension to remove (0 to remove all)
763  * \param registrar registrar of the extension
764  *
765  * This function removes an extension from a given context.
766  *
767  * \retval 0 on success
768  * \retval -1 on failure
769  *
770  * @{
771  */
772 int ast_context_remove_extension(const char *context, const char *extension, int priority,
773  const char *registrar);
774 
775 int ast_context_remove_extension2(struct ast_context *con, const char *extension,
776  int priority, const char *registrar, int already_locked);
777 
778 int ast_context_remove_extension_callerid(const char *context, const char *extension,
779  int priority, const char *callerid, int matchcid, const char *registrar);
780 
781 int ast_context_remove_extension_callerid2(struct ast_context *con, const char *extension,
782  int priority, const char *callerid, int matchcid, const char *registrar,
783  int already_locked);
784 /*! @} */
785 
786 /*!
787  * \brief Add an ignorepat
788  *
789  * \param context which context to add the ignorpattern to
790  * \param ignorepat ignorepattern to set up for the extension
791  * \param registrar registrar of the ignore pattern
792  *
793  * Adds an ignore pattern to a particular context.
794  *
795  * \retval 0 on success
796  * \retval -1 on failure
797  */
798 int ast_context_add_ignorepat(const char *context, const char *ignorepat, const char *registrar);
799 
800 int ast_context_add_ignorepat2(struct ast_context *con, const char *ignorepat, const char *registrar);
801 
802 /*
803  * \brief Remove an ignorepat
804  *
805  * \param context context from which to remove the pattern
806  * \param ignorepat the pattern to remove
807  * \param registrar the registrar of the ignore pattern
808  *
809  * This removes the given ignorepattern
810  *
811  * \retval 0 on success
812  * \retval -1 on failure
813  */
814 int ast_context_remove_ignorepat(const char *context, const char *ignorepat, const char *registrar);
815 
816 int ast_context_remove_ignorepat2(struct ast_context *con, const char *ignorepat, const char *registrar);
817 
818 /*!
819  * \brief Checks to see if a number should be ignored
820  *
821  * \param context context to search within
822  * \param pattern to check whether it should be ignored or not
823  *
824  * Check if a number should be ignored with respect to dialtone cancellation.
825  *
826  * \retval 0 if the pattern should not be ignored
827  * \retval non-zero if the pattern should be ignored
828  */
829 int ast_ignore_pattern(const char *context, const char *pattern);
830 
831 /* Locking functions for outer modules, especially for completion functions */
832 
833 /*!
834  * \brief Write locks the context list
835  *
836  * \retval 0 on success
837  * \retval -1 on error
838  */
839 int ast_wrlock_contexts(void);
840 
841 /*!
842  * \brief Read locks the context list
843  *
844  * \retval 0 on success
845  * \retval -1 on error
846  */
847 int ast_rdlock_contexts(void);
848 
849 /*!
850  * \brief Unlocks contexts
851  *
852  * \retval 0 on success
853  * \retval -1 on failure
854  */
855 int ast_unlock_contexts(void);
856 
857 /*!
858  * \brief Write locks a given context
859  *
860  * \param con context to lock
861  *
862  * \retval 0 on success
863  * \retval -1 on failure
864  */
865 int ast_wrlock_context(struct ast_context *con);
866 
867 /*!
868  * \brief Read locks a given context
869  *
870  * \param con context to lock
871  *
872  * \retval 0 on success
873  * \retval -1 on failure
874  */
875 int ast_rdlock_context(struct ast_context *con);
876 
877 /*!
878  * \retval Unlocks the given context
879  *
880  * \param con context to unlock
881  *
882  * \retval 0 on success
883  * \retval -1 on failure
884  */
885 int ast_unlock_context(struct ast_context *con);
886 
887 /*!
888  * \brief locks the macrolock in the given given context
889  *
890  * \param macrocontext name of the macro-context to lock
891  *
892  * Locks the given macro-context to ensure only one thread (call) can execute it at a time
893  *
894  * \retval 0 on success
895  * \retval -1 on failure
896  */
897 int ast_context_lockmacro(const char *macrocontext);
898 
899 /*!
900  * \brief Unlocks the macrolock in the given context
901  *
902  * \param macrocontext name of the macro-context to unlock
903  *
904  * Unlocks the given macro-context so that another thread (call) can execute it
905  *
906  * \retval 0 on success
907  * \retval -1 on failure
908  */
909 int ast_context_unlockmacro(const char *macrocontext);
910 
911 /*!
912  * \brief Set the channel to next execute the specified dialplan location.
913  * \see ast_async_parseable_goto, ast_async_goto_if_exists
914  *
915  * \note Do _NOT_ hold any channel locks when calling this function.
916  */
917 int ast_async_goto(struct ast_channel *chan, const char *context, const char *exten, int priority);
918 
919 /*!
920  * \brief Set the channel to next execute the specified dialplan location.
921  */
922 int ast_async_goto_by_name(const char *chan, const char *context, const char *exten, int priority);
923 
924 /*! Synchronously or asynchronously make an outbound call and send it to a
925  particular extension */
926 int ast_pbx_outgoing_exten(const char *type, format_t format, void *data, int timeout, const char *context, const char *exten, int priority, int *reason, int sync, const char *cid_num, const char *cid_name, struct ast_variable *vars, const char *account, struct ast_channel **locked_channel);
927 
928 /*! Synchronously or asynchronously make an outbound call and send it to a
929  particular application with given extension */
930 int ast_pbx_outgoing_app(const char *type, format_t format, void *data, int timeout, const char *app, const char *appdata, int *reason, int sync, const char *cid_num, const char *cid_name, struct ast_variable *vars, const char *account, struct ast_channel **locked_channel);
931 
932 /*!
933  * \brief Evaluate a condition
934  *
935  * \retval 0 if the condition is NULL or of zero length
936  * \retval int If the string is an integer, the integer representation of
937  * the integer is returned
938  * \retval 1 Any other non-empty string
939  */
940 int pbx_checkcondition(const char *condition);
941 
942 /*! @name
943  * Functions for returning values from structures */
944 /*! @{ */
945 const char *ast_get_context_name(struct ast_context *con);
946 const char *ast_get_extension_name(struct ast_exten *exten);
947 struct ast_context *ast_get_extension_context(struct ast_exten *exten);
948 const char *ast_get_include_name(struct ast_include *include);
949 const char *ast_get_ignorepat_name(struct ast_ignorepat *ip);
950 const char *ast_get_switch_name(struct ast_sw *sw);
951 const char *ast_get_switch_data(struct ast_sw *sw);
952 int ast_get_switch_eval(struct ast_sw *sw);
953 
954 /*! @} */
955 
956 /*! @name Other Extension stuff */
957 /*! @{ */
958 int ast_get_extension_priority(struct ast_exten *exten);
960 const char *ast_get_extension_cidmatch(struct ast_exten *e);
961 const char *ast_get_extension_app(struct ast_exten *e);
962 const char *ast_get_extension_label(struct ast_exten *e);
963 void *ast_get_extension_app_data(struct ast_exten *e);
964 /*! @} */
965 
966 /*! @name Registrar info functions ... */
967 /*! @{ */
968 const char *ast_get_context_registrar(struct ast_context *c);
969 const char *ast_get_extension_registrar(struct ast_exten *e);
970 const char *ast_get_include_registrar(struct ast_include *i);
971 const char *ast_get_ignorepat_registrar(struct ast_ignorepat *ip);
972 const char *ast_get_switch_registrar(struct ast_sw *sw);
973 /*! @} */
974 
975 /*! @name Walking functions ... */
976 /*! @{ */
977 struct ast_context *ast_walk_contexts(struct ast_context *con);
979  struct ast_exten *priority);
981  struct ast_exten *priority);
983  struct ast_include *inc);
985  struct ast_ignorepat *ip);
986 struct ast_sw *ast_walk_context_switches(struct ast_context *con, struct ast_sw *sw);
987 /*! @} */
988 
989 /*!
990  * \brief Create a human-readable string, specifying all variables and their corresponding values.
991  * \param chan Channel from which to read variables
992  * \param buf Dynamic string in which to place the result (should be allocated with ast_str_create).
993  * \see ast_str_create
994  * \note Will lock the channel.
995  */
996 int pbx_builtin_serialize_variables(struct ast_channel *chan, struct ast_str **buf);
997 
998 /*!
999  * \brief Return a pointer to the value of the corresponding channel variable.
1000  * \note Will lock the channel.
1001  *
1002  * \note This function will return a pointer to the buffer inside the channel
1003  * variable. This value should only be accessed with the channel locked. If
1004  * the value needs to be kept around, it should be done by using the following
1005  * thread-safe code:
1006  * \code
1007  * const char *var;
1008  *
1009  * ast_channel_lock(chan);
1010  * if ((var = pbx_builtin_getvar_helper(chan, "MYVAR"))) {
1011  * var = ast_strdupa(var);
1012  * }
1013  * ast_channel_unlock(chan);
1014  * \endcode
1015  */
1016 const char *pbx_builtin_getvar_helper(struct ast_channel *chan, const char *name);
1017 
1018 /*!
1019  * \brief Add a variable to the channel variable stack, without removing any previously set value.
1020  * \note Will lock the channel.
1021  */
1022 void pbx_builtin_pushvar_helper(struct ast_channel *chan, const char *name, const char *value);
1023 
1024 /*!
1025  * \brief Add a variable to the channel variable stack, removing the most recently set value for the same name.
1026  * \note Will lock the channel. May also be used to set a channel dialplan function to a particular value.
1027  * \see ast_func_write
1028  * \return -1 if the dialplan function fails to be set
1029  * \version 1.8 changed the function to return an error code
1030  */
1031 int pbx_builtin_setvar_helper(struct ast_channel *chan, const char *name, const char *value);
1032 
1033 /*!
1034  * \brief Retrieve the value of a builtin variable or variable from the channel variable stack.
1035  * \note Will lock the channel.
1036  */
1037 void pbx_retrieve_variable(struct ast_channel *c, const char *var, char **ret, char *workspace, int workspacelen, struct varshead *headp);
1038 void pbx_builtin_clear_globals(void);
1039 
1040 /*!
1041  * \brief Parse and set a single channel variable, where the name and value are separated with an '=' character.
1042  * \note Will lock the channel.
1043  */
1044 int pbx_builtin_setvar(struct ast_channel *chan, const char *data);
1045 
1046 /*!
1047  * \brief Parse and set multiple channel variables, where the pairs are separated by the ',' character, and name and value are separated with an '=' character.
1048  * \note Will lock the channel.
1049  */
1050 int pbx_builtin_setvar_multiple(struct ast_channel *chan, const char *data);
1051 
1052 int pbx_builtin_raise_exception(struct ast_channel *chan, const char *data);
1053 
1054 /*! @name Substitution routines, using static string buffers
1055  * @{ */
1056 void pbx_substitute_variables_helper(struct ast_channel *c, const char *cp1, char *cp2, int count);
1057 void pbx_substitute_variables_varshead(struct varshead *headp, const char *cp1, char *cp2, int count);
1058 void pbx_substitute_variables_helper_full(struct ast_channel *c, struct varshead *headp, const char *cp1, char *cp2, int cp2_size, size_t *used);
1059 /*! @} */
1060 /*! @} */
1061 
1062 /*! @name Substitution routines, using dynamic string buffers */
1063 
1064 /*!
1065  * \param buf Result will be placed in this buffer.
1066  * \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.
1067  * \param chan Channel variables from which to extract values, and channel to pass to any dialplan functions.
1068  * \param headp If no channel is specified, a channel list from which to extract variable values
1069  * \param var Variable name to retrieve.
1070  */
1071 const char *ast_str_retrieve_variable(struct ast_str **buf, ssize_t maxlen, struct ast_channel *chan, struct varshead *headp, const char *var);
1072 
1073 /*!
1074  * \param buf Result will be placed in this buffer.
1075  * \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.
1076  * \param chan Channel variables from which to extract values, and channel to pass to any dialplan functions.
1077  * \param templ Variable template to expand.
1078  */
1079 void ast_str_substitute_variables(struct ast_str **buf, ssize_t maxlen, struct ast_channel *chan, const char *templ);
1080 
1081 /*!
1082  * \param buf Result will be placed in this buffer.
1083  * \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.
1084  * \param headp If no channel is specified, a channel list from which to extract variable values
1085  * \param templ Variable template to expand.
1086  */
1087 void ast_str_substitute_variables_varshead(struct ast_str **buf, ssize_t maxlen, struct varshead *headp, const char *templ);
1088 
1089 /*!
1090  * \param buf Result will be placed in this buffer.
1091  * \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.
1092  * \param c Channel variables from which to extract values, and channel to pass to any dialplan functions.
1093  * \param headp If no channel is specified, a channel list from which to extract variable values
1094  * \param templ Variable template to expand.
1095  * \param used Number of bytes read from the template.
1096  */
1097 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);
1098 /*! @} */
1099 
1100 int ast_extension_patmatch(const char *pattern, const char *data);
1101 
1102 /*! Set "autofallthrough" flag, if newval is <0, does not actually set. If
1103  set to 1, sets to auto fall through. If newval set to 0, sets to no auto
1104  fall through (reads extension instead). Returns previous value. */
1105 int pbx_set_autofallthrough(int newval);
1106 
1107 /*! Set "extenpatternmatchnew" flag, if newval is <0, does not actually set. If
1108  set to 1, sets to use the new Trie-based pattern matcher. If newval set to 0, sets to use
1109  the old linear-search algorithm. Returns previous value. */
1110 int pbx_set_extenpatternmatchnew(int newval);
1111 
1112 /*! Set "overrideswitch" field. If set and of nonzero length, all contexts
1113  * will be tried directly through the named switch prior to any other
1114  * matching within that context.
1115  * \since 1.6.1
1116  */
1117 void pbx_set_overrideswitch(const char *newval);
1118 
1119 /*!
1120  * \note This function will handle locking the channel as needed.
1121  */
1122 int ast_goto_if_exists(struct ast_channel *chan, const char *context, const char *exten, int priority);
1123 
1124 /*!
1125  * \note This function will handle locking the channel as needed.
1126  */
1127 int ast_parseable_goto(struct ast_channel *chan, const char *goto_string);
1128 
1129 /*!
1130  * \note This function will handle locking the channel as needed.
1131  */
1132 int ast_async_parseable_goto(struct ast_channel *chan, const char *goto_string);
1133 
1134 /*!
1135  * \note This function will handle locking the channel as needed.
1136  */
1137 int ast_explicit_goto(struct ast_channel *chan, const char *context, const char *exten, int priority);
1138 
1139 /*!
1140  * \note This function will handle locking the channel as needed.
1141  */
1142 int ast_async_goto_if_exists(struct ast_channel *chan, const char *context, const char *exten, int priority);
1143 
1145 
1146 /*!
1147  * \brief Unregister a custom function
1148  */
1150 
1151 /*!
1152  * \brief Description of the ways in which a function may escalate privileges.
1153  */
1159 };
1160 
1161 /*!
1162  * \brief Register a custom function
1163  */
1164 #define ast_custom_function_register(acf) __ast_custom_function_register(acf, ast_module_info->self)
1165 
1166 /*!
1167  * \brief Register a custom function which requires escalated privileges.
1168  *
1169  * Examples would be SHELL() (for which a read needs permission to execute
1170  * arbitrary code) or FILE() (for which write needs permission to change files
1171  * on the filesystem).
1172  */
1173 #define ast_custom_function_register_escalating(acf, escalation) __ast_custom_function_register_escalating(acf, escalation, ast_module_info->self)
1174 
1175 /*!
1176  * \brief Register a custom function
1177  */
1179 
1180 /*!
1181  * \brief Register a custom function which requires escalated privileges.
1182  *
1183  * Examples would be SHELL() (for which a read needs permission to execute
1184  * arbitrary code) or FILE() (for which write needs permission to change files
1185  * on the filesystem).
1186  */
1188 
1189 /*!
1190  * \brief Retrieve the number of active calls
1191  */
1192 int ast_active_calls(void);
1193 
1194 /*!
1195  * \brief Retrieve the total number of calls processed through the PBX since last restart
1196  */
1197 int ast_processed_calls(void);
1198 
1199 /*!
1200  * \brief executes a read operation on a function
1201  *
1202  * \param chan Channel to execute on
1203  * \param function Data containing the function call string (will be modified)
1204  * \param workspace A pointer to safe memory to use for a return value
1205  * \param len the number of bytes in workspace
1206  *
1207  * This application executes a function in read mode on a given channel.
1208  *
1209  * \retval 0 success
1210  * \retval non-zero failure
1211  */
1212 int ast_func_read(struct ast_channel *chan, const char *function, char *workspace, size_t len);
1213 
1214 /*!
1215  * \brief executes a read operation on a function
1216  *
1217  * \param chan Channel to execute on
1218  * \param function Data containing the function call string (will be modified)
1219  * \param str A dynamic string buffer into which to place the result.
1220  * \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
1221  *
1222  * This application executes a function in read mode on a given channel.
1223  *
1224  * \retval 0 success
1225  * \retval non-zero failure
1226  */
1227 int ast_func_read2(struct ast_channel *chan, const char *function, struct ast_str **str, ssize_t maxlen);
1228 
1229 /*!
1230  * \brief executes a write operation on a function
1231  *
1232  * \param chan Channel to execute on
1233  * \param function Data containing the function call string (will be modified)
1234  * \param value A value parameter to pass for writing
1235  *
1236  * This application executes a function in write mode on a given channel.
1237  *
1238  * \retval 0 success
1239  * \retval non-zero failure
1240  */
1241 int ast_func_write(struct ast_channel *chan, const char *function, const char *value);
1242 
1243 /*!
1244  * \details
1245  * When looking up extensions, we can have different requests
1246  * identified by the 'action' argument, as follows.
1247  *
1248  * \note that the coding is such that the low 4 bits are the
1249  * third argument to extension_match_core.
1250  */
1252  E_MATCHMORE = 0x00, /* extension can match but only with more 'digits' */
1253  E_CANMATCH = 0x01, /* extension can match with or without more 'digits' */
1254  E_MATCH = 0x02, /* extension is an exact match */
1255  E_MATCH_MASK = 0x03, /* mask for the argument to extension_match_core() */
1256  E_SPAWN = 0x12, /* want to spawn an extension. Requires exact match */
1257  E_FINDLABEL = 0x22 /* returns the priority for a given label. Requires exact match */
1258 };
1259 
1260 #define STATUS_NO_CONTEXT 1
1261 #define STATUS_NO_EXTENSION 2
1262 #define STATUS_NO_PRIORITY 3
1263 #define STATUS_NO_LABEL 4
1264 #define STATUS_SUCCESS 5
1265 #define AST_PBX_MAX_STACK 128
1266 
1267 /* request and result for pbx_find_extension */
1268 struct pbx_find_info {
1269 #if 0
1270  const char *context;
1271  const char *exten;
1272  int priority;
1273 #endif
1274 
1275  char *incstack[AST_PBX_MAX_STACK]; /* filled during the search */
1276  int stacklen; /* modified during the search */
1277  int status; /* set on return */
1278  struct ast_switch *swo; /* set on return */
1279  const char *data; /* set on return */
1280  const char *foundcontext; /* set on return */
1281 };
1282 
1283 struct ast_exten *pbx_find_extension(struct ast_channel *chan,
1284  struct ast_context *bypass, struct pbx_find_info *q,
1285  const char *context, const char *exten, int priority,
1286  const char *label, const char *callerid, enum ext_match_t action);
1287 
1288 /*! \brief hashtable functions for contexts */
1289 /*! @{ */
1290 int ast_hashtab_compare_contexts(const void *ah_a, const void *ah_b);
1291 unsigned int ast_hashtab_hash_contexts(const void *obj);
1292 /*! @} */
1293 
1294 /*!
1295  * \brief Command completion for the list of installed applications.
1296  *
1297  * This can be called from a CLI command completion function that wants to
1298  * complete from the list of available applications.
1299  */
1300 char *ast_complete_applications(const char *line, const char *word, int state);
1301 
1302 /*!
1303  * \brief Enable/disable the execution of 'dangerous' functions from external
1304  * protocols (AMI, etc.).
1305  *
1306  * These dialplan functions (such as \c SHELL) provide an opportunity for
1307  * privilege escalation. They are okay to invoke from the dialplan, but external
1308  * protocols with permission controls should not normally invoke them.
1309  *
1310  * This function can globally enable/disable the execution of dangerous
1311  * functions from external protocols.
1312  *
1313  * \param new_live_dangerously If true, enable the execution of escalating
1314  * functions from external protocols.
1315  */
1316 void pbx_live_dangerously(int new_live_dangerously);
1317 
1318 /*!
1319  * \brief Inhibit (in the current thread) the execution of dialplan functions
1320  * which cause privilege escalations. If pbx_live_dangerously() has been
1321  * called, this function has no effect.
1322  *
1323  * \return 0 if successfuly marked current thread.
1324  * \return Non-zero if marking current thread failed.
1325  */
1327 
1328 #if defined(__cplusplus) || defined(c_plusplus)
1329 }
1330 #endif
1331 
1332 #endif /* _ASTERISK_PBX_H */
struct ast_include * ast_walk_context_includes(struct ast_context *con, struct ast_include *inc)
Definition: pbx.c:11203
ast_include: include= support in extensions.conf
Definition: pbx.c:904
void pbx_substitute_variables_helper(struct ast_channel *c, const char *cp1, char *cp2, int count)
Definition: pbx.c:4676
int ast_hashtab_compare_contexts(const void *ah_a, const void *ah_b)
hashtable functions for contexts
Definition: pbx.c:1136
int hastime
Definition: pbx.h:140
int ast_unlock_context(struct ast_context *con)
Definition: pbx.c:11065
enum sip_cc_notify_state state
Definition: chan_sip.c:842
Options for ast_pbx_run()
Definition: pbx.h:336
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:124
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:5362
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:5420
int ast_func_read(struct ast_channel *chan, const char *function, char *workspace, size_t len)
executes a read operation on a function
Definition: pbx.c:4177
static char exten[AST_MAX_EXTENSION]
Definition: chan_alsa.c:109
Main Channel structure associated with a channel.
Definition: channel.h:742
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.c:8362
int ast_context_add_include2(struct ast_context *con, const char *include, const char *registrar)
Add a context include.
Definition: pbx.c:8411
ast_device_state
Device States.
Definition: devicestate.h:51
unsigned int daymask
Definition: pbx.h:142
int ast_get_extension_priority(struct ast_exten *exten)
Definition: pbx.c:11103
ast_extension_states
Extension states.
Definition: pbx.h:60
ast_exten: An extension The dialplan is saved as a linked list with each context having it&#39;s own link...
Definition: pbx.c:884
int ast_context_remove_include(const char *context, const char *include, const char *registrar)
Remove a context include.
Definition: pbx.c:6007
int ast_context_remove_ignorepat(const char *context, const char *ignorepat, const char *registrar)
Definition: pbx.c:8554
int ast_active_calls(void)
Retrieve the number of active calls.
Definition: pbx.c:5931
void pbx_builtin_clear_globals(void)
Definition: pbx.c:10709
const char * ast_get_extension_registrar(struct ast_exten *e)
Definition: pbx.c:11116
struct ast_app * pbx_findapp(const char *app)
Look up an application.
Definition: pbx.c:1537
int pbx_exec(struct ast_channel *c, struct ast_app *app, const char *data)
Execute an application.
Definition: pbx.c:1497
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.
Definition: pbx.c:3994
static int exists(struct ast_channel *chan, const char *cmd, char *data, char *buf, size_t len)
Definition: func_logic.c:126
Device state management.
int ast_context_lockmacro(const char *macrocontext)
locks the macrolock in the given given context
Definition: pbx.c:6306
int ast_extension_state_del(int id, ast_state_cb_type change_cb)
Deletes a registered state change callback by ID.
Definition: pbx.c:5157
const ast_string_field syntax
Definition: pbx.h:103
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
Definition: pbx.c:4216
Channel Variables.
int(* ast_state_cb_type)(char *context, char *id, enum ast_extension_states state, void *data)
Typedef for devicestate and hint callbacks.
Definition: pbx.h:89
enum ast_pbx_result ast_pbx_start(struct ast_channel *c)
Create a new thread and start the PBX.
Definition: pbx.c:5879
int ast_extension_cmp(const char *a, const char *b)
Determine if one extension should match before another.
Definition: pbx.c:2713
const char * ast_get_extension_app(struct ast_exten *e)
Definition: pbx.c:11141
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)
Add an extension to an extension context, this time with an ast_context *.
Definition: pbx.c:9052
uint64_t __padding
Definition: pbx.h:340
ast_custom_function_escalation
Description of the ways in which a function may escalate privileges.
Definition: pbx.h:1154
char * ast_complete_applications(const char *line, const char *word, int state)
Command completion for the list of installed applications.
Definition: pbx.c:11336
Generic (perhaps overly so) hashtable implementation Hash Table support in Asterisk.
Structure for variables, used for configurations and for channel variables.
Definition: config.h:75
#define var
Definition: ast_expr2f.c:606
int pbx_checkcondition(const char *condition)
Evaluate a condition.
Definition: pbx.c:10719
void ast_str_substitute_variables(struct ast_str **buf, ssize_t maxlen, struct ast_channel *chan, const char *templ)
Definition: pbx.c:4468
const ast_string_field desc
Definition: pbx.h:103
enum ast_doc_src docsrc
Definition: pbx.h:104
int ast_ignore_pattern(const char *context, const char *pattern)
Checks to see if a number should be ignored.
Definition: pbx.c:8650
void ast_unregister_switch(struct ast_switch *sw)
Unregister an alternative switch.
Definition: pbx.c:6457
const ast_string_field arguments
Definition: pbx.h:103
void * ast_get_extension_app_data(struct ast_exten *e)
Definition: pbx.c:11146
int ast_rdlock_contexts(void)
Read locks the context list.
Definition: pbx.c:11042
static int matchmore(struct ast_channel *chan, const char *context, const char *exten, int priority, const char *callerid, const char *data)
Definition: pbx_lua.c:1258
const char * ast_get_extension_label(struct ast_exten *e)
Definition: pbx.c:11088
#define AST_DECLARE_STRING_FIELDS(field_list)
Declare the fields needed in a structure.
Definition: stringfields.h:235
int ast_explicit_goto(struct ast_channel *chan, const char *context, const char *exten, int priority)
Definition: pbx.c:8708
struct ast_module * mod
Definition: pbx.h:119
int ast_wrlock_contexts(void)
Write locks the context list.
Definition: pbx.c:11037
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:6149
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:6030
const char * str
Definition: app_jack.c:144
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...
Definition: pbx.c:10513
const char * ast_get_context_registrar(struct ast_context *c)
Definition: pbx.c:11111
int value
Definition: syslog.c:39
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:5380
int(* ast_acf_read2_fn_t)(struct ast_channel *, const char *, char *, struct ast_str **, ssize_t)
Typedef for a custom read2 function.
Definition: channel.h:476
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: pbx.c:8494
AST_LIST_ENTRY(ast_custom_function) acflist
static char cid_num[AST_MAX_EXTENSION]
Definition: chan_mgcp.c:157
ast_doc_src
From where the documentation come from, this structure is useful for use it inside application/functi...
Definition: xmldoc.h:28
Definition: ael.tab.c:203
int ast_context_add_include(const char *context, const char *include, const char *registrar)
Add a context include.
Definition: pbx.c:8142
int ast_custom_function_unregister(struct ast_custom_function *acf)
Unregister a custom function.
Definition: pbx.c:3814
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:5415
const char * pbx_builtin_getvar_helper(struct ast_channel *chan, const char *name)
Return a pointer to the value of the corresponding channel variable.
Definition: pbx.c:10475
int ast_context_remove_extension(const char *context, const char *extension, int priority, const char *registrar)
Simply remove extension from context.
Definition: pbx.c:6114
String fields in structures.
unsigned int monthmask
Definition: pbx.h:141
int ast_context_remove_switch(const char *context, const char *sw, const char *data, const char *registrar)
Remove a switch.
Definition: pbx.c:6065
const char * ast_get_switch_name(struct ast_sw *sw)
Definition: pbx.c:11151
const char * ast_get_include_name(struct ast_include *include)
Definition: pbx.c:11093
char * timezone
Definition: pbx.h:145
const char * ast_get_include_registrar(struct ast_include *i)
Definition: pbx.c:11121
Definition: pbx.h:179
ast_sw: Switch statement in extensions.conf
Definition: pbx.c:915
static const char app[]
Definition: app_adsiprog.c:49
General Asterisk PBX channel definitions.
struct ast_exten * ast_walk_context_extensions(struct ast_context *con, struct ast_exten *priority)
Definition: pbx.c:11179
int pbx_builtin_raise_exception(struct ast_channel *chan, const char *data)
Definition: pbx.c:3620
int ast_context_add_ignorepat(const char *context, const char *ignorepat, const char *registrar)
Add an ignorepat.
Definition: pbx.c:8598
Data structure associated with a custom dialplan function.
Definition: pbx.h:95
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:5906
int ast_parseable_goto(struct ast_channel *chan, const char *goto_string)
Definition: pbx.c:11326
int pbx_set_extenpatternmatchnew(int newval)
Definition: pbx.c:5948
Scheduler Routines (derived from cheops)
const char * ast_get_ignorepat_registrar(struct ast_ignorepat *ip)
Definition: pbx.c:11126
#define AST_STRING_FIELD(name)
Declare a string field.
Definition: stringfields.h:220
ast_ext_matchcid_types
extension matchcid types
Definition: pbx.h:76
const char * ast_extension_state2str(int extension_state)
Return string representation of the state of an extension.
Definition: pbx.c:4902
size_t read_max
Definition: pbx.h:116
const char * ast_get_switch_data(struct ast_sw *sw)
Definition: pbx.c:11156
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)
Registers a state change callback with destructor.
Definition: pbx.c:5048
ast_acf_write_fn_t write
Definition: pbx.h:118
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)
Definition: pbx.c:4289
int(* ast_acf_read_fn_t)(struct ast_channel *, const char *, char *, char *, size_t)
Typedef for a custom read function.
Definition: channel.h:473
struct ast_ignorepat * ast_walk_context_ignorepats(struct ast_context *con, struct ast_ignorepat *ip)
Definition: pbx.c:11212
int pbx_set_autofallthrough(int newval)
Definition: pbx.c:5941
const char * ast_get_extension_cidmatch(struct ast_exten *e)
Definition: pbx.c:11136
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:5400
int ast_context_add_ignorepat2(struct ast_context *con, const char *ignorepat, const char *registrar)
Definition: pbx.c:8611
struct ast_context * ast_walk_contexts(struct ast_context *con)
Definition: pbx.c:11174
const char * ast_get_context_name(struct ast_context *con)
Definition: pbx.c:11073
ast_pbx_result
The result codes when starting the PBX on a channel with ast_pbx_start.
Definition: pbx.h:299
#define AST_PBX_MAX_STACK
Definition: pbx.h:1265
struct ast_custom_function * ast_custom_function_find(const char *name)
Definition: pbx.c:3800
int ast_get_switch_eval(struct ast_sw *sw)
Definition: pbx.c:11161
int ast_processed_calls(void)
Retrieve the total number of calls processed through the PBX since last restart.
Definition: pbx.c:5936
unsigned int dowmask
Definition: pbx.h:143
int ast_pbx_outgoing_exten(const char *type, format_t format, void *data, int timeout, const char *context, const char *exten, int priority, int *reason, int sync, const char *cid_num, const char *cid_name, struct ast_variable *vars, const char *account, struct ast_channel **locked_channel)
Definition: pbx.c:9375
static int canmatch(struct ast_channel *chan, const char *context, const char *exten, int priority, const char *callerid, const char *data)
Definition: pbx_lua.c:1235
ast_acf_read2_fn_t read2
Definition: pbx.h:114
The descriptor of a dynamic string XXX storage will be optimized later if needed We use the ts field ...
Definition: strings.h:364
void ast_str_substitute_variables_varshead(struct ast_str **buf, ssize_t maxlen, struct varshead *headp, const char *templ)
Definition: pbx.c:4474
int64_t format_t
Definition: frame_defs.h:32
static struct @350 args
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.
Definition: pbx.c:3434
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: pbx.c:7937
const char * ast_get_switch_registrar(struct ast_sw *sw)
Definition: pbx.c:11166
char * data
Definition: pbx.c:918
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: pbx.c:8357
void(* ast_state_cb_destroy_type)(int id, void *data)
Typedef for devicestate and hint callback removal indication callback.
Definition: pbx.h:92
struct ast_exten * ast_walk_extension_priorities(struct ast_exten *exten, struct ast_exten *priority)
Definition: pbx.c:11197
ast_ignorepat: Ignore patterns in dial plan
Definition: pbx.c:925
int ast_unlock_contexts(void)
Unlocks contexts.
Definition: pbx.c:11047
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:5405
static int len(struct ast_channel *chan, const char *cmd, char *data, char *buf, size_t buflen)
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...
Definition: pbx.c:10633
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:6119
const char * ast_get_extension_name(struct ast_exten *exten)
Definition: pbx.c:11083
int ast_wrlock_context(struct ast_context *con)
Write locks a given context.
Definition: pbx.c:11055
int ast_goto_if_exists(struct ast_channel *chan, const char *context, const char *exten, int priority)
Definition: pbx.c:11261
enum ast_extension_states ast_devstate_to_extenstate(enum ast_device_state devstate)
Map devstate to an extension state.
Definition: pbx.c:4844
int ast_destroy_timing(struct ast_timing *i)
Deallocates memory structures associated with a timing bitmap.
Definition: pbx.c:8396
static int matchcid(const char *cidpattern, const char *callerid)
Definition: pbx.c:3001
const char * ast_get_ignorepat_name(struct ast_ignorepat *ip)
Definition: pbx.c:11098
unsigned int ast_hashtab_hash_contexts(const void *obj)
Definition: pbx.c:1188
void pbx_live_dangerously(int new_live_dangerously)
Enable/disable the execution of &#39;dangerous&#39; functions from external protocols (AMI, etc.).
Definition: pbx.c:4059
int ast_register_switch(struct ast_switch *sw)
Register an alternative dialplan switch.
Definition: pbx.c:6439
int ast_extension_close(const char *pattern, const char *data, int needmore)
Definition: pbx.c:2948
Asterisk XML Documentation API.
int ast_extension_match(const char *pattern, const char *extension)
Determine if a given extension matches a given pattern (in NXX format)
Definition: pbx.c:2943
static char * registrar
Definition: features.c:623
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...
Definition: pbx.c:10603
int ast_async_goto_if_exists(struct ast_channel *chan, const char *context, const char *exten, int priority)
Definition: pbx.c:11266
static const char type[]
Definition: chan_nbs.c:57
const ast_string_field synopsis
Definition: pbx.h:103
int ast_build_timing(struct ast_timing *i, const char *info)
Construct a timing bitmap, for use in time-based conditionals.
Definition: pbx.c:8314
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:5425
static char cid_name[AST_MAX_EXTENSION]
Definition: chan_mgcp.c:158
#define AST_RWLIST_ENTRY
Definition: linkedlists.h:414
static int replace(struct ast_channel *chan, const char *cmd, char *data, struct ast_str **buf, ssize_t len)
Definition: func_strings.c:775
int ast_async_parseable_goto(struct ast_channel *chan, const char *goto_string)
Definition: pbx.c:11331
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...
Definition: pbx.c:10546
struct ast_sw * ast_walk_context_switches(struct ast_context *con, struct ast_sw *sw)
Definition: pbx.c:11188
static int exec(struct ast_channel *chan, const char *context, const char *exten, int priority, const char *callerid, const char *data)
Definition: pbx_lua.c:1282
const char * ast_str_retrieve_variable(struct ast_str **buf, ssize_t maxlen, struct ast_channel *chan, struct varshead *headp, const char *var)
Definition: pbx.c:3445
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:8691
int dtimeoutms
Definition: pbx.h:180
ast_acf_read_fn_t read
Definition: pbx.h:106
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:4914
ast_app: A registered application
Definition: pbx.c:971
ext_match_t
Definition: extconf.h:215
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:8731
void pbx_set_overrideswitch(const char *newval)
Definition: pbx.c:5955
int ast_thread_inhibit_escalations(void)
Inhibit (in the current thread) the execution of dialplan functions which cause privilege escalations...
Definition: pbx.c:4072
enum ast_pbx_result ast_pbx_run(struct ast_channel *c)
Execute the PBX in the current thread.
Definition: pbx.c:5926
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:6144
int __ast_custom_function_register(struct ast_custom_function *acf, struct ast_module *mod)
Register a custom function.
Definition: pbx.c:3946
void ast_context_destroy(struct ast_context *con, const char *registrar)
Destroy a context (matches the specified context (or ANY context if NULL)
Definition: pbx.c:9875
const char * name
Definition: pbx.h:96
struct timeval tv
void pbx_substitute_variables_helper_full(struct ast_channel *c, struct varshead *headp, const char *cp1, char *cp2, int cp2_size, size_t *used)
Definition: pbx.c:4480
enum queue_result id
Definition: app_queue.c:1090
int ast_context_verify_includes(struct ast_context *con)
Verifies includes in an ast_contect structure.
Definition: pbx.c:11221
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: pbx.c:3013
static char context[AST_MAX_CONTEXT]
Definition: chan_alsa.c:107
int ast_pbx_outgoing_app(const char *type, format_t format, void *data, int timeout, const char *app, const char *appdata, int *reason, int sync, const char *cid_num, const char *cid_name, struct ast_variable *vars, const char *account, struct ast_channel **locked_channel)
Definition: pbx.c:9544
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:7726
int ast_extension_state_add(const char *context, const char *exten, ast_state_cb_type change_cb, void *data)
Registers a state change callback.
Definition: pbx.c:5135
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:8474
const ast_string_field seealso
Definition: pbx.h:103
int ast_get_extension_matchcid(struct ast_exten *e)
Definition: pbx.c:11131
int(* ast_acf_write_fn_t)(struct ast_channel *, const char *, char *, const char *)
Typedef for a custom write function.
Definition: channel.h:479
struct ast_module_info * info
Definition: loader.c:90
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: pbx.c:5410
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:6087
static snd_pcm_format_t format
Definition: chan_alsa.c:93
Asterisk internal frame definitions.
int ast_func_write(struct ast_channel *chan, const char *function, const char *value)
executes a write operation on a function
Definition: pbx.c:4263
ast_context: An extension context
Definition: pbx.c:955
int ast_context_remove_ignorepat2(struct ast_context *con, const char *ignorepat, const char *registrar)
Definition: pbx.c:8567
int ast_context_unlockmacro(const char *macrocontext)
Unlocks the macrolock in the given context.
Definition: pbx.c:6327
struct ast_context * ast_context_find(const char *name)
Find a context.
Definition: pbx.c:2971
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:8813
void pbx_substitute_variables_varshead(struct varshead *headp, const char *cp1, char *cp2, int count)
Definition: pbx.c:4682
jack_status_t status
Definition: app_jack.c:143
struct ast_context * ast_get_extension_context(struct ast_exten *exten)
Definition: pbx.c:11078
int ast_rdlock_context(struct ast_context *con)
Read locks a given context.
Definition: pbx.c:11060
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.
Definition: pbx.c:10444
int rtimeoutms
Definition: pbx.h:181