b50dfe36b5f0f0d7f154b8d20ae3c913143d39b5
[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 - 2005, 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
22 /* IVR stuff */
23
24 /* Callback function for IVR, returns 0 on completion, -1 on hangup or digit if
25    interrupted */
26 typedef int (*ast_ivr_callback)(struct ast_channel *chan, char *option, void *cbdata);
27
28 typedef enum {
29         AST_ACTION_UPONE,               /* adata is unused */
30         AST_ACTION_EXIT,                /* adata is the return value for ast_ivr_menu_run if channel was not hungup */
31         AST_ACTION_CALLBACK,    /* adata is an ast_ivr_callback */
32         AST_ACTION_PLAYBACK,    /* adata is file to play */
33         AST_ACTION_BACKGROUND,  /* adata is file to play */
34         AST_ACTION_PLAYLIST,    /* adata is list of files, separated by ; to play */
35         AST_ACTION_MENU,                /* adata is a pointer to an ast_ivr_menu */
36         AST_ACTION_REPEAT,              /* adata is max # of repeats, cast to a pointer */
37         AST_ACTION_RESTART,             /* adata is like repeat, but resets repeats to 0 */
38         AST_ACTION_TRANSFER,    /* adata is a string with exten[@context] */
39         AST_ACTION_WAITOPTION,  /* adata is a timeout, or 0 for defaults */
40         AST_ACTION_NOOP,                /* adata is unused */
41         AST_ACTION_BACKLIST,    /* adata is list of files separated by ; allows interruption */
42 } ast_ivr_action;
43
44 struct ast_ivr_option {
45         char *option;
46         ast_ivr_action action;
47         void *adata;    
48 };
49
50 /* 
51     Special "options" are: 
52    "s" - "start here (one time greeting)"
53    "g" - "greeting/instructions"
54    "t" - "timeout"
55    "h" - "hangup"
56    "i" - "invalid selection"
57
58 */
59
60 struct ast_ivr_menu {
61         char *title;            /* Title of menu */
62         unsigned int flags;     /* Flags */
63         struct ast_ivr_option *options; /* All options */
64 };
65
66 #define AST_IVR_FLAG_AUTORESTART (1 << 0)
67
68 struct ast_option {
69         unsigned int flag;
70         int argoption;
71 };
72
73 extern int ast_parseoptions(const struct ast_option *options, struct ast_flags *flags, char **args, char *optstr);
74
75 #define AST_DECLARE_OPTIONS(holder,args...) \
76         static struct ast_option holder[128] = args
77
78 #define AST_IVR_DECLARE_MENU(holder,title,flags,foo...) \
79         static struct ast_ivr_option __options_##holder[] = foo;\
80         static struct ast_ivr_menu holder = { title, flags, __options_##holder }
81         
82
83 /*! Runs an IVR menu, returns 0 on successful completion, -1 on hangup, or -2 on user error in menu */
84 extern int ast_ivr_menu_run(struct ast_channel *c, struct ast_ivr_menu *menu, void *cbdata);
85
86 /*! Plays a stream and gets DTMF data from a channel */
87 /*!
88  * \param c Which channel one is interacting with
89  * \param prompt File to pass to ast_streamfile (the one that you wish to play)
90  * \param s The location where the DTMF data will be stored
91  * \param maxlen Max Length of the data
92  * \param timeout Timeout length waiting for data(in milliseconds).  Set to 0 for standard timeout(six seconds), or -1 for no time out.
93  *
94  *  This function was designed for application programmers for situations where they need 
95  *  to play a message and then get some DTMF data in response to the message.  If a digit 
96  *  is pressed during playback, it will immediately break out of the message and continue
97  *  execution of your code.
98  */
99 extern int ast_app_getdata(struct ast_channel *c, char *prompt, char *s, int maxlen, int timeout);
100
101 /* Full version with audiofd and controlfd.  NOTE: returns '2' on ctrlfd available, not '1' like other full functions */
102 extern int ast_app_getdata_full(struct ast_channel *c, char *prompt, char *s, int maxlen, int timeout, int audiofd, int ctrlfd);
103
104 /*! Record voice (after playing prompt if specified), waiting for silence (in ms) up to a given timeout (in s) or '#' */
105 int ast_app_getvoice(struct ast_channel *c, char *dest, char *dstfmt, char *prompt, int silence, int maxsec);
106
107 void ast_install_vm_functions(int (*has_voicemail_func)(const char *mailbox, const char *folder),
108                               int (*messagecount_func)(const char *mailbox, int *newmsgs, int *oldmsgs));
109   
110 void ast_uninstall_vm_functions(void);
111
112 /*! Determine if a given mailbox has any voicemail */
113 int ast_app_has_voicemail(const char *mailbox, const char *folder);
114
115 /*! Determine number of new/old messages in a mailbox */
116 int ast_app_messagecount(const char *mailbox, int *newmsgs, int *oldmsgs);
117
118 /*! Safely spawn an external program while closingn file descriptors */
119 extern int ast_safe_system(const char *s);
120
121 /*! Send DTMF to chan (optionally entertain peer)   */
122 int ast_dtmf_stream(struct ast_channel *chan, struct ast_channel *peer, char *digits, int between);
123
124 /*! Stream a filename (or file descriptor) as a generator. */
125 int ast_linear_stream(struct ast_channel *chan, const char *filename, int fd, int allowoverride);
126
127 /*! Stream a file with fast forward, pause, reverse. */
128 int ast_control_streamfile(struct ast_channel *chan, const char *file, const char *fwd, const char *rev, const char *stop, const char *pause, int skipms);
129
130 /*! Play a stream and wait for a digit, returning the digit that was pressed */
131 int ast_play_and_wait(struct ast_channel *chan, const char *fn);
132
133 /*! 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 */
134 /*   permitted silence time in milliseconds of 'maxsilence' under 'silencethreshold' or use '-1' for either or both parameters for defaults. 
135      calls ast_unlock_path() on 'path' if passed */
136 int ast_play_and_record(struct ast_channel *chan, const char *playfile, const char *recordfile, int maxtime_sec, const char *fmt, int *duration, int silencethreshold, int maxsilence_ms, const char *path);
137
138 /*! 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 */
139 /*   permitted silence time in milliseconds of 'maxsilence' under 'silencethreshold' or use '-1' for either or both parameters for defaults. */
140 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);
141
142 /* Lock a path */
143 int ast_lock_path(const char *path);
144
145 /* Unlock a path */
146 int ast_unlock_path(const char *path);
147
148 /*Read a file into asterisk*/
149 char *ast_read_textfile(const char *file);
150
151 #define GROUP_CATEGORY_PREFIX "GROUP"
152
153 /*! Split a group string into group and category, returning a default category if none is provided. */
154 int ast_app_group_split_group(char *data, char *group, int group_max, char *category, int category_max);
155
156 /*! Set the group for a channel, splitting the provided data into group and category, if specified. */
157 int ast_app_group_set_channel(struct ast_channel *chan, char *data);
158
159 /*! Get the current channel count of the specified group and category. */
160 int ast_app_group_get_count(char *group, char *category);
161
162 /*! Get the current channel count of all groups that match the specified pattern and category. */
163 int ast_app_group_match_get_count(char *groupmatch, char *category);
164
165 /*! Create an argc argv type structure for app args */
166 int ast_separate_app_args(char *buf, char delim, char **array, int arraylen);
167
168 /*! Present a dialtone and collect a certain length extension.  Returns 1 on valid extension entered, -1 on hangup, or 0 on invalid extension. Note that if 'collect' holds digits already, new digits will be appended, so be sure it's initialized properly */
169 int ast_app_dtget(struct ast_channel *chan, const char *context, char *collect, size_t size, int maxlen, int timeout);
170
171 /*! Allow to record message and have a review option */
172 int ast_record_review(struct ast_channel *chan, const char *playfile, const char *recordfile, int maxtime, const char *fmt, int *duration, const char *path);
173
174 #if defined(__cplusplus) || defined(c_plusplus)
175 }
176 #endif
177
178 #endif