00001 /* 00002 * Asterisk -- An open source telephony toolkit. 00003 * 00004 * Copyright (C) 1999 - 2006, Digium, Inc. 00005 * 00006 * Mark Spencer <markster@digium.com> 00007 * 00008 * See http://www.asterisk.org for more information about 00009 * the Asterisk project. Please do not directly contact 00010 * any of the maintainers of this project for assistance; 00011 * the project provides a web site, mailing lists and IRC 00012 * channels for your use. 00013 * 00014 * This program is free software, distributed under the terms of 00015 * the GNU General Public License Version 2. See the LICENSE file 00016 * at the top of the source tree. 00017 */ 00018 00019 /*! \file 00020 * \brief Generic File Format Support. 00021 * Should be included by clients of the file handling routines. 00022 * File service providers should instead include mod_format.h 00023 */ 00024 00025 #ifndef _ASTERISK_FILE_H 00026 #define _ASTERISK_FILE_H 00027 00028 #ifdef HAVE_FCNTL_H 00029 #include <fcntl.h> 00030 #endif 00031 00032 #ifdef HAVE_MMAP 00033 #include <sys/mman.h> 00034 #endif 00035 00036 #if defined(__cplusplus) || defined(c_plusplus) 00037 extern "C" { 00038 #endif 00039 00040 struct ast_filestream; 00041 struct ast_format; 00042 00043 /*! Convenient for waiting */ 00044 #define AST_DIGIT_ANY "0123456789#*ABCD" 00045 #define AST_DIGIT_ANYNUM "0123456789" 00046 00047 #define SEEK_FORCECUR 10 00048 00049 /*! 00050 * \brief Streams a file 00051 * \param c channel to stream the file to 00052 * \param filename the name of the file you wish to stream, minus the extension 00053 * \param preflang the preferred language you wish to have the file streamed to you in 00054 * Prepares a channel for the streaming of a file. To start the stream, afterward do a ast_waitstream() on the channel 00055 * Also, it will stop any existing streams on the channel. 00056 * \retval 0 on success. 00057 * \retval -1 on failure. 00058 */ 00059 int ast_streamfile(struct ast_channel *c, const char *filename, const char *preflang); 00060 00061 /*! 00062 * \brief stream file until digit 00063 * If the file name is non-empty, try to play it. 00064 * \note If digits == "" then we can simply check for non-zero. 00065 * \return 0 if success. 00066 * \retval -1 if error. 00067 * \retval digit if interrupted by a digit. 00068 */ 00069 int ast_stream_and_wait(struct ast_channel *chan, const char *file, const char *digits); 00070 00071 /*! 00072 * \brief Stops a stream 00073 * 00074 * \param c The channel you wish to stop playback on 00075 * 00076 * Stop playback of a stream 00077 * 00078 * \retval 0 always 00079 * 00080 * \note The channel does not need to be locked before calling this function. 00081 */ 00082 int ast_stopstream(struct ast_channel *c); 00083 00084 /*! 00085 * \brief Checks for the existence of a given file 00086 * \param filename name of the file you wish to check, minus the extension 00087 * \param fmt the format you wish to check (the extension) 00088 * \param preflang (the preferred language you wisht to find the file in) 00089 * See if a given file exists in a given format. If fmt is NULL, any format is accepted. 00090 * \return -1 if file does not exist, non-zero positive otherwise. 00091 */ 00092 int ast_fileexists(const char *filename, const char *fmt, const char *preflang); 00093 00094 /*! 00095 * \brief Renames a file 00096 * \param oldname the name of the file you wish to act upon (minus the extension) 00097 * \param newname the name you wish to rename the file to (minus the extension) 00098 * \param fmt the format of the file 00099 * Rename a given file in a given format, or if fmt is NULL, then do so for all 00100 * \return -1 on failure 00101 */ 00102 int ast_filerename(const char *oldname, const char *newname, const char *fmt); 00103 00104 /*! 00105 * \brief Deletes a file 00106 * \param filename name of the file you wish to delete (minus the extension) 00107 * \param fmt of the file 00108 * Delete a given file in a given format, or if fmt is NULL, then do so for all 00109 */ 00110 int ast_filedelete(const char *filename, const char *fmt); 00111 00112 /*! 00113 * \brief Copies a file 00114 * \param oldname name of the file you wish to copy (minus extension) 00115 * \param newname name you wish the file to be copied to (minus extension) 00116 * \param fmt the format of the file 00117 * Copy a given file in a given format, or if fmt is NULL, then do so for all 00118 */ 00119 int ast_filecopy(const char *oldname, const char *newname, const char *fmt); 00120 00121 /*! 00122 * \brief Waits for a stream to stop or digit to be pressed 00123 * \param c channel to waitstream on 00124 * \param breakon string of DTMF digits to break upon 00125 * Begins playback of a stream... 00126 * Wait for a stream to stop or for any one of a given digit to arrive, 00127 * \retval 0 if the stream finishes 00128 * \retval the character if it was interrupted, 00129 * \retval -1 on error 00130 */ 00131 int ast_waitstream(struct ast_channel *c, const char *breakon); 00132 00133 /*! 00134 * \brief Waits for a stream to stop or digit matching a valid one digit exten to be pressed 00135 * \param c channel to waitstream on 00136 * \param context string of context to match digits to break upon 00137 * Begins playback of a stream... 00138 * Wait for a stream to stop or for any one of a valid extension digit to arrive, 00139 * \retval 0 if the stream finishes. 00140 * \retval the character if it was interrupted. 00141 * \retval -1 on error. 00142 */ 00143 int ast_waitstream_exten(struct ast_channel *c, const char *context); 00144 00145 /*! 00146 * \brief Same as waitstream but allows stream to be forwarded or rewound 00147 * \param c channel to waitstream on 00148 * \param breakon string of DTMF digits to break upon 00149 * \param forward DTMF digit to fast forward upon 00150 * \param rewind DTMF digit to rewind upon 00151 * \param ms How many miliseconds to skip forward/back 00152 * Begins playback of a stream... 00153 * Wait for a stream to stop or for any one of a given digit to arrive, 00154 * \retval 0 if the stream finishes. 00155 * \retval the character if it was interrupted. 00156 * \retval -1 on error. 00157 */ 00158 int ast_waitstream_fr(struct ast_channel *c, const char *breakon, const char *forward, const char *rewind, int ms); 00159 00160 /*! 00161 * Same as waitstream, but with audio output to fd and monitored fd checking. 00162 * 00163 * \return 1 if monfd is ready for reading 00164 */ 00165 int ast_waitstream_full(struct ast_channel *c, const char *breakon, int audiofd, int monfd); 00166 00167 /*! 00168 * \brief Starts reading from a file 00169 * \param filename the name of the file to read from 00170 * \param type format of file you wish to read from 00171 * \param comment comment to go with 00172 * \param flags file flags 00173 * \param check (unimplemented, hence negligible) 00174 * \param mode Open mode 00175 * Open an incoming file stream. flags are flags for the open() command, and 00176 * if check is non-zero, then it will not read a file if there are any files that 00177 * start with that name and have an extension 00178 * Please note, this is a blocking function. Program execution will not return until ast_waitstream completes it's execution. 00179 * \retval a struct ast_filestream on success. 00180 * \retval NULL on failure. 00181 */ 00182 struct ast_filestream *ast_readfile(const char *filename, const char *type, const char *comment, int flags, int check, mode_t mode); 00183 00184 /*! 00185 * \brief Starts writing a file 00186 * \param filename the name of the file to write to 00187 * \param type format of file you wish to write out to 00188 * \param comment comment to go with 00189 * \param flags output file flags 00190 * \param check (unimplemented, hence negligible) 00191 * \param mode Open mode 00192 * Create an outgoing file stream. oflags are flags for the open() command, and 00193 * if check is non-zero, then it will not write a file if there are any files that 00194 * start with that name and have an extension 00195 * Please note, this is a blocking function. Program execution will not return until ast_waitstream completes it's execution. 00196 * \retval a struct ast_filestream on success. 00197 * \retval NULL on failure. 00198 */ 00199 struct ast_filestream *ast_writefile(const char *filename, const char *type, const char *comment, int flags, int check, mode_t mode); 00200 00201 /*! 00202 * \brief Writes a frame to a stream 00203 * \param fs filestream to write to 00204 * \param f frame to write to the filestream 00205 * Send a frame to a filestream -- note: does NOT free the frame, call ast_frfree manually 00206 * \retval 0 on success. 00207 * \retval -1 on failure. 00208 */ 00209 int ast_writestream(struct ast_filestream *fs, struct ast_frame *f); 00210 00211 /*! 00212 * \brief Closes a stream 00213 * \param f filestream to close 00214 * Close a playback or recording stream 00215 * \retval 0 on success. 00216 * \retval -1 on failure. 00217 */ 00218 int ast_closestream(struct ast_filestream *f); 00219 00220 /*! 00221 * \brief Opens stream for use in seeking, playing 00222 * \param chan channel to work with 00223 * \param filename to use 00224 * \param preflang prefered language to use 00225 * \retval a ast_filestream pointer if it opens the file. 00226 * \retval NULL on error. 00227 */ 00228 struct ast_filestream *ast_openstream(struct ast_channel *chan, const char *filename, const char *preflang); 00229 00230 /*! 00231 * \brief Opens stream for use in seeking, playing 00232 * \param chan channel to work with 00233 * \param filename to use 00234 * \param preflang prefered language to use 00235 * \param asis if set, don't clear generators 00236 * \retval a ast_filestream pointer if it opens the file. 00237 * \retval NULL on error. 00238 */ 00239 struct ast_filestream *ast_openstream_full(struct ast_channel *chan, const char *filename, const char *preflang, int asis); 00240 /*! 00241 * \brief Opens stream for use in seeking, playing 00242 * \param chan channel to work with 00243 * \param filename to use 00244 * \param preflang prefered language to use 00245 * \retval a ast_filestream pointer if it opens the file. 00246 * \retval NULL on error. 00247 */ 00248 struct ast_filestream *ast_openvstream(struct ast_channel *chan, const char *filename, const char *preflang); 00249 00250 /*! 00251 * \brief Applys a open stream to a channel. 00252 * \param chan channel to work 00253 * \param s ast_filestream to apply 00254 * \retval 0 on success. 00255 * \retval -1 on failure. 00256 */ 00257 int ast_applystream(struct ast_channel *chan, struct ast_filestream *s); 00258 00259 /*! 00260 * \brief Play a open stream on a channel. 00261 * \param s filestream to play 00262 * \retval 0 on success. 00263 * \retval -1 on failure. 00264 */ 00265 int ast_playstream(struct ast_filestream *s); 00266 00267 /*! 00268 * \brief Seeks into stream 00269 * \param fs ast_filestream to perform seek on 00270 * \param sample_offset numbers of samples to seek 00271 * \param whence SEEK_SET, SEEK_CUR, SEEK_END 00272 * \retval 0 on success. 00273 * \retval -1 on failure. 00274 */ 00275 int ast_seekstream(struct ast_filestream *fs, off_t sample_offset, int whence); 00276 00277 /*! 00278 * \brief Trunc stream at current location 00279 * \param fs filestream to act on 00280 * \retval 0 on success. 00281 * \retval -1 on failure. 00282 */ 00283 int ast_truncstream(struct ast_filestream *fs); 00284 00285 /*! 00286 * \brief Fast forward stream ms 00287 * \param fs filestream to act on 00288 * \param ms milliseconds to move 00289 * \retval 0 on success. 00290 * \retval -1 on failure. 00291 */ 00292 int ast_stream_fastforward(struct ast_filestream *fs, off_t ms); 00293 00294 /*! 00295 * \brief Rewind stream ms 00296 * \param fs filestream to act on 00297 * \param ms milliseconds to move 00298 * \retval 0 on success. 00299 * \retval -1 on failure. 00300 */ 00301 int ast_stream_rewind(struct ast_filestream *fs, off_t ms); 00302 00303 /*! 00304 * \brief Tell where we are in a stream 00305 * \param fs fs to act on 00306 * \return a long as a sample offset into stream 00307 */ 00308 off_t ast_tellstream(struct ast_filestream *fs); 00309 00310 /*! 00311 * \brief Read a frame from a filestream 00312 * \param s ast_filestream to act on 00313 * \return a frame. 00314 * \retval NULL if read failed. 00315 */ 00316 struct ast_frame *ast_readframe(struct ast_filestream *s); 00317 00318 /*!\brief destroy a filestream using an ast_frame as input 00319 * 00320 * This is a hack that is used also by the ast_trans_pvt and 00321 * ast_dsp structures. When a structure contains an ast_frame 00322 * pointer as one of its fields. It may be that the frame is 00323 * still used after the outer structure is freed. This leads to 00324 * invalid memory accesses. This function allows for us to hold 00325 * off on destroying the ast_filestream until we are done using 00326 * the ast_frame pointer that is part of it 00327 * 00328 * \param fr The ast_frame that is part of an ast_filestream we wish 00329 * to free. 00330 */ 00331 void ast_filestream_frame_freed(struct ast_frame *fr); 00332 00333 /*! Initialize file stuff */ 00334 /*! 00335 * Initializes all the various file stuff. Basically just registers the cli stuff 00336 * Returns 0 all the time 00337 */ 00338 int ast_file_init(void); 00339 00340 00341 #define AST_RESERVED_POINTERS 20 00342 00343 #if defined(__cplusplus) || defined(c_plusplus) 00344 } 00345 #endif 00346 00347 #endif /* _ASTERISK_FILE_H */