Asterisk - The Open Source Telephony Project  21.4.1
include/asterisk/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/stringfields.h"
27 #include "asterisk/strings.h"
28 #include "asterisk/threadstorage.h"
29 #include "asterisk/file.h"
30 #include "asterisk/linkedlists.h"
31 #include "asterisk/utils.h"
32 #include "asterisk/stasis.h"
33 
34 struct ast_flags64;
35 
36 #if defined(__cplusplus) || defined(c_plusplus)
37 extern "C" {
38 #endif
39 
40 AST_THREADSTORAGE_EXTERNAL(ast_str_thread_global_buf);
41 
42 /* IVR stuff */
43 
44 /*! \brief Callback function for IVR
45  \retval 0 on completion.
46  \retval -1 on hangup or digit if interrupted.
47  */
48 typedef int (ast_ivr_callback)(struct ast_channel *chan, char *option, void *cbdata);
49 
50 typedef enum {
51  AST_ACTION_UPONE, /*!< adata is unused */
52  AST_ACTION_EXIT, /*!< adata is the return value for ast_ivr_menu_run if channel was not hungup */
53  AST_ACTION_CALLBACK, /*!< adata is an ast_ivr_callback */
54  AST_ACTION_PLAYBACK, /*!< adata is file to play */
55  AST_ACTION_BACKGROUND, /*!< adata is file to play */
56  AST_ACTION_PLAYLIST, /*!< adata is list of files, separated by ; to play */
57  AST_ACTION_MENU, /*!< adata is a pointer to an ast_ivr_menu */
58  AST_ACTION_REPEAT, /*!< adata is max # of repeats, cast to a pointer */
59  AST_ACTION_RESTART, /*!< adata is like repeat, but resets repeats to 0 */
60  AST_ACTION_TRANSFER, /*!< adata is a string with exten[\@context] */
61  AST_ACTION_WAITOPTION, /*!< adata is a timeout, or 0 for defaults */
62  AST_ACTION_NOOP, /*!< adata is unused */
63  AST_ACTION_BACKLIST, /*!< adata is list of files separated by ; allows interruption */
65 
66 /*!
67  Special "options" are:
68  \arg "s" - "start here (one time greeting)"
69  \arg "g" - "greeting/instructions"
70  \arg "t" - "timeout"
71  \arg "h" - "hangup"
72  \arg "i" - "invalid selection"
73 
74 */
76  char *option;
77  ast_ivr_action action;
78  void *adata;
79 };
80 
81 struct ast_ivr_menu {
82  char *title; /*!< Title of menu */
83  unsigned int flags; /*!< Flags */
84  struct ast_ivr_option *options; /*!< All options */
85 };
86 
87 /*!
88  * \brief Structure used for ast_copy_recording_to_vm in order to cleanly supply
89  * data needed for making the recording from the recorded file.
90  */
93  AST_STRING_FIELD(context);
94  AST_STRING_FIELD(mailbox);
95  AST_STRING_FIELD(folder);
96  AST_STRING_FIELD(recording_file);
97  AST_STRING_FIELD(recording_ext);
98  AST_STRING_FIELD(call_context);
99  AST_STRING_FIELD(call_extension);
100  AST_STRING_FIELD(call_callerchan);
101  AST_STRING_FIELD(call_callerid);
102  );
103  int call_priority;
104 };
105 
106 #define AST_IVR_FLAG_AUTORESTART (1 << 0)
107 
108 #define AST_IVR_DECLARE_MENU(holder, title, flags, foo...) \
109  static struct ast_ivr_option __options_##holder[] = foo;\
110  static struct ast_ivr_menu holder = { title, flags, __options_##holder }
111 
112 enum ast_timelen {
113  TIMELEN_HOURS,
114  TIMELEN_MINUTES,
115  TIMELEN_SECONDS,
116  TIMELEN_MILLISECONDS,
117 };
118 
119 /*! \brief Runs an IVR menu
120  \retval 0 on successful completion.
121  \retval -1 on hangup.
122  \retval -2 on user error in menu.
123 */
124 int ast_ivr_menu_run(struct ast_channel *c, struct ast_ivr_menu *menu, void *cbdata);
125 
127  AST_GETDATA_FAILED = -1,
128  AST_GETDATA_COMPLETE = 0,
129  AST_GETDATA_TIMEOUT = 1,
130  AST_GETDATA_INTERRUPTED = 2,
131  /*! indicates a user terminated empty string rather than an empty string resulting
132  * from a timeout or other factors */
134 };
135 
136 /*! \brief Plays a stream and gets DTMF data from a channel
137  * \param c Which channel one is interacting with
138  * \param prompt File to pass to ast_streamfile (the one that you wish to play).
139  * It is also valid for this to be multiple files concatenated by "&".
140  * For example, "file1&file2&file3".
141  * \param s The location where the DTMF data will be stored
142  * \param maxlen Max Length of the data
143  * \param timeout Timeout length waiting for data(in milliseconds). Set to 0 for standard timeout(six seconds), or -1 for no time out.
144  *
145  * This function was designed for application programmers for situations where they need
146  * to play a message and then get some DTMF data in response to the message. If a digit
147  * is pressed during playback, it will immediately break out of the message and continue
148  * execution of your code.
149  */
150 enum ast_getdata_result ast_app_getdata(struct ast_channel *c, const char *prompt, char *s, int maxlen, int timeout);
151 
152 /*! \brief Plays a stream and gets DTMF data from a channel
153  * \param c Which channel one is interacting with
154  * \param prompt File to pass to ast_streamfile (the one that you wish to play).
155  * It is also valid for this to be multiple files concatenated by "&".
156  * For example, "file1&file2&file3".
157  * \param s The location where the DTMF data will be stored
158  * \param maxlen Max Length of the data
159  * \param timeout Timeout length waiting for data(in milliseconds). Set to 0 for standard timeout(six seconds), or -1 for no time out.
160  * \param terminator A string of characters that may be used as terminators to end input. If NULL, "#" will be used.
161  *
162  * This function was designed for application programmers for situations where they need
163  * to play a message and then get some DTMF data in response to the message. If a digit
164  * is pressed during playback, it will immediately break out of the message and continue
165  * execution of your code.
166  */
167 enum ast_getdata_result ast_app_getdata_terminator(struct ast_channel *c, const char *prompt, char *s, int maxlen, int timeout, char *terminator);
168 
169 /*! \brief Full version with audiofd and controlfd. NOTE: returns '2' on ctrlfd available, not '1' like other full functions */
170 int ast_app_getdata_full(struct ast_channel *c, const char *prompt, char *s, int maxlen, int timeout, int audiofd, int ctrlfd);
171 
172 /*!
173  * \brief Stack applications callback functions.
174  */
176  /*!
177  * Module reference pointer so the module will stick around
178  * while a callback is active.
179  */
180  void *module;
181 
182  /*!
183  * \brief Callback for the routine to run a subroutine on a channel.
184  *
185  * \note Absolutely _NO_ channel locks should be held before calling this function.
186  *
187  * \param chan Channel to execute subroutine on.
188  * \param args Gosub application argument string.
189  * \param ignore_hangup TRUE if a hangup does not stop execution of the routine.
190  *
191  * \retval 0 success
192  * \retval -1 on error
193  */
194  int (*run_sub)(struct ast_channel *chan, const char *args, int ignore_hangup);
195 
196  /*!
197  * \brief Add missing context/exten to Gosub application argument string.
198  *
199  * \param chan Channel to obtain context/exten.
200  * \param args Gosub application argument string.
201  *
202  * \details
203  * Fills in the optional context and exten from the given channel.
204  *
205  * \return New-args Gosub argument string on success. Must be freed.
206  * \retval NULL on error.
207  */
208  const char *(*expand_sub_args)(struct ast_channel *chan, const char *args);
209 
210  /* Add new API calls to the end here. */
211 };
212 
213 /*!
214  * \since 11
215  * \brief Set stack application function callbacks
216  * \param funcs Stack applications callback functions.
217  */
218 void ast_install_stack_functions(const struct ast_app_stack_funcs *funcs);
219 
220 /*!
221  * \brief Add missing context/exten to subroutine argument string.
222  *
223  * \param chan Channel to obtain context/exten.
224  * \param args Gosub application argument string.
225  *
226  * \details
227  * Fills in the optional context and exten from the given channel.
228  *
229  * \return New-args Gosub argument string on success. Must be freed.
230  * \retval NULL on error.
231  */
232 const char *ast_app_expand_sub_args(struct ast_channel *chan, const char *args);
233 
234 /*!
235  * \since 11
236  * \brief Run a subroutine on a channel, placing an optional second channel into autoservice.
237  *
238  * \details
239  * This is a shorthand method that makes it very easy to run a
240  * subroutine on any given channel. It is perfectly reasonable
241  * to supply a NULL autoservice_chan here in case there is no
242  * channel to place into autoservice.
243  *
244  * \note Absolutely _NO_ channel locks should be held before calling this function.
245  *
246  * \param autoservice_chan A channel to place into autoservice while the subroutine is run
247  * \param sub_chan Channel to execute subroutine on.
248  * \param sub_args Gosub application argument string.
249  * \param ignore_hangup TRUE if a hangup does not stop execution of the routine.
250  *
251  * \retval 0 success
252  * \retval -1 on error
253  */
254 int ast_app_exec_sub(struct ast_channel *autoservice_chan, struct ast_channel *sub_chan, const char *sub_args, int ignore_hangup);
255 
256 /*!
257  * \since 11
258  * \brief Run a subroutine on a channel, placing an optional second channel into autoservice.
259  *
260  * \details
261  * This is a shorthand method that makes it very easy to run a
262  * subroutine on any given channel. It is perfectly reasonable
263  * to supply a NULL autoservice_chan here in case there is no
264  * channel to place into autoservice.
265  *
266  * \note Absolutely _NO_ channel locks should be held before calling this function.
267  *
268  * \param autoservice_chan A channel to place into autoservice while the subroutine is run
269  * \param sub_chan Channel to execute subroutine on.
270  * \param sub_location The location of the subroutine to run.
271  * \param sub_args The arguments to pass to the subroutine.
272  * \param ignore_hangup TRUE if a hangup does not stop execution of the routine.
273  *
274  * \retval 0 success
275  * \retval -1 on error
276  */
277 int ast_app_run_sub(struct ast_channel *autoservice_chan,
278  struct ast_channel *sub_chan, const char *sub_location, const char *sub_args, int ignore_hangup);
279 
280 enum ast_vm_snapshot_sort_val {
281  AST_VM_SNAPSHOT_SORT_BY_ID = 0,
282  AST_VM_SNAPSHOT_SORT_BY_TIME,
283 };
284 
287  AST_STRING_FIELD(msg_id);
288  AST_STRING_FIELD(callerid);
289  AST_STRING_FIELD(callerchan);
290  AST_STRING_FIELD(exten);
291  AST_STRING_FIELD(origdate);
292  AST_STRING_FIELD(origtime);
293  AST_STRING_FIELD(duration);
294  AST_STRING_FIELD(folder_name);
295  AST_STRING_FIELD(flag);
296  );
297  unsigned int msg_number;
298 
300 };
301 
303  int total_msg_num;
304  int folders;
305  /* Things are not quite as they seem here. This points to an allocated array of lists. */
307 };
308 
309 /*!
310  * \brief Voicemail playback callback function definition
311  *
312  * \param chan Channel to play the file back on.
313  * \param playfile Location of file on disk
314  * \param duration of file in seconds. This will be zero if msg is very short or
315  * has an unknown duration.
316  */
317 typedef void (ast_vm_msg_play_cb)(struct ast_channel *chan, const char *playfile, int duration);
318 
319 /*!
320  * \brief Determines if the given folder has messages.
321  *
322  * \param mailboxes Comma or & delimited list of mailboxes (user\@context).
323  * If no context is found, uses 'default' for the context.
324  * \param folder The folder to look in. Default is INBOX if not provided.
325  *
326  * \retval 1 if the folder has one or more messages.
327  * \retval 0 otherwise.
328  */
329 typedef int (ast_has_voicemail_fn)(const char *mailboxes, const char *folder);
330 
331 /*!
332  * \brief Gets the number of messages that exist for the mailbox list.
333  *
334  * \param mailboxes Comma or space delimited list of mailboxes (user\@context).
335  * If no context is found, uses 'default' for the context.
336  * \param newmsgs Where to put the count of new messages. (Can be NULL)
337  * \param oldmsgs Where to put the count of old messages. (Can be NULL)
338  *
339  * \details
340  * Simultaneously determines the count of new + urgent and old
341  * messages. The total messages would then be the sum of these.
342  *
343  * \retval 0 on success
344  * \retval -1 on failure
345  */
346 typedef int (ast_inboxcount_fn)(const char *mailboxes, int *newmsgs, int *oldmsgs);
347 
348 /*!
349  * \brief Gets the number of messages that exist for the mailbox list.
350  *
351  * \param mailboxes Comma or space delimited list of mailboxes (user\@context).
352  * If no context is found, uses 'default' for the context.
353  * \param urgentmsgs Where to put the count of urgent messages. (Can be NULL)
354  * \param newmsgs Where to put the count of new messages. (Can be NULL)
355  * \param oldmsgs Where to put the count of old messages. (Can be NULL)
356  *
357  * \details
358  * Simultaneously determines the count of new, old, and urgent
359  * messages. The total messages would then be the sum of these
360  * three.
361  *
362  * \retval 0 on success
363  * \retval -1 on failure
364  */
365 typedef int (ast_inboxcount2_fn)(const char *mailboxes, int *urgentmsgs, int *newmsgs, int *oldmsgs);
366 
367 /*!
368  * \brief Gets the number of messages that exist in a mailbox folder.
369  *
370  * \param mailbox_id The mailbox name.
371  * \param folder The folder to look in. Default is INBOX if not provided.
372  *
373  * \note If requesting INBOX then the returned count is INBOX + Urgent.
374  *
375  * \return The number of messages in the mailbox folder (zero or more).
376  */
377 typedef int (ast_messagecount_fn)(const char *mailbox_id, const char *folder);
378 
379 /*!
380  * \brief Play a recorded user name for the mailbox to the specified channel.
381  *
382  * \param chan Where to play the recorded name file.
383  * \param mailbox_id The mailbox name.
384  *
385  * \retval 0 Name played without interruption
386  * \return dtmf ASCII value of the DTMF which interrupted playback.
387  * \retval -1 Unable to locate mailbox or hangup occurred.
388  */
389 typedef int (ast_sayname_fn)(struct ast_channel *chan, const char *mailbox_id);
390 
391 /*!
392  * \brief Creates a voicemail based on a specified file to a mailbox.
393  *
394  * \param vm_rec_data A record containing filename and voicemail txt info.
395  *
396  * \retval 0 on success
397  * \retval -1 on failure
398  */
399 typedef int (ast_copy_recording_to_vm_fn)(struct ast_vm_recording_data *vm_rec_data);
400 
401 /*!
402  * \brief Convert the mailbox folder id to a folder name.
403  *
404  * \param id Mailbox folder id to convert.
405  *
406  * \deprecated Nothing calls it and nothing ever should.
407  *
408  * \return The folder name associated with the id.
409  */
410 typedef const char *(ast_vm_index_to_foldername_fn)(int id);
411 
412 /*!
413  * \brief Create a snapshot of a mailbox which contains information about every msg.
414  *
415  * \param user The user part of user\@context.
416  * \param context The context part of user\@context. Must be explicit.
417  * \param folder When not NULL only msgs from the specified folder will be included.
418  * \param descending list the msgs in descending order rather than ascending order.
419  * \param sort_val What to sort in the snapshot.
420  * \param combine_INBOX_and_OLD When this argument is set, The OLD folder will be represented
421  * in the INBOX folder of the snapshot. This allows the snapshot to represent the
422  * OLD and INBOX messages in sorted order merged together.
423  *
424  * \note Only used by voicemail unit tests.
425  *
426  * \return snapshot on success
427  * \retval NULL on failure
428  */
430  const char *context, const char *folder, int descending,
431  enum ast_vm_snapshot_sort_val sort_val, int combine_INBOX_and_OLD);
432 
433 /*!
434  * \brief destroy a snapshot
435  *
436  * \param mailbox_snapshot The snapshot to destroy.
437  *
438  * \note Only used by voicemail unit tests.
439  *
440  * \retval NULL
441  */
443 
444 /*!
445  * \brief Move messages from one folder to another
446  *
447  * \param mailbox The mailbox to which the folders belong
448  * \param context The voicemail context for the mailbox
449  * \param num_msgs The number of messages to move
450  * \param oldfolder The folder from where messages should be moved
451  * \param old_msg_ids The message IDs of the messages to move
452  * \param newfolder The folder to which messages should be moved
453  * new folder. This array must be num_msgs sized.
454  *
455  * \note Only used by voicemail unit tests.
456  *
457  * \retval -1 Failure
458  * \retval 0 Success
459  */
460 typedef int (ast_vm_msg_move_fn)(const char *mailbox, const char *context, size_t num_msgs,
461  const char *oldfolder, const char *old_msg_ids[], const char *newfolder);
462 
463 /*!
464  * \brief Remove/delete messages from a mailbox folder.
465  *
466  * \param mailbox The mailbox from which to delete messages
467  * \param context The voicemail context for the mailbox
468  * \param num_msgs The number of messages to delete
469  * \param folder The folder from which to remove messages
470  * \param msgs The message IDs of the messages to delete
471  *
472  * \note Only used by voicemail unit tests.
473  *
474  * \retval -1 Failure
475  * \retval 0 Success
476  */
477 typedef int (ast_vm_msg_remove_fn)(const char *mailbox, const char *context, size_t num_msgs,
478  const char *folder, const char *msgs[]);
479 
480 /*!
481  * \brief forward a message from one mailbox to another.
482  *
483  * \brief from_mailbox The original mailbox the message is being forwarded from
484  * \brief from_context The voicemail context of the from_mailbox
485  * \brief from_folder The folder from which the message is being forwarded
486  * \brief to_mailbox The mailbox to forward the message to
487  * \brief to_context The voicemail context of the to_mailbox
488  * \brief to_folder The folder to which the message is being forwarded
489  * \brief num_msgs The number of messages being forwarded
490  * \brief msg_ids The message IDs of the messages in from_mailbox to forward
491  * \brief delete_old If non-zero, the forwarded messages are also deleted from from_mailbox.
492  * Otherwise, the messages will remain in the from_mailbox.
493  *
494  * \note Only used by voicemail unit tests.
495  *
496  * \retval -1 Failure
497  * \retval 0 Success
498  */
499 typedef int (ast_vm_msg_forward_fn)(const char *from_mailbox, const char *from_context,
500  const char *from_folder, const char *to_mailbox, const char *to_context,
501  const char *to_folder, size_t num_msgs, const char *msg_ids[], int delete_old);
502 
503 /*!
504  * \brief Play a voicemail msg back on a channel.
505  *
506  * \param chan
507  * \param mailbox msg is in.
508  * \param context of mailbox.
509  * \param folder voicemail folder to look in.
510  * \param msg_num message number in the voicemailbox to playback to the channel.
511  * \param cb
512  *
513  * \note Only used by voicemail unit tests.
514  *
515  * \retval 0 success
516  * \retval -1 failure
517  */
518 typedef int (ast_vm_msg_play_fn)(struct ast_channel *chan, const char *mailbox,
519  const char *context, const char *folder, const char *msg_num, ast_vm_msg_play_cb *cb);
520 
521 #define VM_MODULE_VERSION 2
522 
523 /*! \brief Voicemail function table definition. */
525  /*!
526  * \brief The version of this function table.
527  *
528  * \note If the ABI for this table changes, the module version
529  * (\ref VM_MODULE_VERSION) should be incremented.
530  */
531  unsigned int module_version;
532  /*! \brief The name of the module that provides the voicemail functionality */
533  const char *module_name;
534  /*! \brief The module for the voicemail provider */
536 
538  ast_inboxcount_fn *inboxcount;
540  ast_messagecount_fn *messagecount;
541  ast_copy_recording_to_vm_fn *copy_recording_to_vm;
542  ast_vm_index_to_foldername_fn *index_to_foldername;
543  ast_vm_mailbox_snapshot_create_fn *mailbox_snapshot_create;
544  ast_vm_mailbox_snapshot_destroy_fn *mailbox_snapshot_destroy;
545  ast_vm_msg_move_fn *msg_move;
546  ast_vm_msg_remove_fn *msg_remove;
547  ast_vm_msg_forward_fn *msg_forward;
548  ast_vm_msg_play_fn *msg_play;
549 };
550 
551 /*!
552  * \brief Determine if a voicemail provider is registered.
553  * \since 12.0.0
554  *
555  * \retval 0 if no provider registered.
556  * \retval 1 if a provider is registered.
557  */
558 int ast_vm_is_registered(void);
559 
560 /*!
561  * \brief Set voicemail function callbacks
562  *
563  * \param vm_table Voicemail function table to install.
564  * \param module Pointer to the module implementing the interface
565  *
566  * \retval 0 on success.
567  * \retval -1 on error.
568  * \retval AST_MODULE_LOAD_DECLINE if there's already another provider registered.
569  */
570 int __ast_vm_register(const struct ast_vm_functions *vm_table, struct ast_module *module);
571 
572 /*! \brief See \ref __ast_vm_register() */
573 #define ast_vm_register(vm_table) __ast_vm_register(vm_table, AST_MODULE_SELF)
574 
575 /*!
576  * \brief Unregister the specified voicemail provider
577  *
578  * \param module_name The module name of the provider to unregister
579  */
580 void ast_vm_unregister(const char *module_name);
581 
582 #ifdef TEST_FRAMEWORK
583 /*!
584  * \brief Swap out existing voicemail functions with a temporary set of functions for use with unit tests
585  *
586  * \param vm_table function table to use for testing
587  *
588  * \note ast_vm_test_swap_table_out should be called to restore the original set before testing concludes
589  */
590 void ast_vm_test_swap_table_in(const struct ast_vm_functions *vm_table);
591 
592 /*!
593  * \brief Used after ast_vm_test_swap_table_in to restore the original set of voicemail functions
594  */
595 void ast_vm_test_swap_table_out(void);
596 #endif
597 
598 #define VM_GREETER_MODULE_VERSION 1
599 
600 /*! \brief Voicemail greeter function table definition. */
602  /*!
603  * \brief The version of this function table.
604  *
605  * \note If the ABI for this table changes, the module version
606  * (\ref VM_GREETER_MODULE_VERSION) should be incremented.
607  */
608  unsigned int module_version;
609  /*! \brief The name of the module that provides the voicemail greeter functionality */
610  const char *module_name;
611  /*! \brief The module for the voicemail greeter provider */
613 
614  ast_sayname_fn *sayname;
615 };
616 
617 /*!
618  * \brief Determine if a voicemail greeter provider is registered.
619  * \since 13.0.0
620  *
621  * \retval 0 if no provider registered.
622  * \retval 1 if a provider is registered.
623  */
625 
626 /*!
627  * \brief Set voicemail greeter function callbacks
628  * \since 13.0.0
629  *
630  * \param vm_table Voicemail greeter function table to install.
631  * \param module Pointer to the module implementing the interface
632  *
633  * \retval 0 on success.
634  * \retval -1 on error.
635  * \retval AST_MODULE_LOAD_DECLINE if there's already another greeter registered.
636  */
637 int __ast_vm_greeter_register(const struct ast_vm_greeter_functions *vm_table, struct ast_module *module);
638 
639 /*! \brief See \ref __ast_vm_greeter_register() */
640 #define ast_vm_greeter_register(vm_table) __ast_vm_greeter_register(vm_table, AST_MODULE_SELF)
641 
642 /*!
643  * \brief Unregister the specified voicemail greeter provider
644  * \since 13.0.0
645  *
646  * \param module_name The module name of the provider to unregister
647  */
648 void ast_vm_greeter_unregister(const char *module_name);
649 
650 #ifdef TEST_FRAMEWORK
651 typedef int (ast_vm_test_create_user_fn)(const char *context, const char *user);
652 typedef int (ast_vm_test_destroy_user_fn)(const char *context, const char *user);
653 
654 void ast_install_vm_test_functions(ast_vm_test_create_user_fn *vm_test_create_user_func,
655  ast_vm_test_destroy_user_fn *vm_test_destroy_user_func);
656 
657 void ast_uninstall_vm_test_functions(void);
658 #endif
659 
660 /*!
661  * \brief
662  * param[in] vm_rec_data Contains data needed to make the recording.
663  * retval 0 voicemail successfully created from recording.
664  * retval -1 Failure
665  */
666 int ast_app_copy_recording_to_vm(struct ast_vm_recording_data *vm_rec_data);
667 
668 /*!
669  * \brief Determine if a given mailbox has any voicemail
670  * If folder is NULL, defaults to "INBOX". If folder is "INBOX", includes the
671  * number of messages in the "Urgent" folder.
672  * \retval 1 Mailbox has voicemail
673  * \retval 0 No new voicemail in specified mailbox
674  * \retval -1 Failure
675  * \since 1.0
676  */
677 int ast_app_has_voicemail(const char *mailboxes, const char *folder);
678 
679 /*!
680  * \brief Determine number of new/old messages in a mailbox
681  * \since 1.0
682  * \param[in] mailboxes Mailbox specification in the format
683  * /code
684  * mbox[\@context][&mbox2[\@context2]][...]
685  * /code
686  * \param[out] newmsgs Number of messages in the "INBOX" folder. Includes number of messages in the "Urgent" folder, if any.
687  * \param[out] oldmsgs Number of messages in the "Old" folder.
688  * \retval 0 Success
689  * \retval -1 Failure
690  */
691 int ast_app_inboxcount(const char *mailboxes, int *newmsgs, int *oldmsgs);
692 
693 /*!
694  * \brief Determine number of urgent/new/old messages in a mailbox
695  * \param[in] mailboxes the mailbox context to use
696  * \param[out] urgentmsgs the urgent message count
697  * \param[out] newmsgs the new message count
698  * \param[out] oldmsgs the old message count
699  * \retval 0 for success
700  * \retval negative upon error
701  * \since 1.6.1
702  */
703 int ast_app_inboxcount2(const char *mailboxes, int *urgentmsgs, int *newmsgs, int *oldmsgs);
704 
705 /*!
706  * \brief Play a recorded user name for the mailbox to the specified channel.
707  *
708  * \param chan Where to play the recorded name file.
709  * \param mailbox_id The mailbox name.
710  *
711  * \retval 0 Name played without interruption
712  * \retval dtmf ASCII value of the DTMF which interrupted playback.
713  * \retval -1 Unable to locate mailbox or hangup occurred.
714  */
715 int ast_app_sayname(struct ast_channel *chan, const char *mailbox_id);
716 
717 /*!
718  * \brief Get the number of messages in a given mailbox folder
719  *
720  * \param[in] mailbox_id Mailbox name
721  * \param[in] folder The folder to look in. Default is INBOX if not provided.
722  *
723  * \note If requesting INBOX then the returned count is INBOX + Urgent.
724  *
725  * \return The number of messages in the mailbox folder (zero or more).
726  */
727 int ast_app_messagecount(const char *mailbox_id, const char *folder);
728 
729 /*!
730  * \brief Return name of folder, given an id
731  * \param[in] id Folder id
732  * \return Name of folder
733  */
734 const char *ast_vm_index_to_foldername(int id);
735 
736 /*!
737  * \brief Create a snapshot of a mailbox which contains information about every msg.
738  *
739  * \param mailbox the mailbox to look for
740  * \param context the context to look for the mailbox in
741  * \param folder OPTIONAL. When not NULL only msgs from the specified folder will be included.
742  * \param descending list the msgs in descending order rather than ascending order.
743  * \param sort_val What to sort in the snapshot.
744  * \param combine_INBOX_and_OLD When this argument is set, The OLD folder will be represented
745  * in the INBOX folder of the snapshot. This allows the snapshot to represent the
746  * OLD and INBOX messages in sorted order merged together.
747  *
748  * \return snapshot on success
749  * \retval NULL on failure
750  */
751 struct ast_vm_mailbox_snapshot *ast_vm_mailbox_snapshot_create(const char *mailbox,
752  const char *context,
753  const char *folder,
754  int descending,
755  enum ast_vm_snapshot_sort_val sort_val,
756  int combine_INBOX_and_OLD);
757 
758 /*!
759  * \brief destroy a snapshot
760  *
761  * \param mailbox_snapshot The snapshot to destroy.
762  * \retval NULL
763  */
765 
766 /*!
767  * \brief Move messages from one folder to another
768  *
769  * \param mailbox The mailbox to which the folders belong
770  * \param context The voicemail context for the mailbox
771  * \param num_msgs The number of messages to move
772  * \param oldfolder The folder from where messages should be moved
773  * \param old_msg_ids The message IDs of the messages to move
774  * \param newfolder The folder to which messages should be moved
775  * new folder. This array must be num_msgs sized.
776  *
777  * \retval -1 Failure
778  * \retval 0 Success
779  */
780 int ast_vm_msg_move(const char *mailbox,
781  const char *context,
782  size_t num_msgs,
783  const char *oldfolder,
784  const char *old_msg_ids[],
785  const char *newfolder);
786 
787 /*!
788  * \brief Remove/delete messages from a mailbox folder.
789  *
790  * \param mailbox The mailbox from which to delete messages
791  * \param context The voicemail context for the mailbox
792  * \param num_msgs The number of messages to delete
793  * \param folder The folder from which to remove messages
794  * \param msgs The message IDs of the messages to delete
795  *
796  * \retval -1 Failure
797  * \retval 0 Success
798  */
799 int ast_vm_msg_remove(const char *mailbox,
800  const char *context,
801  size_t num_msgs,
802  const char *folder,
803  const char *msgs[]);
804 
805 /*!
806  * \brief forward a message from one mailbox to another.
807  *
808  * \brief from_mailbox The original mailbox the message is being forwarded from
809  * \brief from_context The voicemail context of the from_mailbox
810  * \brief from_folder The folder from which the message is being forwarded
811  * \brief to_mailbox The mailbox to forward the message to
812  * \brief to_context The voicemail context of the to_mailbox
813  * \brief to_folder The folder to which the message is being forwarded
814  * \brief num_msgs The number of messages being forwarded
815  * \brief msg_ids The message IDs of the messages in from_mailbox to forward
816  * \brief delete_old If non-zero, the forwarded messages are also deleted from from_mailbox.
817  * Otherwise, the messages will remain in the from_mailbox.
818  *
819  * \retval -1 Failure
820  * \retval 0 Success
821  */
822 int ast_vm_msg_forward(const char *from_mailbox,
823  const char *from_context,
824  const char *from_folder,
825  const char *to_mailbox,
826  const char *to_context,
827  const char *to_folder,
828  size_t num_msgs,
829  const char *msg_ids[],
830  int delete_old);
831 
832 /*!
833  * \brief Play a voicemail msg back on a channel.
834  *
835  * \param chan
836  * \param mailbox msg is in.
837  * \param context of mailbox.
838  * \param folder voicemail folder to look in.
839  * \param msg_num message number in the voicemailbox to playback to the channel.
840  * \param cb
841  *
842  * \retval 0 success
843  * \retval -1 failure
844  */
845 int ast_vm_msg_play(struct ast_channel *chan,
846  const char *mailbox,
847  const char *context,
848  const char *folder,
849  const char *msg_num,
850  ast_vm_msg_play_cb *cb);
851 
852 #ifdef TEST_FRAMEWORK
853 int ast_vm_test_destroy_user(const char *context, const char *mailbox);
854 int ast_vm_test_create_user(const char *context, const char *mailbox);
855 #endif
856 
857 /*!
858  * \brief Safely spawn an external program while closing file descriptors
859  *
860  * \note This replaces the \b execvp call in all Asterisk modules
861  *
862  * \param dualfork Non-zero to simulate running the program in the
863  * background by forking twice. The option provides similar
864  * functionality to the '&' in the OS shell command "cmd &". The
865  * option allows Asterisk to run a reaper loop to watch the first fork
866  * which immediately exits after spaning the second fork. The actual
867  * program is run in the second fork.
868  * \param file execvp(file, argv) file parameter
869  * \param argv execvp(file, argv) argv parameter
870  */
871 int ast_safe_execvp(int dualfork, const char *file, char *const argv[]);
872 
873 /*!
874  * \brief Safely spawn an OS shell command while closing file descriptors
875  *
876  * \note This replaces the \b system call in all Asterisk modules
877  *
878  * \param s - OS shell command string to execute.
879  *
880  * \warning Command injection can happen using this call if the passed
881  * in string is created using untrusted data from an external source.
882  * It is best not to use untrusted data. However, the caller could
883  * filter out dangerous characters to avoid command injection.
884  */
885 int ast_safe_system(const char *s);
886 
887 /*!
888  * \brief Replace the SIGCHLD handler
889  *
890  * Normally, Asterisk has a SIGCHLD handler that is cleaning up all zombie
891  * processes from forking elsewhere in Asterisk. However, if you want to
892  * wait*() on the process to retrieve information about it's exit status,
893  * then this signal handler needs to be temporarily replaced.
894  *
895  * Code that executes this function *must* call ast_unreplace_sigchld()
896  * after it is finished doing the wait*().
897  */
898 void ast_replace_sigchld(void);
899 
900 /*!
901  * \brief Restore the SIGCHLD handler
902  *
903  * This function is called after a call to ast_replace_sigchld. It restores
904  * the SIGCHLD handler that cleans up any zombie processes.
905  */
906 void ast_unreplace_sigchld(void);
907 
908 /*!
909  * \brief Send a string of SF digits to a channel
910  *
911  * \param chan The channel that will receive the SF digits
912  * \param peer (optional) Peer channel that will be autoserviced while the
913  * primary channel is receiving SF
914  * \param chan2 A second channel that will simultaneously receive SF digits.
915  * This option may only be used if is_external is 0.
916  * \param digits This is a string of characters representing the SF digits
917  * to be sent to the channel. Valid characters are
918  * "0123456789". Note: You can pass arguments 'f' or
919  * 'F', if you want to Flash the channel (if supported by the
920  * channel), or 'w' or 'W' to add a wink (if supported by the
921  * channel).
922  * \param frequency The frequency to use for signaling. 0 can be specified for
923  * the default, which is 2600 Hz.
924  * \param is_external 1 if called by a thread that is not the channel's media
925  * handler thread, 0 if called by the channel's media handler
926  * thread.
927  *
928  * \retval 0 on success.
929  * \retval -1 on failure or a channel hung up.
930  */
931 int ast_sf_stream(struct ast_channel *chan, struct ast_channel *peer, struct ast_channel *chan2, const char *digits, int frequency, int is_external);
932 
933 /*!
934  * \brief Send a string of MF digits to a channel
935  *
936  * \param chan The channel that will receive the MF digits.
937  * \param peer (optional) Peer channel that will be autoserviced while the
938  * primary channel is receiving MF
939  * \param chan2 A second channel that will simultaneously receive MF digits.
940  * This option may only be used if is_external is 0.
941  * \param digits This is a string of characters representing the MF digits
942  * to be sent to the channel. Valid characters are
943  * "0123456789*#abcdABCD". Note: You can pass arguments 'f' or
944  * 'F', if you want to Flash the channel (if supported by the
945  * channel), or 'w' or 'W' to add a wink (if supported by the
946  * channel).
947  * \param between This is the number of milliseconds to wait in between each
948  * MF digit. If zero milliseconds is specified, then the
949  * default value of 50 will be used.
950  * \param duration This is the duration that each numeric MF digit should have.
951  * Default value is 55.
952  * \param durationkp This is the duration that each KP digit should have. Default
953  * is 120.
954  * \param durationst This is the duration that each ST, STP, ST2P, or ST3P digit
955  * should have. Default is 65.
956  * \param is_external 1 if called by a thread that is not the channel's media
957  * handler thread, 0 if called by the channel's media handler
958  * thread.
959  *
960  * \retval 0 on success.
961  * \retval -1 on failure or a channel hung up.
962  */
963 int ast_mf_stream(struct ast_channel *chan, struct ast_channel *peer, struct ast_channel *chan2, const char *digits,
964  int between, unsigned int duration, unsigned int durationkp, unsigned int durationst, int is_external);
965 
966 /*!
967  * \brief Send a string of DTMF digits to a channel
968  *
969  * \param chan The channel that will receive the DTMF frames
970  * \param peer (optional) Peer channel that will be autoserviced while the
971  * primary channel is receiving DTMF
972  * \param digits This is a string of characters representing the DTMF digits
973  * to be sent to the channel. Valid characters are
974  * "0123456789*#abcdABCD". Note: You can pass arguments 'f' or
975  * 'F', if you want to Flash the channel (if supported by the
976  * channel), or 'w' to add a 500 millisecond pause to the DTMF
977  * sequence.
978  * \param between This is the number of milliseconds to wait in between each
979  * DTMF digit. If zero milliseconds is specified, then the
980  * default value of 100 will be used.
981  * \param duration This is the duration that each DTMF digit should have.
982  *
983  * \pre This must only be called by the channel's media handler thread.
984  *
985  * \retval 0 on success.
986  * \retval -1 on failure or a channel hung up.
987  */
988 int ast_dtmf_stream(struct ast_channel *chan, struct ast_channel *peer, const char *digits, int between, unsigned int duration);
989 
990 /*!
991  * \brief Send a string of DTMF digits to a channel from an external thread.
992  *
993  * \param chan The channel that will receive the DTMF frames
994  * \param digits This is a string of characters representing the DTMF digits
995  * to be sent to the channel. Valid characters are
996  * "0123456789*#abcdABCD". Note: You can pass arguments 'f' or
997  * 'F', if you want to Flash the channel (if supported by the
998  * channel), or 'w' to add a 500 millisecond pause to the DTMF
999  * sequence.
1000  * \param between This is the number of milliseconds to wait in between each
1001  * DTMF digit. If zero milliseconds is specified, then the
1002  * default value of 100 will be used.
1003  * \param duration This is the duration that each DTMF digit should have.
1004  *
1005  * \pre This must only be called by threads that are not the channel's
1006  * media handler thread.
1007  */
1008 void ast_dtmf_stream_external(struct ast_channel *chan, const char *digits, int between, unsigned int duration);
1009 
1010 /*! \brief Stream a filename (or file descriptor) as a generator. */
1011 int ast_linear_stream(struct ast_channel *chan, const char *filename, int fd, int allowoverride);
1012 
1013 /*!
1014  * \brief Stream a file with fast forward, pause, reverse, restart.
1015  * \param chan Channel
1016  * \param file File to play.
1017  * \param fwd, rev, stop, pause, restart DTMF keys for media control
1018  * \param skipms Number of milliseconds to skip for fwd/rev.
1019  * \param offsetms Number of milliseconds to skip when starting the media.
1020  *
1021  * Before calling this function, set this to be the number
1022  * of ms to start from the beginning of the file. When the function
1023  * returns, it will be the number of ms from the beginning where the
1024  * playback stopped. Pass NULL if you don't care.
1025  *
1026  * \retval 0 on success
1027  * \retval Non-zero on failure
1028  */
1029 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);
1030 
1031 /*!
1032  * \brief Version of ast_control_streamfile() which allows the language of the
1033  * media file to be specified.
1034  *
1035  * \retval 0 on success
1036  * \retval Non-zero on failure
1037  */
1038 int ast_control_streamfile_lang(struct ast_channel *chan, const char *file,
1039  const char *fwd, const char *rev, const char *stop, const char *suspend,
1040  const char *restart, int skipms, const char *lang, long *offsetms);
1041 
1042 /*!
1043  * \brief Controls playback of a tone
1044  *
1045  * \retval 0 on success
1046  * \retval Non-zero on failure
1047  */
1048 int ast_control_tone(struct ast_channel *chan, const char *tone);
1049 
1050 /*!
1051  * \brief Stream a file with fast forward, pause, reverse, restart.
1052  * \param chan
1053  * \param file filename
1054  * \param fwd, rev, stop, pause, restart, skipms, offsetms
1055  * \param cb waitstream callback to invoke when fastforward or rewind occurs.
1056  *
1057  * Before calling this function, set this to be the number
1058  * of ms to start from the beginning of the file. When the function
1059  * returns, it will be the number of ms from the beginning where the
1060  * playback stopped. Pass NULL if you don't care.
1061  */
1062 int ast_control_streamfile_w_cb(struct ast_channel *chan,
1063  const char *file,
1064  const char *fwd,
1065  const char *rev,
1066  const char *stop,
1067  const char *pause,
1068  const char *restart,
1069  int skipms,
1070  long *offsetms,
1072 
1073 /*! \brief Play a stream and wait for a digit, returning the digit that was pressed */
1074 int ast_play_and_wait(struct ast_channel *chan, const char *fn);
1075 
1076 /*!
1077  * Possible actions to take if a recording already exists
1078  * \since 12
1079  */
1081  /*! Return an Error State for IF_Exists */
1083  /*! Fail the recording. */
1085  /*! Overwrite the existing recording. */
1087  /*! Append to the existing recording. */
1089 };
1090 
1091 /*!
1092  * \brief Record a file based on input from a channel
1093  * This function will play "auth-thankyou" upon successful recording if
1094  * skip_confirmation_sound is false.
1095  *
1096  * \param chan the channel being recorded
1097  * \param playfile Filename of sound to play before recording begins. A beep is also played when playfile completes, before the recording begins.
1098  * \param recordfile Filename to save the recording
1099  * \param maxtime_sec Longest possible message length in seconds
1100  * \param fmt string containing all formats to be recorded delimited by '|'
1101  * \param duration pointer to integer for storing length of the recording
1102  * \param beep If true, play a beep before recording begins (and doesn't play \a playfile)
1103  * \param sound_duration pointer to integer for storing length of the recording minus all silence
1104  * \param silencethreshold tolerance of noise levels that can be considered silence for the purpose of silence timeout, -1 for default
1105  * \param maxsilence_ms Length of time in milliseconds which will trigger a timeout from silence, -1 for default
1106  * \param path Optional filesystem path to unlock
1107  * \param acceptdtmf Character of DTMF to end and accept the recording
1108  * \param canceldtmf Character of DTMF to end and cancel the recording
1109  * \param skip_confirmation_sound If true, don't play auth-thankyou at end. Nice for custom recording prompts in apps.
1110  * \param if_exists Action to take if recording already exists.
1111  *
1112  * \retval -1 failure or hangup
1113  * \retval 'S' Recording ended from silence timeout
1114  * \retval 't' Recording ended from the message exceeding the maximum duration
1115  * \retval dtmfchar Recording ended via the return value's DTMF character for either cancel or accept.
1116  */
1117 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 beep, int silencethreshold, int maxsilence_ms, const char *path, const char *acceptdtmf, const char *canceldtmf, int skip_confirmation_sound, enum ast_record_if_exists if_exists);
1118 
1119 /*!
1120  * \brief Record a file based on input from a channel. Use default accept and cancel DTMF.
1121  * This function will play "auth-thankyou" upon successful recording.
1122  *
1123  * \param chan the channel being recorded
1124  * \param playfile Filename of sound to play before recording begins
1125  * \param recordfile Filename to save the recording
1126  * \param maxtime_sec Longest possible message length in seconds
1127  * \param fmt string containing all formats to be recorded delimited by '|'
1128  * \param duration pointer to integer for storing length of the recording
1129  * \param sound_duration pointer to integer for storing length of the recording minus all silence
1130  * \param silencethreshold tolerance of noise levels that can be considered silence for the purpose of silence timeout, -1 for default
1131  * \param maxsilence_ms length of time in milliseconds which will trigger a timeout from silence, -1 for default
1132  * \param path Optional filesystem path to unlock
1133  *
1134  * \retval -1 failure or hangup
1135  * \retval 'S' Recording ended from silence timeout
1136  * \retval 't' Recording ended from the message exceeding the maximum duration
1137  * \retval dtmfchar Recording ended via the return value's DTMF character for either cancel or accept.
1138  */
1139 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);
1140 
1141 /*!
1142  * \brief Record a file based on input frm a channel. Recording is performed in 'prepend' mode which works a little differently from normal recordings
1143  * This function will not play a success message due to post-recording control in the application this was added for.
1144  *
1145  * \param chan the channel being recorded
1146  * \param playfile Filename of sound to play before recording begins
1147  * \param recordfile Filename to save the recording
1148  * \param maxtime_sec Longest possible message length in seconds
1149  * \param fmt string containing all formats to be recorded delimited by '|'
1150  * \param duration pointer to integer for storing length of the recording
1151  * \param sound_duration pointer to integer for storing length of the recording minus all silence
1152  * \param beep whether to play a beep to prompt the recording
1153  * \param silencethreshold tolerance of noise levels that can be considered silence for the purpose of silence timeout, -1 for default
1154  * \param maxsilence_ms length of time in milliseconds which will trigger a timeout from silence, -1 for default.
1155  *
1156  * \retval -1 failure or hangup
1157  * \retval 'S' Recording ended from silence timeout
1158  * \retval 't' Recording either exceeded maximum duration or the call was ended via DTMF
1159  */
1160 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);
1161 
1162 enum AST_LOCK_RESULT {
1163  AST_LOCK_SUCCESS = 0,
1164  AST_LOCK_TIMEOUT = -1,
1165  AST_LOCK_PATH_NOT_FOUND = -2,
1166  AST_LOCK_FAILURE = -3,
1167 };
1168 
1169 /*! \brief Type of locking to use in ast_lock_path / ast_unlock_path */
1171  AST_LOCK_TYPE_LOCKFILE = 0,
1172  AST_LOCK_TYPE_FLOCK = 1,
1173 };
1174 
1175 /*!
1176  * \brief Set the type of locks used by ast_lock_path()
1177  * \param type the locking type to use
1178  */
1179 void ast_set_lock_type(enum AST_LOCK_TYPE type);
1180 
1181 /*!
1182  * \brief Lock a filesystem path.
1183  * \param path the path to be locked
1184  * \return one of \ref AST_LOCK_RESULT values
1185  */
1186 enum AST_LOCK_RESULT ast_lock_path(const char *path);
1187 
1188 /*! \brief Unlock a path */
1189 int ast_unlock_path(const char *path);
1190 
1191 /*! \brief Read a file into asterisk*/
1192 char *ast_read_textfile(const char *file);
1193 
1194 struct ast_group_info;
1195 
1196 /*! \brief Split a group string into group and category, returning a default category if none is provided. */
1197 int ast_app_group_split_group(const char *data, char *group, int group_max, char *category, int category_max);
1198 
1199 /*! \brief Set the group for a channel, splitting the provided data into group and category, if specified. */
1200 int ast_app_group_set_channel(struct ast_channel *chan, const char *data);
1201 
1202 /*! \brief Get the current channel count of the specified group and category. */
1203 int ast_app_group_get_count(const char *group, const char *category);
1204 
1205 /*! \brief Get the current channel count of all groups that match the specified pattern and category. */
1206 int ast_app_group_match_get_count(const char *groupmatch, const char *category);
1207 
1208 /*! \brief Discard all group counting for a channel */
1209 int ast_app_group_discard(struct ast_channel *chan);
1210 
1211 /*! \brief Update all group counting for a channel to a new one */
1212 int ast_app_group_update(struct ast_channel *oldchan, struct ast_channel *newchan);
1213 
1214 /*! \brief Write Lock the group count list */
1215 int ast_app_group_list_wrlock(void);
1216 
1217 /*! \brief Read Lock the group count list */
1218 int ast_app_group_list_rdlock(void);
1219 
1220 /*! \brief Get the head of the group count list */
1222 
1223 /*! \brief Unlock the group count list */
1224 int ast_app_group_list_unlock(void);
1225 
1226 /*!
1227  \brief Define an application argument
1228  \param name The name of the argument
1229 */
1230 #define AST_APP_ARG(name) char *name
1231 
1232 /*!
1233  \brief Declare a structure to hold an application's arguments.
1234  \param name The name of the structure
1235  \param arglist The list of arguments, defined using AST_APP_ARG
1236 
1237  This macro declares a structure intended to be used in a call
1238  to ast_app_separate_args(). The structure includes all the
1239  arguments specified, plus an argv array that overlays them and an
1240  argc argument counter. The arguments must be declared using AST_APP_ARG,
1241  and they will all be character pointers (strings).
1242 
1243  \note The structure is <b>not</b> initialized, as the call to
1244  ast_app_separate_args() will perform that function before parsing
1245  the arguments.
1246  */
1247 #define AST_DECLARE_APP_ARGS(name, arglist) AST_DEFINE_APP_ARGS_TYPE(argtype_##name, arglist) name = { 0, }
1248 
1249 /*!
1250  \brief Define a structure type to hold an application's arguments.
1251  \param type The name of the structure type
1252  \param arglist The list of arguments, defined using AST_APP_ARG
1253 
1254  This macro defines a structure type intended to be used in a call
1255  to ast_app_separate_args(). The structure includes all the
1256  arguments specified, plus an argv array that overlays them and an
1257  argc argument counter. The arguments must be declared using AST_APP_ARG,
1258  and they will all be character pointers (strings).
1259 
1260  \note This defines a structure type, but does not declare an instance
1261  of the structure. That must be done separately.
1262  */
1263 
1264 #define AST_DEFINE_APP_ARGS_TYPE(type, arglist) \
1265  struct __subtype_##type { arglist }; \
1266  struct type { \
1267  unsigned int argc; \
1268  union { \
1269  char *argv[sizeof(struct __subtype_##type) / sizeof(char*)]; \
1270  struct { arglist }; \
1271  }; \
1272  }
1273 
1274 /*!
1275  \brief Performs the 'standard' argument separation process for an application.
1276  \param args An argument structure defined using AST_DECLARE_APP_ARGS
1277  \param parse A modifiable buffer containing the input to be parsed
1278 
1279  This function will separate the input string using the standard argument
1280  separator character ',' and fill in the provided structure, including
1281  the argc argument counter field.
1282  */
1283 #define AST_STANDARD_APP_ARGS(args, parse) \
1284  args.argc = __ast_app_separate_args(parse, ',', 1, args.argv, ((sizeof(args) - offsetof(typeof(args), argv)) / sizeof(args.argv[0])))
1285 #define AST_STANDARD_RAW_ARGS(args, parse) \
1286  args.argc = __ast_app_separate_args(parse, ',', 0, args.argv, ((sizeof(args) - offsetof(typeof(args), argv)) / sizeof(args.argv[0])))
1287 
1288 /*!
1289  \brief Performs the 'nonstandard' argument separation process for an application.
1290  \param args An argument structure defined using AST_DECLARE_APP_ARGS
1291  \param parse A modifiable buffer containing the input to be parsed
1292  \param sep A nonstandard separator character
1293 
1294  This function will separate the input string using the nonstandard argument
1295  separator character and fill in the provided structure, including
1296  the argc argument counter field.
1297  */
1298 #define AST_NONSTANDARD_APP_ARGS(args, parse, sep) \
1299  args.argc = __ast_app_separate_args(parse, sep, 1, args.argv, ((sizeof(args) - offsetof(typeof(args), argv)) / sizeof(args.argv[0])))
1300 #define AST_NONSTANDARD_RAW_ARGS(args, parse, sep) \
1301  args.argc = __ast_app_separate_args(parse, sep, 0, args.argv, ((sizeof(args) - offsetof(typeof(args), argv)) / sizeof(args.argv[0])))
1302 
1303 /*!
1304  \brief Separate a string into arguments in an array
1305  \param buf The string to be parsed (this must be a writable copy, as it will be modified)
1306  \param delim The character to be used to delimit arguments
1307  \param remove_chars Remove backslashes and quote characters, while parsing
1308  \param array An array of 'char *' to be filled in with pointers to the found arguments
1309  \param arraylen The number of elements in the array (i.e. the number of arguments you will accept)
1310 
1311  Note: if there are more arguments in the string than the array will hold, the last element of
1312  the array will contain the remaining arguments, not separated.
1313 
1314  The array will be completely zeroed by this function before it populates any entries.
1315 
1316  \return The number of arguments found, or zero if the function arguments are not valid.
1317 */
1318 unsigned int __ast_app_separate_args(char *buf, char delim, int remove_chars, char **array, int arraylen);
1319 #define ast_app_separate_args(a,b,c,d) __ast_app_separate_args(a,b,1,c,d)
1320 
1321 /*!
1322  \brief A structure to hold the description of an application 'option'.
1323 
1324  Application 'options' are single-character flags that can be supplied
1325  to the application to affect its behavior; they can also optionally
1326  accept arguments enclosed in parenthesis.
1327 
1328  These structures are used by the ast_app_parse_options function, uses
1329  this data to fill in a flags structure (to indicate which options were
1330  supplied) and array of argument pointers (for those options that had
1331  arguments supplied).
1332  */
1334  /*! \brief The flag bit that represents this option. */
1335  uint64_t flag;
1336  /*! \brief The index of the entry in the arguments array
1337  that should be used for this option's argument. */
1338  unsigned int arg_index;
1339 };
1340 
1341 #define BEGIN_OPTIONS {
1342 #define END_OPTIONS }
1343 
1344 /*!
1345  \brief Declares an array of options for an application.
1346  \param holder The name of the array to be created
1347  \param options The actual options to be placed into the array
1348  \sa ast_app_parse_options
1349 
1350  This macro declares a 'static const' array of \c struct \c ast_option
1351  elements to hold the list of available options for an application.
1352  Each option must be declared using either the AST_APP_OPTION()
1353  or AST_APP_OPTION_ARG() macros.
1354 
1355  Example usage:
1356  \code
1357  enum my_app_option_flags {
1358  OPT_JUMP = (1 << 0),
1359  OPT_BLAH = (1 << 1),
1360  OPT_BLORT = (1 << 2),
1361  };
1362 
1363  enum my_app_option_args {
1364  OPT_ARG_BLAH = 0,
1365  OPT_ARG_BLORT,
1366  !! this entry tells how many possible arguments there are,
1367  and must be the last entry in the list
1368  OPT_ARG_ARRAY_SIZE,
1369  };
1370 
1371  AST_APP_OPTIONS(my_app_options, {
1372  AST_APP_OPTION('j', OPT_JUMP),
1373  AST_APP_OPTION_ARG('b', OPT_BLAH, OPT_ARG_BLAH),
1374  AST_APP_OPTION_BLORT('B', OPT_BLORT, OPT_ARG_BLORT),
1375  });
1376 
1377  static int my_app_exec(struct ast_channel *chan, void *data)
1378  {
1379  char *options;
1380  struct ast_flags opts = { 0, };
1381  char *opt_args[OPT_ARG_ARRAY_SIZE];
1382 
1383  ... do any argument parsing here ...
1384 
1385  if (ast_app_parse_options(my_app_options, &opts, opt_args, options)) {
1386  return -1;
1387  }
1388  }
1389  \endcode
1390  */
1391 #define AST_APP_OPTIONS(holder, options...) \
1392  static const struct ast_app_option holder[128] = options
1393 
1394 /*!
1395  \brief Declares an application option that does not accept an argument.
1396  \param option The single character representing the option
1397  \param flagno The flag index to be set if this option is present
1398  \sa AST_APP_OPTIONS, ast_app_parse_options
1399  */
1400 #define AST_APP_OPTION(option, flagno) \
1401  [option] = { .flag = flagno }
1402 
1403 /*!
1404  \brief Declares an application option that accepts an argument.
1405  \param option The single character representing the option
1406  \param flagno The flag index to be set if this option is present
1407  \param argno The index into the argument array where the argument should
1408  be placed
1409  \sa AST_APP_OPTIONS, ast_app_parse_options
1410  */
1411 #define AST_APP_OPTION_ARG(option, flagno, argno) \
1412  [option] = { .flag = flagno, .arg_index = argno + 1 }
1413 
1414 /*!
1415  \brief Parses a string containing application options and sets flags/arguments.
1416  \param options The array of possible options declared with AST_APP_OPTIONS
1417  \param flags The flag structure to have option flags set
1418  \param args The array of argument pointers to hold arguments found
1419  \param optstr The string containing the options to be parsed
1420  \retval zero for success
1421  \retval non-zero if an error occurs
1422  \sa AST_APP_OPTIONS
1423  */
1424 int ast_app_parse_options(const struct ast_app_option *options, struct ast_flags *flags, char **args, char *optstr);
1425 
1426  /*!
1427  \brief Parses a string containing application options and sets flags/arguments.
1428  \param options The array of possible options declared with AST_APP_OPTIONS
1429  \param flags The 64-bit flag structure to have option flags set
1430  \param args The array of argument pointers to hold arguments found
1431  \param optstr The string containing the options to be parsed
1432  \retval zero for success
1433  \retval non-zero if an error occurs
1434  \sa AST_APP_OPTIONS
1435  */
1436 int ast_app_parse_options64(const struct ast_app_option *options, struct ast_flags64 *flags, char **args, char *optstr);
1437 
1438 /*! \brief Given a list of options array, return an option string based on passed flags
1439  \param options The array of possible options declared with AST_APP_OPTIONS
1440  \param flags The flags of the options that you wish to populate the buffer with
1441  \param buf The buffer to fill with the string of options
1442  \param len The maximum length of buf
1443 */
1444 void ast_app_options2str64(const struct ast_app_option *options, struct ast_flags64 *flags, char *buf, size_t len);
1445 
1446 /*! \brief Present a dialtone and collect a certain length extension.
1447  \retval 1 if extension exists
1448  \retval 0 if extension does not exist
1449  \retval -1 on hangup
1450 \note Note that if 'collect' holds digits already, new digits will be appended, so be sure it's initialized properly */
1451 int ast_app_dtget(struct ast_channel *chan, const char *context, char *collect, size_t size, int maxlen, int timeout);
1452 
1453 /*! \brief Allow to record message and have a review option */
1454 int ast_record_review(struct ast_channel *chan, const char *playfile, const char *recordfile, int maxtime, const char *fmt, int *duration, const char *path);
1455 
1456 /*!
1457  * \brief Decode an encoded control or extended ASCII character
1458  * \param[in] stream String to decode
1459  * \param[out] result Decoded character
1460  * \param[out] consumed Number of characters used in stream to encode the character
1461  * \retval -1 Stream is of zero length
1462  * \retval 0 Success
1463  */
1464 int ast_get_encoded_char(const char *stream, char *result, size_t *consumed);
1465 
1466 /*!
1467  * \brief Decode a stream of encoded control or extended ASCII characters
1468  * \param[in] stream Encoded string
1469  * \param[out] result Decoded string
1470  * \param[in] result_len Maximum size of the result buffer
1471  * \return A pointer to the result string
1472  */
1473 char *ast_get_encoded_str(const char *stream, char *result, size_t result_len);
1474 
1475 /*! \brief Decode a stream of encoded control or extended ASCII characters */
1476 int ast_str_get_encoded_str(struct ast_str **str, int maxlen, const char *stream);
1477 
1478 /*!
1479  * \brief Common routine for child processes, to close all fds prior to exec(2)
1480  * \param[in] n starting file descriptor number for closing all higher file descriptors
1481  * \since 1.6.1
1482  */
1483 void ast_close_fds_above_n(int n);
1484 
1485 /*!
1486  * \brief Common routine to safely fork without a chance of a signal handler firing badly in the child
1487  * \param[in] stop_reaper flag to determine if sigchld handler is replaced or not
1488  * \since 1.6.1
1489  */
1490 int ast_safe_fork(int stop_reaper);
1491 
1492 /*!
1493  * \brief Common routine to cleanup after fork'ed process is complete (if reaping was stopped)
1494  * \since 1.6.1
1495  */
1496 void ast_safe_fork_cleanup(void);
1497 
1498 /*!
1499  * \brief Common routine to parse time lengths, with optional time unit specifier
1500  * \param[in] timestr String to parse
1501  * \param[in] defunit Default unit type
1502  * \param[out] result Resulting value, specified in milliseconds
1503  * \retval 0 Success
1504  * \retval -1 Failure
1505  * \since 1.8
1506  */
1507 int ast_app_parse_timelen(const char *timestr, int *result, enum ast_timelen defunit);
1508 
1509 /*!
1510  * \brief Get the \ref stasis topic for queue messages
1511  * \return The topic structure for queue messages
1512  * \retval NULL if it has not been allocated
1513  * \since 12
1514  */
1515 struct stasis_topic *ast_queue_topic_all(void);
1516 
1517 /*!
1518  * \brief Get the \ref stasis topic for queue messages for a particular queue name
1519  * \param queuename The name for which to get the topic
1520  * \return The topic structure for queue messages for a given name
1521  * \retval NULL if it failed to be found or allocated
1522  * \since 12
1523  */
1524 struct stasis_topic *ast_queue_topic(const char *queuename);
1525 
1526 /*!
1527  * \brief Initialize the application core
1528  * \retval 0 Success
1529  * \retval -1 Failure
1530  * \since 12
1531  */
1532 int app_init(void);
1533 
1534 #if defined(__cplusplus) || defined(c_plusplus)
1535 }
1536 #endif
1537 
1538 #endif /* _ASTERISK_APP_H */
void ast_install_stack_functions(const struct ast_app_stack_funcs *funcs)
Set stack application function callbacks.
Definition: main/app.c:273
unsigned int module_version
The version of this function table.
int ast_vm_is_registered(void)
Determine if a voicemail provider is registered.
Definition: main/app.c:357
int ast_vm_greeter_is_registered(void)
Determine if a voicemail greeter provider is registered.
Definition: main/app.c:468
int ast_dtmf_stream(struct ast_channel *chan, struct ast_channel *peer, const char *digits, int between, unsigned int duration)
Send a string of DTMF digits to a channel.
Definition: main/app.c:1127
Main Channel structure associated with a channel.
channel group info
Definition: channel.h:2915
enum ast_getdata_result 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: main/app.c:188
struct ast_module * module
The module for the voicemail provider.
void( ast_waitstream_fr_cb)(struct ast_channel *chan, long ms, enum ast_waitstream_fr_cb_values val)
callback used during dtmf controlled file playback to indicate location of playback in a file after r...
Definition: file.h:65
int __ast_vm_register(const struct ast_vm_functions *vm_table, struct ast_module *module)
Set voicemail function callbacks.
Definition: main/app.c:368
unsigned int flags
void ast_set_lock_type(enum AST_LOCK_TYPE type)
Set the type of locks used by ast_lock_path()
Definition: main/app.c:2609
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: main/app.c:3162
void ast_unreplace_sigchld(void)
Restore the SIGCHLD handler.
Definition: extconf.c:815
String manipulation functions.
int( ast_has_voicemail_fn)(const char *mailboxes, const char *folder)
Determines if the given folder has messages.
struct ast_group_info * ast_app_group_list_head(void)
Get the head of the group count list.
Definition: main/app.c:2346
const char * ast_app_expand_sub_args(struct ast_channel *chan, const char *args)
Add missing context/exten to subroutine argument string.
Definition: main/app.c:278
int ast_app_sayname(struct ast_channel *chan, const char *mailbox_id)
Play a recorded user name for the mailbox to the specified channel.
Definition: main/app.c:637
int ast_control_streamfile_lang(struct ast_channel *chan, const char *file, const char *fwd, const char *rev, const char *stop, const char *suspend, const char *restart, int skipms, const char *lang, long *offsetms)
Version of ast_control_streamfile() which allows the language of the media file to be specified...
Definition: main/app.c:1473
char context[AST_MAX_CONTEXT]
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: main/app.c:2356
Stasis Message Bus API. See Stasis Message Bus API for detailed documentation.
int( ast_inboxcount2_fn)(const char *mailboxes, int *urgentmsgs, int *newmsgs, int *oldmsgs)
Gets the number of messages that exist for the mailbox list.
Voicemail greeter function table definition.
static struct stasis_rest_handlers mailboxes
REST handler for /api-docs/mailboxes.json.
struct ast_vm_mailbox_snapshot *( ast_vm_mailbox_snapshot_create_fn)(const char *user, const char *context, const char *folder, int descending, enum ast_vm_snapshot_sort_val sort_val, int combine_INBOX_and_OLD)
Create a snapshot of a mailbox which contains information about every msg.
struct stasis_topic * ast_queue_topic_all(void)
Get the Stasis Message Bus API topic for queue messages.
Definition: main/app.c:3344
void ast_close_fds_above_n(int n)
Common routine for child processes, to close all fds prior to exec(2)
Definition: main/app.c:3202
ast_record_if_exists
int( ast_vm_msg_remove_fn)(const char *mailbox, const char *context, size_t num_msgs, const char *folder, const char *msgs[])
Remove/delete messages from a mailbox folder.
int ast_control_tone(struct ast_channel *chan, const char *tone)
Controls playback of a tone.
Definition: main/app.c:1545
void( ast_vm_msg_play_cb)(struct ast_channel *chan, const char *playfile, int duration)
Voicemail playback callback function definition.
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: main/app.c:3076
void ast_vm_unregister(const char *module_name)
Unregister the specified voicemail provider.
Definition: main/app.c:400
#define AST_DECLARE_STRING_FIELDS(field_list)
Declare the fields needed in a structure.
Definition: stringfields.h:341
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 'prepend' mode which works a li...
Definition: main/app.c:2159
int( ast_vm_msg_forward_fn)(const char *from_mailbox, const char *from_context, const char *from_folder, const char *to_mailbox, const char *to_context, const char *to_folder, size_t num_msgs, const char *msg_ids[], int delete_old)
forward a message from one mailbox to another.
Generic File Format Support. Should be included by clients of the file handling routines. File service providers should instead include mod_format.h.
int ast_unlock_path(const char *path)
Unlock a path.
Definition: main/app.c:2630
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: main/app.c:1465
Definitions to aid in the use of thread local storage.
static int inboxcount2(const char *mailbox, int *urgentmsgs, int *newmsgs, int *oldmsgs)
Check the given mailbox's message count.
Structure used to handle a large number of boolean flags == used only in app_dial?
Definition: utils.h:204
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: main/app.c:3175
char * ast_read_textfile(const char *file)
Read a file into asterisk.
Definition: main/app.c:2949
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: main/app.c:2300
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: main/app.c:1235
ast_getdata_result
Utility functions.
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: main/app.c:2646
enum AST_LOCK_RESULT ast_lock_path(const char *path)
Lock a filesystem path.
Definition: main/app.c:2614
int ast_app_inboxcount2(const char *mailboxes, int *urgentmsgs, int *newmsgs, int *oldmsgs)
Determine number of urgent/new/old messages in a mailbox.
Definition: main/app.c:619
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 '2' on ctrlfd available, not '1' like other fu...
Definition: main/app.c:247
int ast_ivr_menu_run(struct ast_channel *c, struct ast_ivr_menu *menu, void *cbdata)
Runs an IVR menu.
Definition: main/app.c:2942
int ast_vm_msg_move(const char *mailbox, const char *context, size_t num_msgs, const char *oldfolder, const char *old_msg_ids[], const char *newfolder)
Move messages from one folder to another.
Definition: main/app.c:683
int( ast_sayname_fn)(struct ast_channel *chan, const char *mailbox_id)
Play a recorded user name for the mailbox to the specified channel.
A structure to hold the description of an application 'option'.
void ast_safe_fork_cleanup(void)
Common routine to cleanup after fork'ed process is complete (if reaping was stopped) ...
Definition: main/app.c:3268
#define AST_STRING_FIELD(name)
Declare a string field.
Definition: stringfields.h:303
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: main/app.c:1616
struct ast_vm_mailbox_snapshot *( ast_vm_mailbox_snapshot_destroy_fn)(struct ast_vm_mailbox_snapshot *mailbox_snapshot)
destroy a snapshot
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 beep, int silencethreshold, int maxsilence_ms, const char *path, const char *acceptdtmf, const char *canceldtmf, int skip_confirmation_sound, enum ast_record_if_exists if_exists)
Record a file based on input from a channel This function will play "auth-thankyou" upon successful r...
Definition: main/app.c:2149
int( ast_copy_recording_to_vm_fn)(struct ast_vm_recording_data *vm_rec_data)
Creates a voicemail based on a specified file to a mailbox.
A set of macros to manage forward-linked lists.
int( ast_vm_msg_play_fn)(struct ast_channel *chan, const char *mailbox, const char *context, const char *folder, const char *msg_num, ast_vm_msg_play_cb *cb)
Play a voicemail msg back on a channel.
int ast_get_encoded_char(const char *stream, char *result, size_t *consumed)
Decode an encoded control or extended ASCII character.
Definition: main/app.c:3087
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: main/app.c:3066
void ast_replace_sigchld(void)
Replace the SIGCHLD handler.
Definition: extconf.c:801
int ast_vm_msg_play(struct ast_channel *chan, const char *mailbox, const char *context, const char *folder, const char *msg_num, ast_vm_msg_play_cb *cb)
Play a voicemail msg back on a channel.
Definition: main/app.c:726
struct ast_vm_mailbox_snapshot * ast_vm_mailbox_snapshot_destroy(struct ast_vm_mailbox_snapshot *mailbox_snapshot)
destroy a snapshot
Definition: main/app.c:675
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: main/app.c:3071
int ast_vm_msg_remove(const char *mailbox, const char *context, size_t num_msgs, const char *folder, const char *msgs[])
Remove/delete messages from a mailbox folder.
Definition: main/app.c:697
enum ast_getdata_result ast_app_getdata_terminator(struct ast_channel *c, const char *prompt, char *s, int maxlen, int timeout, char *terminator)
Plays a stream and gets DTMF data from a channel.
Definition: main/app.c:193
struct ast_module * module
The module for the voicemail greeter provider.
void ast_vm_greeter_unregister(const char *module_name)
Unregister the specified voicemail greeter provider.
Definition: main/app.c:511
#define AST_LIST_HEAD_NOLOCK(name, type)
Defines a structure to be used to hold a list of specified type (with no lock).
Definition: linkedlists.h:225
uint64_t flag
The flag bit that represents this option.
int( ast_messagecount_fn)(const char *mailbox_id, const char *folder)
Gets the number of messages that exist in a mailbox folder.
int __ast_vm_greeter_register(const struct ast_vm_greeter_functions *vm_table, struct ast_module *module)
Set voicemail greeter function callbacks.
Definition: main/app.c:479
Support for dynamic strings.
Definition: strings.h:623
int ast_safe_system(const char *s)
Safely spawn an OS shell command while closing file descriptors.
Definition: extconf.c:829
int( ast_ivr_callback)(struct ast_channel *chan, char *option, void *cbdata)
Callback function for IVR.
struct ast_vm_mailbox_snapshot * ast_vm_mailbox_snapshot_create(const char *mailbox, const char *context, const char *folder, int descending, enum ast_vm_snapshot_sort_val sort_val, int combine_INBOX_and_OLD)
Create a snapshot of a mailbox which contains information about every msg.
Definition: main/app.c:661
const char * module_name
The name of the module that provides the voicemail greeter functionality.
const char * ast_vm_index_to_foldername(int id)
Return name of folder, given an id.
Definition: main/app.c:653
Stack applications callback functions.
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: main/app.c:3207
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: main/app.c:2154
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: main/app.c:328
#define AST_LIST_ENTRY(type)
Declare a forward link structure inside a list entry.
Definition: linkedlists.h:410
unsigned int stop
Definition: res_smdi.c:217
int ast_app_group_list_unlock(void)
Unlock the group count list.
Definition: main/app.c:2351
int ast_sf_stream(struct ast_channel *chan, struct ast_channel *peer, struct ast_channel *chan2, const char *digits, int frequency, int is_external)
Send a string of SF digits to a channel.
Definition: main/app.c:1097
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: main/app.c:2166
int ast_vm_msg_forward(const char *from_mailbox, const char *from_context, const char *from_folder, const char *to_mailbox, const char *to_context, const char *to_folder, size_t num_msgs, const char *msg_ids[], int delete_old)
forward a message from one mailbox to another.
Definition: main/app.c:709
int( ast_inboxcount_fn)(const char *mailboxes, int *newmsgs, int *oldmsgs)
Gets the number of messages that exist for the mailbox list.
struct ast_ivr_option * options
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: main/app.c:2260
unsigned int arg_index
The index of the entry in the arguments array that should be used for this option's argument...
structure to hold users read from users.conf
Structure used to handle boolean flags.
Definition: utils.h:199
ast_ivr_action
int ast_app_has_voicemail(const char *mailboxes, const char *folder)
Determine if a given mailbox has any voicemail If folder is NULL, defaults to "INBOX". If folder is "INBOX", includes the number of messages in the "Urgent" folder.
Definition: main/app.c:582
int(* run_sub)(struct ast_channel *chan, const char *args, int ignore_hangup)
Callback for the routine to run a subroutine on a channel.
int ast_app_messagecount(const char *mailbox_id, const char *folder)
Get the number of messages in a given mailbox folder.
Definition: main/app.c:645
const char * module_name
The name of the module that provides the voicemail functionality.
Structure used for ast_copy_recording_to_vm in order to cleanly supply data needed for making the rec...
int ast_app_group_list_rdlock(void)
Read Lock the group count list.
Definition: main/app.c:2341
static int has_voicemail(const char *mailbox, const char *folder)
Determines if the given folder has messages.
int( ast_vm_msg_move_fn)(const char *mailbox, const char *context, size_t num_msgs, const char *oldfolder, const char *old_msg_ids[], const char *newfolder)
Move messages from one folder to another.
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: main/app.c:138
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: main/app.c:297
unsigned int module_version
The version of this function table.
int ast_control_streamfile_w_cb(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, ast_waitstream_fr_cb cb)
Stream a file with fast forward, pause, reverse, restart.
Definition: main/app.c:1451
int ast_app_group_discard(struct ast_channel *chan)
Discard all group counting for a channel.
Definition: main/app.c:2319
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: main/app.c:3273
struct stasis_topic * ast_queue_topic(const char *queuename)
Get the Stasis Message Bus API topic for queue messages for a particular queue name.
Definition: main/app.c:3349
int ast_mf_stream(struct ast_channel *chan, struct ast_channel *peer, struct ast_channel *chan2, const char *digits, int between, unsigned int duration, unsigned int durationkp, unsigned int durationst, int is_external)
Send a string of MF digits to a channel.
Definition: main/app.c:1113
Voicemail function table definition.
const char *( ast_vm_index_to_foldername_fn)(int id)
Convert the mailbox folder id to a folder name.
AST_LOCK_TYPE
Type of locking to use in ast_lock_path / ast_unlock_path.
int ast_safe_execvp(int dualfork, const char *file, char *const argv[])
Safely spawn an external program while closing file descriptors.
Definition: asterisk.c:1222
int ast_app_copy_recording_to_vm(struct ast_vm_recording_data *vm_rec_data)
param[in] vm_rec_data Contains data needed to make the recording. retval 0 voicemail successfully cre...
Definition: main/app.c:596
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: main/app.c:2193
void ast_dtmf_stream_external(struct ast_channel *chan, const char *digits, int between, unsigned int duration)
Send a string of DTMF digits to a channel from an external thread.
Definition: main/app.c:1142
int ast_app_group_list_wrlock(void)
Write Lock the group count list.
Definition: main/app.c:2336
int app_init(void)
Initialize the application core.
Definition: main/app.c:3365
int ast_app_group_get_count(const char *group, const char *category)
Get the current channel count of the specified group and category.
Definition: main/app.c:2240
int ast_app_inboxcount(const char *mailboxes, int *newmsgs, int *oldmsgs)
Determine number of new/old messages in a mailbox.
Definition: main/app.c:604