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