Wed Jan 8 2020 09:49:39

Asterisk developer's documentation


app.h
Go to the documentation of this file.
1 /*
2  * Asterisk -- An open source telephony toolkit.
3  *
4  * Copyright (C) 1999 - 2005, Digium, Inc.
5  *
6  * Mark Spencer <markster@digium.com>
7  * See http://www.asterisk.org for more information about
8  * the Asterisk project. Please do not directly contact
9  * any of the maintainers of this project for assistance;
10  * the project provides a web site, mailing lists and IRC
11  * channels for your use.
12  *
13  * This program is free software, distributed under the terms of
14  * the GNU General Public License Version 2. See the LICENSE file
15  * at the top of the source tree.
16  */
17 
18 /*! \file
19  * \brief Application convenience functions, designed to give consistent
20  * look and feel to Asterisk apps.
21  */
22 
23 #ifndef _ASTERISK_APP_H
24 #define _ASTERISK_APP_H
25 
26 #include "asterisk/strings.h"
27 #include "asterisk/threadstorage.h"
28 
29 struct ast_flags64;
30 
31 #if defined(__cplusplus) || defined(c_plusplus)
32 extern "C" {
33 #endif
34 
35 AST_THREADSTORAGE_EXTERNAL(ast_str_thread_global_buf);
36 
37 /* IVR stuff */
38 
39 /*! \brief Callback function for IVR
40  \return returns 0 on completion, -1 on hangup or digit if interrupted
41  */
42 typedef int (*ast_ivr_callback)(struct ast_channel *chan, char *option, void *cbdata);
43 
44 typedef enum {
45  AST_ACTION_UPONE, /*!< adata is unused */
46  AST_ACTION_EXIT, /*!< adata is the return value for ast_ivr_menu_run if channel was not hungup */
47  AST_ACTION_CALLBACK, /*!< adata is an ast_ivr_callback */
48  AST_ACTION_PLAYBACK, /*!< adata is file to play */
49  AST_ACTION_BACKGROUND, /*!< adata is file to play */
50  AST_ACTION_PLAYLIST, /*!< adata is list of files, separated by ; to play */
51  AST_ACTION_MENU, /*!< adata is a pointer to an ast_ivr_menu */
52  AST_ACTION_REPEAT, /*!< adata is max # of repeats, cast to a pointer */
53  AST_ACTION_RESTART, /*!< adata is like repeat, but resets repeats to 0 */
54  AST_ACTION_TRANSFER, /*!< adata is a string with exten\verbatim[@context]\endverbatim */
55  AST_ACTION_WAITOPTION, /*!< adata is a timeout, or 0 for defaults */
56  AST_ACTION_NOOP, /*!< adata is unused */
57  AST_ACTION_BACKLIST, /*!< adata is list of files separated by ; allows interruption */
59 
60 /*!
61  Special "options" are:
62  \arg "s" - "start here (one time greeting)"
63  \arg "g" - "greeting/instructions"
64  \arg "t" - "timeout"
65  \arg "h" - "hangup"
66  \arg "i" - "invalid selection"
67 
68 */
70  char *option;
72  void *adata;
73 };
74 
75 struct ast_ivr_menu {
76  char *title; /*!< Title of menu */
77  unsigned int flags; /*!< Flags */
78  struct ast_ivr_option *options; /*!< All options */
79 };
80 
81 #define AST_IVR_FLAG_AUTORESTART (1 << 0)
82 
83 #define AST_IVR_DECLARE_MENU(holder, title, flags, foo...) \
84  static struct ast_ivr_option __options_##holder[] = foo;\
85  static struct ast_ivr_menu holder = { title, flags, __options_##holder }
86 
92 };
93 
94 /*! \brief Runs an IVR menu
95  \return returns 0 on successful completion, -1 on hangup, or -2 on user error in menu */
96 int ast_ivr_menu_run(struct ast_channel *c, struct ast_ivr_menu *menu, void *cbdata);
97 
98 /*! \brief Plays a stream and gets DTMF data from a channel
99  * \param c Which channel one is interacting with
100  * \param prompt File to pass to ast_streamfile (the one that you wish to play).
101  * It is also valid for this to be multiple files concatenated by "&".
102  * For example, "file1&file2&file3".
103  * \param s The location where the DTMF data will be stored
104  * \param maxlen Max Length of the data
105  * \param timeout Timeout length waiting for data(in milliseconds). Set to 0 for standard timeout(six seconds), or -1 for no time out.
106  *
107  * This function was designed for application programmers for situations where they need
108  * to play a message and then get some DTMF data in response to the message. If a digit
109  * is pressed during playback, it will immediately break out of the message and continue
110  * execution of your code.
111  */
112 int ast_app_getdata(struct ast_channel *c, const char *prompt, char *s, int maxlen, int timeout);
113 
114 /*! \brief Full version with audiofd and controlfd. NOTE: returns '2' on ctrlfd available, not '1' like other full functions */
115 int ast_app_getdata_full(struct ast_channel *c, const char *prompt, char *s, int maxlen, int timeout, int audiofd, int ctrlfd);
116 
117 /*!
118  * \brief Run a macro on a channel, placing an optional second channel into autoservice.
119  * \since 1.8.30.0
120  * \since 11.0
121  *
122  * \details
123  * This is a shorthand method that makes it very easy to run a
124  * macro on any given channel. It is perfectly reasonable to
125  * supply a NULL autoservice_chan here in case there is no
126  * channel to place into autoservice.
127  *
128  * \note Absolutely _NO_ channel locks should be held before calling this function.
129  *
130  * \param autoservice_chan A channel to place into autoservice while the macro is run
131  * \param macro_chan Channel to execute macro on.
132  * \param macro_args Macro application argument string.
133  *
134  * \retval 0 success
135  * \retval -1 on error
136  */
137 int ast_app_exec_macro(struct ast_channel *autoservice_chan, struct ast_channel *macro_chan, const char *macro_args);
138 
139 /*!
140  * \since 1.8
141  * \brief Run a macro on a channel, placing an optional second channel into autoservice.
142  *
143  * \details
144  * This is a shorthand method that makes it very easy to run a
145  * macro on any given channel. It is perfectly reasonable to
146  * supply a NULL autoservice_chan here in case there is no
147  * channel to place into autoservice.
148  *
149  * \note Absolutely _NO_ channel locks should be held before calling this function.
150  *
151  * \param autoservice_chan A channel to place into autoservice while the macro is run
152  * \param macro_chan Channel to execute macro on.
153  * \param macro_name The name of the macro to run.
154  * \param macro_args The arguments to pass to the macro.
155  *
156  * \retval 0 success
157  * \retval -1 on error
158  */
159 int ast_app_run_macro(struct ast_channel *autoservice_chan,
160  struct ast_channel *macro_chan, const char *macro_name, const char *macro_args);
161 
162 /*!
163  * \brief Stack applications callback functions.
164  */
166  /*!
167  * Module reference pointer so the module will stick around
168  * while a callback is active.
169  */
170  void *module;
171 
172  /*!
173  * \brief Callback for the routine to run a subroutine on a channel.
174  *
175  * \note Absolutely _NO_ channel locks should be held before calling this function.
176  *
177  * \param chan Channel to execute subroutine on.
178  * \param args Gosub application argument string.
179  * \param ignore_hangup TRUE if a hangup does not stop execution of the routine.
180  *
181  * \retval 0 success
182  * \retval -1 on error
183  */
184  int (*run_sub)(struct ast_channel *chan, const char *args, int ignore_hangup);
185 
186  /*!
187  * \brief Add missing context/exten to Gosub application argument string.
188  *
189  * \param chan Channel to obtain context/exten.
190  * \param args Gosub application argument string.
191  *
192  * \details
193  * Fills in the optional context and exten from the given channel.
194  *
195  * \retval New-args Gosub argument string on success. Must be freed.
196  * \retval NULL on error.
197  */
198  const char *(*expand_sub_args)(struct ast_channel *chan, const char *args);
199 
200  /* Add new API calls to the end here. */
201 };
202 
203 /*!
204  * \since 1.8.30.0
205  * \since 11
206  * \brief Set stack application function callbacks
207  * \param funcs Stack applications callback functions.
208  */
209 void ast_install_stack_functions(const struct ast_app_stack_funcs *funcs);
210 
211 /*!
212  * \brief Add missing context/exten to subroutine argument string.
213  * \since 1.8.30.0
214  *
215  * \param chan Channel to obtain context/exten.
216  * \param args Gosub application argument string.
217  *
218  * \details
219  * Fills in the optional context and exten from the given channel.
220  *
221  * \retval New-args Gosub argument string on success. Must be freed.
222  * \retval NULL on error.
223  */
224 const char *ast_app_expand_sub_args(struct ast_channel *chan, const char *args);
225 
226 /*!
227  * \since 1.8.30.0
228  * \since 11
229  * \brief Run a subroutine on a channel, placing an optional second channel into autoservice.
230  *
231  * \details
232  * This is a shorthand method that makes it very easy to run a
233  * subroutine on any given channel. It is perfectly reasonable
234  * to supply a NULL autoservice_chan here in case there is no
235  * channel to place into autoservice.
236  *
237  * \note Absolutely _NO_ channel locks should be held before calling this function.
238  *
239  * \param autoservice_chan A channel to place into autoservice while the subroutine is run
240  * \param sub_chan Channel to execute subroutine on.
241  * \param sub_args Gosub application argument string.
242  * \param ignore_hangup TRUE if a hangup does not stop execution of the routine.
243  *
244  * \retval 0 success
245  * \retval -1 on error
246  */
247 int ast_app_exec_sub(struct ast_channel *autoservice_chan, struct ast_channel *sub_chan, const char *sub_args, int ignore_hangup);
248 
249 /*!
250  * \since 1.8.30.0
251  * \since 11
252  * \brief Run a subroutine on a channel, placing an optional second channel into autoservice.
253  *
254  * \details
255  * This is a shorthand method that makes it very easy to run a
256  * subroutine on any given channel. It is perfectly reasonable
257  * to supply a NULL autoservice_chan here in case there is no
258  * channel to place into autoservice.
259  *
260  * \note Absolutely _NO_ channel locks should be held before calling this function.
261  *
262  * \param autoservice_chan A channel to place into autoservice while the subroutine is run
263  * \param sub_chan Channel to execute subroutine on.
264  * \param sub_location The location of the subroutine to run.
265  * \param sub_args The arguments to pass to the subroutine.
266  * \param ignore_hangup TRUE if a hangup does not stop execution of the routine.
267  *
268  * \retval 0 success
269  * \retval -1 on error
270  */
271 int ast_app_run_sub(struct ast_channel *autoservice_chan,
272  struct ast_channel *sub_chan, const char *sub_location, const char *sub_args, int ignore_hangup);
273 
274 /*!
275  * \brief Set voicemail function callbacks
276  * \param[in] has_voicemail_func set function pointer
277  * \param[in] inboxcount2_func set function pointer
278  * \param[in] sayname_func set function pointer
279  * \param[in] inboxcount_func set function pointer
280  * \param[in] messagecount_func set function pointer
281  * \version 1.6.1 Added inboxcount2_func, sayname_func
282  */
283 void ast_install_vm_functions(int (*has_voicemail_func)(const char *mailbox, const char *folder),
284  int (*inboxcount_func)(const char *mailbox, int *newmsgs, int *oldmsgs),
285  int (*inboxcount2_func)(const char *mailbox, int *urgentmsgs, int *newmsgs, int *oldmsgs),
286  int (*messagecount_func)(const char *context, const char *mailbox, const char *folder),
287  int (*sayname_func)(struct ast_channel *chan, const char *mailbox, const char *context));
288 
289 void ast_uninstall_vm_functions(void);
290 
291 /*!
292  * \brief Determine if a given mailbox has any voicemail
293  * If folder is NULL, defaults to "INBOX". If folder is "INBOX", includes the
294  * number of messages in the "Urgent" folder.
295  * \retval 1 Mailbox has voicemail
296  * \retval 0 No new voicemail in specified mailbox
297  * \retval -1 Failure
298  * \since 1.0
299  */
300 int ast_app_has_voicemail(const char *mailbox, const char *folder);
301 
302 /*!
303  * \brief Determine number of new/old messages in a mailbox
304  * \since 1.0
305  * \param[in] mailbox Mailbox specification in the format mbox[@context][&mbox2[@context2]][...]
306  * \param[out] newmsgs Number of messages in the "INBOX" folder. Includes number of messages in the "Urgent" folder, if any.
307  * \param[out] oldmsgs Number of messages in the "Old" folder.
308  * \retval 0 Success
309  * \retval -1 Failure
310  */
311 int ast_app_inboxcount(const char *mailbox, int *newmsgs, int *oldmsgs);
312 
313 /*!
314  * \brief Determine number of urgent/new/old messages in a mailbox
315  * \param[in] mailbox the mailbox context to use
316  * \param[out] urgentmsgs the urgent message count
317  * \param[out] newmsgs the new message count
318  * \param[out] oldmsgs the old message count
319  * \return Returns 0 for success, negative upon error
320  * \since 1.6.1
321  */
322 int ast_app_inboxcount2(const char *mailbox, int *urgentmsgs, int *newmsgs, int *oldmsgs);
323 
324 /*!
325  * \brief Given a mailbox and context, play that mailbox owner's name to the channel specified
326  * \param[in] chan Channel on which to play the name
327  * \param[in] mailbox Mailbox number from which to retrieve the recording
328  * \param[in] context Mailbox context from which to locate the mailbox number
329  * \retval 0 Name played without interruption
330  * \retval dtmf ASCII value of the DTMF which interrupted playback.
331  * \retval -1 Unable to locate mailbox or hangup occurred.
332  * \since 1.6.1
333  */
334 int ast_app_sayname(struct ast_channel *chan, const char *mailbox, const char *context);
335 
336 /*!
337  * \brief Check number of messages in a given context, mailbox, and folder
338  * \since 1.4
339  * \param[in] context Mailbox context
340  * \param[in] mailbox Mailbox number
341  * \param[in] folder Mailbox folder
342  * \return Number of messages in the given context, mailbox, and folder. If folder is NULL, folder "INBOX" is assumed. If folder is "INBOX", includes number of messages in the "Urgent" folder.
343  */
344 int ast_app_messagecount(const char *context, const char *mailbox, const char *folder);
345 
346 /*! \brief Safely spawn an external program while closing file descriptors
347  \note This replaces the \b system call in all Asterisk modules
348 */
349 int ast_safe_system(const char *s);
350 
351 /*!
352  * \brief Replace the SIGCHLD handler
353  *
354  * Normally, Asterisk has a SIGCHLD handler that is cleaning up all zombie
355  * processes from forking elsewhere in Asterisk. However, if you want to
356  * wait*() on the process to retrieve information about it's exit status,
357  * then this signal handler needs to be temporarily replaced.
358  *
359  * Code that executes this function *must* call ast_unreplace_sigchld()
360  * after it is finished doing the wait*().
361  */
362 void ast_replace_sigchld(void);
363 
364 /*!
365  * \brief Restore the SIGCHLD handler
366  *
367  * This function is called after a call to ast_replace_sigchld. It restores
368  * the SIGCHLD handler that cleans up any zombie processes.
369  */
370 void ast_unreplace_sigchld(void);
371 
372 /*!
373  \brief Send DTMF to a channel
374 
375  \param chan The channel that will receive the DTMF frames
376  \param peer (optional) Peer channel that will be autoserviced while the
377  primary channel is receiving DTMF
378  \param digits This is a string of characters representing the DTMF digits
379  to be sent to the channel. Valid characters are
380  "0123456789*#abcdABCD". Note: You can pass arguments 'f' or
381  'F', if you want to Flash the channel (if supported by the
382  channel), or 'w' to add a 500 millisecond pause to the DTMF
383  sequence.
384  \param between This is the number of milliseconds to wait in between each
385  DTMF digit. If zero milliseconds is specified, then the
386  default value of 100 will be used.
387  \param duration This is the duration that each DTMF digit should have.
388 */
389 int ast_dtmf_stream(struct ast_channel *chan, struct ast_channel *peer, const char *digits, int between, unsigned int duration);
390 
391 /*! \brief Stream a filename (or file descriptor) as a generator. */
392 int ast_linear_stream(struct ast_channel *chan, const char *filename, int fd, int allowoverride);
393 
394 /*!
395  * \brief Stream a file with fast forward, pause, reverse, restart.
396  * \param chan
397  * \param file filename
398  * \param fwd, rev, stop, pause, restart, skipms, offsetms
399  *
400  * Before calling this function, set this to be the number
401  * of ms to start from the beginning of the file. When the function
402  * returns, it will be the number of ms from the beginning where the
403  * playback stopped. Pass NULL if you don't care.
404  */
405 int ast_control_streamfile(struct ast_channel *chan, const char *file, const char *fwd, const char *rev, const char *stop, const char *pause, const char *restart, int skipms, long *offsetms);
406 
407 /*! \brief Play a stream and wait for a digit, returning the digit that was pressed */
408 int ast_play_and_wait(struct ast_channel *chan, const char *fn);
409 
410 /*!
411  * \brief Record a file based on input from a channel
412  * This function will play "auth-thankyou" upon successful recording.
413  *
414  * \param chan the channel being recorded
415  * \param playfile Filename of sound to play before recording begins
416  * \param recordfile Filename to save the recording
417  * \param maxtime_sec Longest possible message length in seconds
418  * \param fmt string containing all formats to be recorded delimited by '|'
419  * \param duration pointer to integer for storing length of the recording
420  * \param sound_duration pointer to integer for storing length of the recording minus all silence
421  * \param silencethreshold tolerance of noise levels that can be considered silence for the purpose of silence timeout, -1 for default
422  * \param maxsilence_ms Length of time in milliseconds which will trigger a timeout from silence, -1 for default
423  * \param path Optional filesystem path to unlock
424  * \param acceptdtmf Character of DTMF to end and accept the recording
425  * \param canceldtmf Character of DTMF to end and cancel the recording
426  *
427  * \retval -1 failure or hangup
428  * \retval 'S' Recording ended from silence timeout
429  * \retval 't' Recording ended from the message exceeding the maximum duration
430  * \retval dtmfchar Recording ended via the return value's DTMF character for either cancel or accept.
431  */
432 int ast_play_and_record_full(struct ast_channel *chan, const char *playfile, const char *recordfile, int maxtime_sec, const char *fmt, int *duration, int *sound_duration, int silencethreshold, int maxsilence_ms, const char *path, const char *acceptdtmf, const char *canceldtmf);
433 
434 /*!
435  * \brief Record a file based on input from a channel. Use default accept and cancel DTMF.
436  * This function will play "auth-thankyou" upon successful recording.
437  *
438  * \param chan the channel being recorded
439  * \param playfile Filename of sound to play before recording begins
440  * \param recordfile Filename to save the recording
441  * \param maxtime_sec Longest possible message length in seconds
442  * \param fmt string containing all formats to be recorded delimited by '|'
443  * \param duration pointer to integer for storing length of the recording
444  * \param sound_duration pointer to integer for storing length of the recording minus all silence
445  * \param silencethreshold tolerance of noise levels that can be considered silence for the purpose of silence timeout, -1 for default
446  * \param maxsilence_ms length of time in milliseconds which will trigger a timeout from silence, -1 for default
447  * \param path Optional filesystem path to unlock
448  *
449  * \retval -1 failure or hangup
450  * \retval 'S' Recording ended from silence timeout
451  * \retval 't' Recording ended from the message exceeding the maximum duration
452  * \retval dtmfchar Recording ended via the return value's DTMF character for either cancel or accept.
453  */
454 int ast_play_and_record(struct ast_channel *chan, const char *playfile, const char *recordfile, int maxtime_sec, const char *fmt, int *duration, int *sound_duration, int silencethreshold, int maxsilence_ms, const char *path);
455 
456 /*!
457  * \brief Record a file based on input frm a channel. Recording is performed in 'prepend' mode which works a little differently from normal recordings
458  * This function will not play a success message due to post-recording control in the application this was added for.
459  *
460  * \param chan the channel being recorded
461  * \param playfile Filename of sound to play before recording begins
462  * \param recordfile Filename to save the recording
463  * \param maxtime_sec Longest possible message length in seconds
464  * \param fmt string containing all formats to be recorded delimited by '|'
465  * \param duration pointer to integer for storing length of the recording
466  * \param sound_duration pointer to integer for storing length of the recording minus all silence
467  * \param beep whether to play a beep to prompt the recording
468  * \param silencethreshold tolerance of noise levels that can be considered silence for the purpose of silence timeout, -1 for default
469  * \param maxsilence_ms length of time in milliseconds which will trigger a timeout from silence, -1 for default.
470  *
471  * \retval -1 failure or hangup
472  * \retval 'S' Recording ended from silence timeout
473  * \retval 't' Recording either exceeded maximum duration or the call was ended via DTMF
474  */
475 int ast_play_and_prepend(struct ast_channel *chan, char *playfile, char *recordfile, int maxtime_sec, char *fmt, int *duration, int *sound_duration, int beep, int silencethreshold, int maxsilence_ms);
476 
482  /*! indicates a user terminated empty string rather than an empty string resulting
483  * from a timeout or other factors */
485 };
486 
492 };
493 
494 /*! \brief Type of locking to use in ast_lock_path / ast_unlock_path */
498 };
499 
500 /*!
501  * \brief Set the type of locks used by ast_lock_path()
502  * \param type the locking type to use
503  */
505 
506 /*!
507  * \brief Lock a filesystem path.
508  * \param path the path to be locked
509  * \return one of \ref AST_LOCK_RESULT values
510  */
511 enum AST_LOCK_RESULT ast_lock_path(const char *path);
512 
513 /*! \brief Unlock a path */
514 int ast_unlock_path(const char *path);
515 
516 /*! \brief Read a file into asterisk*/
517 char *ast_read_textfile(const char *file);
518 
519 struct ast_group_info;
520 
521 /*! \brief Split a group string into group and category, returning a default category if none is provided. */
522 int ast_app_group_split_group(const char *data, char *group, int group_max, char *category, int category_max);
523 
524 /*! \brief Set the group for a channel, splitting the provided data into group and category, if specified. */
525 int ast_app_group_set_channel(struct ast_channel *chan, const char *data);
526 
527 /*! \brief Get the current channel count of the specified group and category. */
528 int ast_app_group_get_count(const char *group, const char *category);
529 
530 /*! \brief Get the current channel count of all groups that match the specified pattern and category. */
531 int ast_app_group_match_get_count(const char *groupmatch, const char *category);
532 
533 /*! \brief Discard all group counting for a channel */
534 int ast_app_group_discard(struct ast_channel *chan);
535 
536 /*! \brief Update all group counting for a channel to a new one */
537 int ast_app_group_update(struct ast_channel *oldchan, struct ast_channel *newchan);
538 
539 /*! \brief Write Lock the group count list */
540 int ast_app_group_list_wrlock(void);
541 
542 /*! \brief Read Lock the group count list */
543 int ast_app_group_list_rdlock(void);
544 
545 /*! \brief Get the head of the group count list */
547 
548 /*! \brief Unlock the group count list */
549 int ast_app_group_list_unlock(void);
550 
551 /*!
552  \brief Define an application argument
553  \param name The name of the argument
554 */
555 #define AST_APP_ARG(name) char *name
556 
557 /*!
558  \brief Declare a structure to hold an application's arguments.
559  \param name The name of the structure
560  \param arglist The list of arguments, defined using AST_APP_ARG
561 
562  This macro declares a structure intended to be used in a call
563  to ast_app_separate_args(). The structure includes all the
564  arguments specified, plus an argv array that overlays them and an
565  argc argument counter. The arguments must be declared using AST_APP_ARG,
566  and they will all be character pointers (strings).
567 
568  \note The structure is <b>not</b> initialized, as the call to
569  ast_app_separate_args() will perform that function before parsing
570  the arguments.
571  */
572 #define AST_DECLARE_APP_ARGS(name, arglist) AST_DEFINE_APP_ARGS_TYPE(, arglist) name = { 0, }
573 
574 /*!
575  \brief Define a structure type to hold an application's arguments.
576  \param type The name of the structure type
577  \param arglist The list of arguments, defined using AST_APP_ARG
578 
579  This macro defines a structure type intended to be used in a call
580  to ast_app_separate_args(). The structure includes all the
581  arguments specified, plus an argv array that overlays them and an
582  argc argument counter. The arguments must be declared using AST_APP_ARG,
583  and they will all be character pointers (strings).
584 
585  \note This defines a structure type, but does not declare an instance
586  of the structure. That must be done separately.
587  */
588 #define AST_DEFINE_APP_ARGS_TYPE(type, arglist) \
589  struct type { \
590  unsigned int argc; \
591  char *argv[0]; \
592  arglist \
593  }
594 
595 /*!
596  \brief Performs the 'standard' argument separation process for an application.
597  \param args An argument structure defined using AST_DECLARE_APP_ARGS
598  \param parse A modifiable buffer containing the input to be parsed
599 
600  This function will separate the input string using the standard argument
601  separator character ',' and fill in the provided structure, including
602  the argc argument counter field.
603  */
604 #define AST_STANDARD_APP_ARGS(args, parse) \
605  args.argc = __ast_app_separate_args(parse, ',', 1, args.argv, ((sizeof(args) - offsetof(typeof(args), argv)) / sizeof(args.argv[0])))
606 #define AST_STANDARD_RAW_ARGS(args, parse) \
607  args.argc = __ast_app_separate_args(parse, ',', 0, args.argv, ((sizeof(args) - offsetof(typeof(args), argv)) / sizeof(args.argv[0])))
608 
609 /*!
610  \brief Performs the 'nonstandard' argument separation process for an application.
611  \param args An argument structure defined using AST_DECLARE_APP_ARGS
612  \param parse A modifiable buffer containing the input to be parsed
613  \param sep A nonstandard separator character
614 
615  This function will separate the input string using the nonstandard argument
616  separator character and fill in the provided structure, including
617  the argc argument counter field.
618  */
619 #define AST_NONSTANDARD_APP_ARGS(args, parse, sep) \
620  args.argc = __ast_app_separate_args(parse, sep, 1, args.argv, ((sizeof(args) - offsetof(typeof(args), argv)) / sizeof(args.argv[0])))
621 #define AST_NONSTANDARD_RAW_ARGS(args, parse, sep) \
622  args.argc = __ast_app_separate_args(parse, sep, 0, args.argv, ((sizeof(args) - offsetof(typeof(args), argv)) / sizeof(args.argv[0])))
623 
624 /*!
625  \brief Separate a string into arguments in an array
626  \param buf The string to be parsed (this must be a writable copy, as it will be modified)
627  \param delim The character to be used to delimit arguments
628  \param remove_chars Remove backslashes and quote characters, while parsing
629  \param array An array of 'char *' to be filled in with pointers to the found arguments
630  \param arraylen The number of elements in the array (i.e. the number of arguments you will accept)
631 
632  Note: if there are more arguments in the string than the array will hold, the last element of
633  the array will contain the remaining arguments, not separated.
634 
635  The array will be completely zeroed by this function before it populates any entries.
636 
637  \return The number of arguments found, or zero if the function arguments are not valid.
638 */
639 unsigned int __ast_app_separate_args(char *buf, char delim, int remove_chars, char **array, int arraylen);
640 #define ast_app_separate_args(a,b,c,d) __ast_app_separate_args(a,b,1,c,d)
641 
642 /*!
643  \brief A structure to hold the description of an application 'option'.
644 
645  Application 'options' are single-character flags that can be supplied
646  to the application to affect its behavior; they can also optionally
647  accept arguments enclosed in parenthesis.
648 
649  These structures are used by the ast_app_parse_options function, uses
650  this data to fill in a flags structure (to indicate which options were
651  supplied) and array of argument pointers (for those options that had
652  arguments supplied).
653  */
655  /*! \brief The flag bit that represents this option. */
656  uint64_t flag;
657  /*! \brief The index of the entry in the arguments array
658  that should be used for this option's argument. */
659  unsigned int arg_index;
660 };
661 
662 #define BEGIN_OPTIONS {
663 #define END_OPTIONS }
664 
665 /*!
666  \brief Declares an array of options for an application.
667  \param holder The name of the array to be created
668  \param options The actual options to be placed into the array
669  \sa ast_app_parse_options
670 
671  This macro declares a 'static const' array of \c struct \c ast_option
672  elements to hold the list of available options for an application.
673  Each option must be declared using either the AST_APP_OPTION()
674  or AST_APP_OPTION_ARG() macros.
675 
676  Example usage:
677  \code
678  enum my_app_option_flags {
679  OPT_JUMP = (1 << 0),
680  OPT_BLAH = (1 << 1),
681  OPT_BLORT = (1 << 2),
682  };
683 
684  enum my_app_option_args {
685  OPT_ARG_BLAH = 0,
686  OPT_ARG_BLORT,
687  !! this entry tells how many possible arguments there are,
688  and must be the last entry in the list
689  OPT_ARG_ARRAY_SIZE,
690  };
691 
692  AST_APP_OPTIONS(my_app_options, {
693  AST_APP_OPTION('j', OPT_JUMP),
694  AST_APP_OPTION_ARG('b', OPT_BLAH, OPT_ARG_BLAH),
695  AST_APP_OPTION_BLORT('B', OPT_BLORT, OPT_ARG_BLORT),
696  });
697 
698  static int my_app_exec(struct ast_channel *chan, void *data)
699  {
700  char *options;
701  struct ast_flags opts = { 0, };
702  char *opt_args[OPT_ARG_ARRAY_SIZE];
703 
704  ... do any argument parsing here ...
705 
706  if (ast_app_parse_options(my_app_options, &opts, opt_args, options)) {
707  return -1;
708  }
709  }
710  \endcode
711  */
712 #define AST_APP_OPTIONS(holder, options...) \
713  static const struct ast_app_option holder[128] = options
714 
715 /*!
716  \brief Declares an application option that does not accept an argument.
717  \param option The single character representing the option
718  \param flagno The flag index to be set if this option is present
719  \sa AST_APP_OPTIONS, ast_app_parse_options
720  */
721 #define AST_APP_OPTION(option, flagno) \
722  [option] = { .flag = flagno }
723 
724 /*!
725  \brief Declares an application option that accepts an argument.
726  \param option The single character representing the option
727  \param flagno The flag index to be set if this option is present
728  \param argno The index into the argument array where the argument should
729  be placed
730  \sa AST_APP_OPTIONS, ast_app_parse_options
731  */
732 #define AST_APP_OPTION_ARG(option, flagno, argno) \
733  [option] = { .flag = flagno, .arg_index = argno + 1 }
734 
735 /*!
736  \brief Parses a string containing application options and sets flags/arguments.
737  \param options The array of possible options declared with AST_APP_OPTIONS
738  \param flags The flag structure to have option flags set
739  \param args The array of argument pointers to hold arguments found
740  \param optstr The string containing the options to be parsed
741  \return zero for success, non-zero if an error occurs
742  \sa AST_APP_OPTIONS
743  */
744 int ast_app_parse_options(const struct ast_app_option *options, struct ast_flags *flags, char **args, char *optstr);
745 
746  /*!
747  \brief Parses a string containing application options and sets flags/arguments.
748  \param options The array of possible options declared with AST_APP_OPTIONS
749  \param flags The 64-bit flag structure to have option flags set
750  \param args The array of argument pointers to hold arguments found
751  \param optstr The string containing the options to be parsed
752  \return zero for success, non-zero if an error occurs
753  \sa AST_APP_OPTIONS
754  */
755 int ast_app_parse_options64(const struct ast_app_option *options, struct ast_flags64 *flags, char **args, char *optstr);
756 
757 /*! \brief Given a list of options array, return an option string based on passed flags
758  \param options The array of possible options declared with AST_APP_OPTIONS
759  \param flags The flags of the options that you wish to populate the buffer with
760  \param buf The buffer to fill with the string of options
761  \param len The maximum length of buf
762 */
763 void ast_app_options2str64(const struct ast_app_option *options, struct ast_flags64 *flags, char *buf, size_t len);
764 
765 /*! \brief Present a dialtone and collect a certain length extension.
766  \return Returns 1 on valid extension entered, -1 on hangup, or 0 on invalid extension.
767 \note Note that if 'collect' holds digits already, new digits will be appended, so be sure it's initialized properly */
768 int ast_app_dtget(struct ast_channel *chan, const char *context, char *collect, size_t size, int maxlen, int timeout);
769 
770 /*! \brief Allow to record message and have a review option */
771 int ast_record_review(struct ast_channel *chan, const char *playfile, const char *recordfile, int maxtime, const char *fmt, int *duration, const char *path);
772 
773 /*!\brief Decode an encoded control or extended ASCII character
774  * \param[in] stream String to decode
775  * \param[out] result Decoded character
776  * \param[out] consumed Number of characters used in stream to encode the character
777  * \retval -1 Stream is of zero length
778  * \retval 0 Success
779  */
780 int ast_get_encoded_char(const char *stream, char *result, size_t *consumed);
781 
782 /*!\brief Decode a stream of encoded control or extended ASCII characters
783  * \param[in] stream Encoded string
784  * \param[out] result Decoded string
785  * \param[in] result_len Maximum size of the result buffer
786  * \return A pointer to the result string
787  */
788 char *ast_get_encoded_str(const char *stream, char *result, size_t result_len);
789 
790 /*! \brief Decode a stream of encoded control or extended ASCII characters */
791 int ast_str_get_encoded_str(struct ast_str **str, int maxlen, const char *stream);
792 
793 /*!
794  * \brief Common routine for child processes, to close all fds prior to exec(2)
795  * \param[in] n starting file descriptor number for closing all higher file descriptors
796  * \since 1.6.1
797  */
798 void ast_close_fds_above_n(int n);
799 
800 /*!
801  * \brief Common routine to safely fork without a chance of a signal handler firing badly in the child
802  * \param[in] stop_reaper flag to determine if sigchld handler is replaced or not
803  * \since 1.6.1
804  */
805 int ast_safe_fork(int stop_reaper);
806 
807 /*!
808  * \brief Common routine to cleanup after fork'ed process is complete (if reaping was stopped)
809  * \since 1.6.1
810  */
811 void ast_safe_fork_cleanup(void);
812 
813 /*!
814  * \brief Common routine to parse time lengths, with optional time unit specifier
815  * \param[in] timestr String to parse
816  * \param[in] defunit Default unit type
817  * \param[out] result Resulting value, specified in milliseconds
818  * \retval 0 Success
819  * \retval -1 Failure
820  * \since 1.8
821  */
822 int ast_app_parse_timelen(const char *timestr, int *result, enum ast_timelen defunit);
823 
824 #if defined(__cplusplus) || defined(c_plusplus)
825 }
826 #endif
827 
828 #endif /* _ASTERISK_APP_H */
int ast_play_and_record(struct ast_channel *chan, const char *playfile, const char *recordfile, int maxtime_sec, const char *fmt, int *duration, int *sound_duration, int silencethreshold, int maxsilence_ms, const char *path)
Record a file based on input from a channel. Use default accept and cancel DTMF. This function will p...
Definition: app.c:1183
Main Channel structure associated with a channel.
Definition: channel.h:742
channel group info
Definition: channel.h:2459
ast_ivr_action action
Definition: app.h:71
int ast_safe_system(const char *s)
Safely spawn an external program while closing file descriptors.
Definition: asterisk.c:1077
int ast_app_dtget(struct ast_channel *chan, const char *context, char *collect, size_t size, int maxlen, int timeout)
Present a dialtone and collect a certain length extension.
Definition: app.c:120
int ast_play_and_record_full(struct ast_channel *chan, const char *playfile, const char *recordfile, int maxtime_sec, const char *fmt, int *duration, int *sound_duration, int silencethreshold, int maxsilence_ms, const char *path, const char *acceptdtmf, const char *canceldtmf)
Record a file based on input from a channel This function will play &quot;auth-thankyou&quot; upon successful r...
Definition: app.c:1178
int ast_app_getdata(struct ast_channel *c, const char *prompt, char *s, int maxlen, int timeout)
Plays a stream and gets DTMF data from a channel.
Definition: app.c:178
unsigned int flags
Definition: app.h:77
int ast_safe_fork(int stop_reaper)
Common routine to safely fork without a chance of a signal handler firing badly in the child...
Definition: app.c:2242
String manipulation functions.
int ast_app_group_set_channel(struct ast_channel *chan, const char *data)
Set the group for a channel, splitting the provided data into group and category, if specified...
Definition: app.c:1222
int ast_control_streamfile(struct ast_channel *chan, const char *file, const char *fwd, const char *rev, const char *stop, const char *pause, const char *restart, int skipms, long *offsetms)
Stream a file with fast forward, pause, reverse, restart.
Definition: app.c:683
AST_THREADSTORAGE_EXTERNAL(ast_str_thread_global_buf)
int ast_app_parse_options64(const struct ast_app_option *options, struct ast_flags64 *flags, char **args, char *optstr)
Parses a string containing application options and sets flags/arguments.
Definition: app.c:2106
int ast_app_has_voicemail(const char *mailbox, const char *folder)
Determine if a given mailbox has any voicemail If folder is NULL, defaults to &quot;INBOX&quot;. If folder is &quot;INBOX&quot;, includes the number of messages in the &quot;Urgent&quot; folder.
Definition: app.c:421
int ast_app_parse_timelen(const char *timestr, int *result, enum ast_timelen defunit)
Common routine to parse time lengths, with optional time unit specifier.
Definition: app.c:2311
char * ast_get_encoded_str(const char *stream, char *result, size_t result_len)
Decode a stream of encoded control or extended ASCII characters.
Definition: app.c:2197
int ast_str_get_encoded_str(struct ast_str **str, int maxlen, const char *stream)
Decode a stream of encoded control or extended ASCII characters.
Definition: app.c:2210
int ast_app_parse_options(const struct ast_app_option *options, struct ast_flags *flags, char **args, char *optstr)
Parses a string containing application options and sets flags/arguments.
Definition: app.c:2101
AST_LOCK_RESULT
Definition: app.h:487
int ast_unlock_path(const char *path)
Unlock a path.
Definition: app.c:1668
void ast_safe_fork_cleanup(void)
Common routine to cleanup after fork&#39;ed process is complete (if reaping was stopped) ...
Definition: app.c:2306
void ast_app_options2str64(const struct ast_app_option *options, struct ast_flags64 *flags, char *buf, size_t len)
Given a list of options array, return an option string based on passed flags.
Definition: app.c:2111
int ast_app_group_discard(struct ast_channel *chan)
Discard all group counting for a channel.
Definition: app.c:1348
char * option
Definition: app.h:70
unsigned int stop
Definition: app_meetme.c:969
int ast_app_exec_sub(struct ast_channel *autoservice_chan, struct ast_channel *sub_chan, const char *sub_args, int ignore_hangup)
Run a subroutine on a channel, placing an optional second channel into autoservice.
Definition: app.c:343
int(* ast_ivr_callback)(struct ast_channel *chan, char *option, void *cbdata)
Callback function for IVR.
Definition: app.h:42
const char * str
Definition: app_jack.c:144
Definitions to aid in the use of thread local storage.
Structure used to handle a large number of boolean flags == used only in app_dial?
Definition: utils.h:206
ast_ivr_action
Definition: app.h:44
void ast_unreplace_sigchld(void)
Restore the SIGCHLD handler.
Definition: asterisk.c:1062
int ast_app_group_match_get_count(const char *groupmatch, const char *category)
Get the current channel count of all groups that match the specified pattern and category.
Definition: app.c:1289
static char beep[AST_MAX_BUF]
Definition: chan_agent.c:239
int ast_app_run_sub(struct ast_channel *autoservice_chan, struct ast_channel *sub_chan, const char *sub_location, const char *sub_args, int ignore_hangup)
Run a subroutine on a channel, placing an optional second channel into autoservice.
Definition: app.c:370
void * adata
Definition: app.h:72
int ast_app_group_split_group(const char *data, char *group, int group_max, char *category, int category_max)
Split a group string into group and category, returning a default category if none is provided...
Definition: app.c:1195
int ast_play_and_wait(struct ast_channel *chan, const char *fn)
Play a stream and wait for a digit, returning the digit that was pressed.
Definition: app.c:822
enum AST_LOCK_RESULT ast_lock_path(const char *path)
Lock a filesystem path.
Definition: app.c:1652
A structure to hold the description of an application &#39;option&#39;.
Definition: app.h:654
int(* run_sub)(struct ast_channel *chan, const char *args, int ignore_hangup)
Callback for the routine to run a subroutine on a channel.
Definition: app.h:184
char * title
Definition: app.h:76
int ast_app_getdata_full(struct ast_channel *c, const char *prompt, char *s, int maxlen, int timeout, int audiofd, int ctrlfd)
Full version with audiofd and controlfd. NOTE: returns &#39;2&#39; on ctrlfd available, not &#39;1&#39; like other fu...
Definition: app.c:231
static int silencethreshold
int ast_app_inboxcount(const char *mailbox, int *newmsgs, int *oldmsgs)
Determine number of new/old messages in a mailbox.
Definition: app.c:435
ast_timelen
Definition: app.h:87
int ast_app_sayname(struct ast_channel *chan, const char *mailbox, const char *context)
Given a mailbox and context, play that mailbox owner&#39;s name to the channel specified.
Definition: app.c:478
int ast_app_inboxcount2(const char *mailbox, int *urgentmsgs, int *newmsgs, int *oldmsgs)
Determine number of urgent/new/old messages in a mailbox.
Definition: app.c:455
int ast_app_group_list_wrlock(void)
Write Lock the group count list.
Definition: app.c:1365
struct ast_group_info * ast_app_group_list_head(void)
Get the head of the group count list.
Definition: app.c:1375
static int skipms
void * module
Definition: app.h:170
uint64_t flag
The flag bit that represents this option.
Definition: app.h:656
int ast_get_encoded_char(const char *stream, char *result, size_t *consumed)
Decode an encoded control or extended ASCII character.
Definition: app.c:2122
The descriptor of a dynamic string XXX storage will be optimized later if needed We use the ts field ...
Definition: strings.h:364
static struct @350 args
static int array(struct ast_channel *chan, const char *cmd, char *var, const char *value)
Definition: func_strings.c:913
const char * ast_app_expand_sub_args(struct ast_channel *chan, const char *args)
Add missing context/exten to subroutine argument string.
Definition: app.c:324
Stack applications callback functions.
Definition: app.h:165
static int len(struct ast_channel *chan, const char *cmd, char *data, char *buf, size_t buflen)
int ast_app_run_macro(struct ast_channel *autoservice_chan, struct ast_channel *macro_chan, const char *macro_name, const char *macro_args)
Run a macro on a channel, placing an optional second channel into autoservice.
Definition: app.c:294
int ast_ivr_menu_run(struct ast_channel *c, struct ast_ivr_menu *menu, void *cbdata)
Runs an IVR menu.
Definition: app.c:1980
unsigned int __ast_app_separate_args(char *buf, char delim, int remove_chars, char **array, int arraylen)
Separate a string into arguments in an array.
Definition: app.c:1388
void ast_close_fds_above_n(int n)
Common routine for child processes, to close all fds prior to exec(2)
Definition: app.c:2237
struct ast_ivr_option * options
Definition: app.h:78
char * category
Definition: channel.h:2461
void ast_install_stack_functions(const struct ast_app_stack_funcs *funcs)
Set stack application function callbacks.
Definition: app.c:319
static char acceptdtmf
Definition: chan_agent.c:227
unsigned int arg_index
The index of the entry in the arguments array that should be used for this option&#39;s argument...
Definition: app.h:659
static const char type[]
Definition: chan_nbs.c:57
Structure used to handle boolean flags.
Definition: utils.h:200
void ast_install_vm_functions(int(*has_voicemail_func)(const char *mailbox, const char *folder), int(*inboxcount_func)(const char *mailbox, int *newmsgs, int *oldmsgs), int(*inboxcount2_func)(const char *mailbox, int *urgentmsgs, int *newmsgs, int *oldmsgs), int(*messagecount_func)(const char *context, const char *mailbox, const char *folder), int(*sayname_func)(struct ast_channel *chan, const char *mailbox, const char *context))
Set voicemail function callbacks.
Definition: app.c:399
int ast_play_and_prepend(struct ast_channel *chan, char *playfile, char *recordfile, int maxtime_sec, char *fmt, int *duration, int *sound_duration, int beep, int silencethreshold, int maxsilence_ms)
Record a file based on input frm a channel. Recording is performed in &#39;prepend&#39; mode which works a li...
Definition: app.c:1188
int ast_app_group_list_unlock(void)
Unlock the group count list.
Definition: app.c:1380
int ast_app_group_update(struct ast_channel *oldchan, struct ast_channel *newchan)
Update all group counting for a channel to a new one.
Definition: app.c:1329
void ast_set_lock_type(enum AST_LOCK_TYPE type)
Set the type of locks used by ast_lock_path()
Definition: app.c:1647
AST_LOCK_TYPE
Type of locking to use in ast_lock_path / ast_unlock_path.
Definition: app.h:495
int ast_app_group_get_count(const char *group, const char *category)
Get the current channel count of the specified group and category.
Definition: app.c:1269
static struct ast_str * prompt
Definition: asterisk.c:2395
static char context[AST_MAX_CONTEXT]
Definition: chan_alsa.c:107
int ast_dtmf_stream(struct ast_channel *chan, struct ast_channel *peer, const char *digits, int between, unsigned int duration)
Send DTMF to a channel.
Definition: app.c:501
int ast_record_review(struct ast_channel *chan, const char *playfile, const char *recordfile, int maxtime, const char *fmt, int *duration, const char *path)
Allow to record message and have a review option.
Definition: app.c:1684
int ast_app_messagecount(const char *context, const char *mailbox, const char *folder)
Check number of messages in a given context, mailbox, and folder.
Definition: app.c:486
int ast_linear_stream(struct ast_channel *chan, const char *filename, int fd, int allowoverride)
Stream a filename (or file descriptor) as a generator.
Definition: app.c:653
int ast_app_exec_macro(struct ast_channel *autoservice_chan, struct ast_channel *macro_chan, const char *macro_args)
Run a macro on a channel, placing an optional second channel into autoservice.
Definition: app.c:254
int ast_app_group_list_rdlock(void)
Read Lock the group count list.
Definition: app.c:1370
ast_getdata_result
Definition: app.h:477
char * ast_read_textfile(const char *file)
Read a file into asterisk.
Definition: app.c:1987
void ast_replace_sigchld(void)
Replace the SIGCHLD handler.
Definition: asterisk.c:1047
static char mailbox[AST_MAX_EXTENSION]
Definition: chan_mgcp.c:197
void ast_uninstall_vm_functions(void)
Definition: app.c:412