Make voicemail registration apps register (bug #3034)
[asterisk/asterisk.git] / include / asterisk / app.h
1 /*
2  * Asterisk -- A telephony toolkit for Linux.
3  *
4  * Application convenience functions, designed to give consistent
5  * look and feel to asterisk apps.
6  * 
7  * Copyright (C) 1999-2004, Digium, Inc.
8  *
9  * Mark Spencer <markster@digium.com>
10  *
11  * This program is free software, distributed under the terms of
12  * the GNU General Public License
13  */
14
15 #ifndef _ASTERISK_APP_H
16 #define _ASTERISK_APP_H
17
18 #if defined(__cplusplus) || defined(c_plusplus)
19 extern "C" {
20 #endif
21 //! Plays a stream and gets DTMF data from a channel
22 /*!
23  * \param c Which channel one is interacting with
24  * \param prompt File to pass to ast_streamfile (the one that you wish to play)
25  * \param s The location where the DTMF data will be stored
26  * \param maxlen Max Length of the data
27  * \param timeout Timeout length waiting for data(in milliseconds).  Set to 0 for standard timeout(six seconds), or -1 for no time out.
28  *
29  *  This function was designed for application programmers for situations where they need 
30  *  to play a message and then get some DTMF data in response to the message.  If a digit 
31  *  is pressed during playback, it will immediately break out of the message and continue
32  *  execution of your code.
33  */
34 extern int ast_app_getdata(struct ast_channel *c, char *prompt, char *s, int maxlen, int timeout);
35
36 /* Full version with audiofd and controlfd.  NOTE: returns '2' on ctrlfd available, not '1' like other full functions */
37 extern int ast_app_getdata_full(struct ast_channel *c, char *prompt, char *s, int maxlen, int timeout, int audiofd, int ctrlfd);
38
39 //! Record voice (after playing prompt if specified), waiting for silence (in ms) up to a given timeout (in s) or '#'
40 int ast_app_getvoice(struct ast_channel *c, char *dest, char *dstfmt, char *prompt, int silence, int maxsec);
41
42 void ast_install_vm_functions(int (*has_voicemail_func)(const char *mailbox, const char *folder),
43                               int (*messagecount_func)(const char *mailbox, int *newmsgs, int *oldmsgs));
44   
45 void ast_uninstall_vm_functions(void);
46
47 //! Determine if a given mailbox has any voicemail
48 int ast_app_has_voicemail(const char *mailbox, const char *folder);
49
50 //! Determine number of new/old messages in a mailbox
51 int ast_app_messagecount(const char *mailbox, int *newmsgs, int *oldmsgs);
52
53 //! Safely spawn an external program while closingn file descriptors
54 extern int ast_safe_system(const char *s);
55
56 //! Send DTMF to chan (optionally entertain peer)  
57 int ast_dtmf_stream(struct ast_channel *chan, struct ast_channel *peer, char *digits, int between);
58
59 //! Stream a filename (or file descriptor) as a generator.
60 int ast_linear_stream(struct ast_channel *chan, const char *filename, int fd, int allowoverride);
61
62 //! Stream a file with fast forward, pause, reverse.
63 int ast_control_streamfile(struct ast_channel *chan, char *file, char *fwd, char *rev, char *stop, char *pause, int skipms);
64
65 //! Play a stream and wait for a digit, returning the digit that was pressed
66 int ast_play_and_wait(struct ast_channel *chan, char *fn);
67
68 //! Record a file for a max amount of time (in seconds), in a given list of formats separated by '|', outputting the duration of the recording, and with a maximum
69 //  permitted silence time in milliseconds of 'maxsilence' under 'silencethreshold' or use '-1' for either or both parameters for defaults.
70 int ast_play_and_record(struct ast_channel *chan, char *playfile, char *recordfile, int maxtime_sec, char *fmt, int *duration, int silencethreshold, int maxsilence_ms);
71
72 //! Record a message and prepend the message to the given record file after playing the optional playfile (or a beep), storing the duration in 'duration' and with a maximum
73 //  permitted silence time in milliseconds of 'maxsilence' under 'silencethreshold' or use '-1' for either or both parameters for defaults.
74 int ast_play_and_prepend(struct ast_channel *chan, char *playfile, char *recordfile, int maxtime_sec, char *fmt, int *duration, int beep, int silencethreshold, int maxsilence_ms);
75
76 #define GROUP_CATEGORY_PREFIX "GROUP"
77
78 //! Split a group string into group and category, returning a default category if none is provided.
79 int ast_app_group_split_group(char *data, char *group, int group_max, char *category, int category_max);
80
81 //! Set the group for a channel, splitting the provided data into group and category, if specified.
82 int ast_app_group_set_channel(struct ast_channel *chan, char *data);
83
84 //! Get the current channel count of the specified group and category.
85 int ast_app_group_get_count(char *group, char *category);
86
87 //! Get the current channel count of all groups that match the specified pattern and category.
88 int ast_app_group_match_get_count(char *groupmatch, char *category);
89
90 //! Create an argc argv type structure for app args
91 int ast_seperate_app_args(char *buf, char delim, char **array, int arraylen);
92
93 #if defined(__cplusplus) || defined(c_plusplus)
94 }
95 #endif
96
97 #endif