00001 /* 00002 * Asterisk -- An open source telephony toolkit. 00003 * 00004 * Copyright (C) 1999 - 2005, 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 */ 00022 00023 #ifndef _ASTERISK_FILE_H 00024 #define _ASTERISK_FILE_H 00025 00026 #ifndef stdin 00027 #error You must include stdio.h before file.h! 00028 #endif /* !stdin */ 00029 00030 #include "asterisk/channel.h" 00031 #include "asterisk/frame.h" 00032 #include <fcntl.h> 00033 00034 00035 #if defined(__cplusplus) || defined(c_plusplus) 00036 extern "C" { 00037 #endif 00038 00039 00040 /*! Convenient for waiting */ 00041 #define AST_DIGIT_ANY "0123456789#*ABCD" 00042 #define AST_DIGIT_ANYNUM "0123456789" 00043 00044 #define SEEK_FORCECUR 10 00045 00046 /* Defined by individual formats. First item MUST be a 00047 pointer for use by the stream manager */ 00048 struct ast_filestream; 00049 00050 /*! Registers a new file format */ 00051 /*! Register a new file format capability 00052 * Adds a format to asterisk's format abilities. Fill in the fields, and it will work. For examples, look at some of the various format code. 00053 * returns 0 on success, -1 on failure 00054 */ 00055 int ast_format_register(const char *name, const char *exts, int format, 00056 struct ast_filestream * (*open)(FILE *f), 00057 struct ast_filestream * (*rewrite)(FILE *f, const char *comment), 00058 int (*write)(struct ast_filestream *, struct ast_frame *), 00059 int (*seek)(struct ast_filestream *, long offset, int whence), 00060 int (*trunc)(struct ast_filestream *), 00061 long (*tell)(struct ast_filestream *), 00062 struct ast_frame * (*read)(struct ast_filestream *, int *timetonext), 00063 void (*close)(struct ast_filestream *), 00064 char * (*getcomment)(struct ast_filestream *)); 00065 00066 /*! Unregisters a file format */ 00067 /*! 00068 * \param name the name of the format you wish to unregister 00069 * Unregisters a format based on the name of the format. 00070 * Returns 0 on success, -1 on failure to unregister 00071 */ 00072 int ast_format_unregister(const char *name); 00073 00074 /*! Streams a file */ 00075 /*! 00076 * \param c channel to stream the file to 00077 * \param filename the name of the file you wish to stream, minus the extension 00078 * \param preflang the preferred language you wish to have the file streamed to you in 00079 * Prepares a channel for the streaming of a file. To start the stream, afterward do a ast_waitstream() on the channel 00080 * Also, it will stop any existing streams on the channel. 00081 * Returns 0 on success, or -1 on failure. 00082 */ 00083 int ast_streamfile(struct ast_channel *c, const char *filename, const char *preflang); 00084 00085 /*! Stops a stream */ 00086 /*! 00087 * \param c The channel you wish to stop playback on 00088 * Stop playback of a stream 00089 * Returns 0 regardless 00090 */ 00091 int ast_stopstream(struct ast_channel *c); 00092 00093 /*! Checks for the existence of a given file */ 00094 /*! 00095 * \param filename name of the file you wish to check, minus the extension 00096 * \param fmt the format you wish to check (the extension) 00097 * \param preflang (the preferred language you wisht to find the file in) 00098 * See if a given file exists in a given format. If fmt is NULL, any format is accepted. 00099 * Returns -1 if file does not exist, non-zero positive otherwise. 00100 */ 00101 int ast_fileexists(const char *filename, const char *fmt, const char *preflang); 00102 00103 /*! Renames a file */ 00104 /*! 00105 * \param oldname the name of the file you wish to act upon (minus the extension) 00106 * \param newname the name you wish to rename the file to (minus the extension) 00107 * \param fmt the format of the file 00108 * Rename a given file in a given format, or if fmt is NULL, then do so for all 00109 * Returns -1 on failure 00110 */ 00111 int ast_filerename(const char *oldname, const char *newname, const char *fmt); 00112 00113 /*! Deletes a file */ 00114 /*! 00115 * \param filename name of the file you wish to delete (minus the extension) 00116 * \param fmt of the file 00117 * Delete a given file in a given format, or if fmt is NULL, then do so for all 00118 */ 00119 int ast_filedelete(const char *filename, const char *fmt); 00120 00121 /*! Copies a file */ 00122 /*! 00123 * \param oldname name of the file you wish to copy (minus extension) 00124 * \param newname name you wish the file to be copied to (minus extension) 00125 * \param fmt the format of the file 00126 * Copy a given file in a given format, or if fmt is NULL, then do so for all 00127 */ 00128 int ast_filecopy(const char *oldname, const char *newname, const char *fmt); 00129 00130 /*! Waits for a stream to stop or digit to be pressed */ 00131 /*! 00132 * \param c channel to waitstram on 00133 * \param breakon string of DTMF digits to break upon 00134 * Begins playback of a stream... 00135 * Wait for a stream to stop or for any one of a given digit to arrive, Returns 0 00136 * if the stream finishes, the character if it was interrupted, and -1 on error 00137 */ 00138 int ast_waitstream(struct ast_channel *c, const char *breakon); 00139 00140 /*! Waits for a stream to stop or digit matching a valid one digit exten to be pressed */ 00141 /*! 00142 * \param c channel to waitstram on 00143 * \param context string of context to match digits to break upon 00144 * Begins playback of a stream... 00145 * Wait for a stream to stop or for any one of a valid extension digit to arrive, Returns 0 00146 * if the stream finishes, the character if it was interrupted, and -1 on error 00147 */ 00148 int ast_waitstream_exten(struct ast_channel *c, const char *context); 00149 00150 /*! Same as waitstream but allows stream to be forwarded or rewound */ 00151 /*! 00152 * \param c channel to waitstram on 00153 * \param breakon string of DTMF digits to break upon 00154 * \param forward DTMF digit to fast forward upon 00155 * \param rewind DTMF digit to rewind upon 00156 * \param ms How many miliseconds to skip forward/back 00157 * Begins playback of a stream... 00158 * Wait for a stream to stop or for any one of a given digit to arrive, Returns 0 00159 * if the stream finishes, the character if it was interrupted, and -1 on error 00160 */ 00161 int ast_waitstream_fr(struct ast_channel *c, const char *breakon, const char *forward, const char *rewind, int ms); 00162 00163 /* Same as waitstream, but with audio output to fd and monitored fd checking. Returns 00164 1 if monfd is ready for reading */ 00165 int ast_waitstream_full(struct ast_channel *c, const char *breakon, int audiofd, int monfd); 00166 00167 /*! Starts reading from a file */ 00168 /*! 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 * Returns a struct ast_filestream on success, NULL on failure 00180 */ 00181 struct ast_filestream *ast_readfile(const char *filename, const char *type, const char *comment, int flags, int check, mode_t mode); 00182 00183 /*! Starts writing a file */ 00184 /*! 00185 * \param filename the name of the file to write to 00186 * \param type format of file you wish to write out to 00187 * \param comment comment to go with 00188 * \param flags output file flags 00189 * \param check (unimplemented, hence negligible) 00190 * \param mode Open mode 00191 * Create an outgoing file stream. oflags are flags for the open() command, and 00192 * if check is non-zero, then it will not write a file if there are any files that 00193 * start with that name and have an extension 00194 * Please note, this is a blocking function. Program execution will not return until ast_waitstream completes it's execution. 00195 * Returns a struct ast_filestream on success, NULL on failure 00196 */ 00197 struct ast_filestream *ast_writefile(const char *filename, const char *type, const char *comment, int flags, int check, mode_t mode); 00198 00199 /*! Writes a frame to a stream */ 00200 /*! 00201 * \param fs filestream to write to 00202 * \param f frame to write to the filestream 00203 * Send a frame to a filestream -- note: does NOT free the frame, call ast_frfree manually 00204 * Returns 0 on success, -1 on failure. 00205 */ 00206 int ast_writestream(struct ast_filestream *fs, struct ast_frame *f); 00207 00208 /*! Closes a stream */ 00209 /*! 00210 * \param f filestream to close 00211 * Close a playback or recording stream 00212 * Returns 0 on success, -1 on failure 00213 */ 00214 int ast_closestream(struct ast_filestream *f); 00215 00216 /*! Opens stream for use in seeking, playing */ 00217 /*! 00218 * \param chan channel to work with 00219 * \param filename to use 00220 * \param preflang prefered language to use 00221 * Returns a ast_filestream pointer if it opens the file, NULL on error 00222 */ 00223 struct ast_filestream *ast_openstream(struct ast_channel *chan, const char *filename, const char *preflang); 00224 00225 /*! Opens stream for use in seeking, playing */ 00226 /*! 00227 * \param chan channel to work with 00228 * \param filename to use 00229 * \param preflang prefered language to use 00230 * \param asis if set, don't clear generators 00231 * Returns a ast_filestream pointer if it opens the file, NULL on error 00232 */ 00233 struct ast_filestream *ast_openstream_full(struct ast_channel *chan, const char *filename, const char *preflang, int asis); 00234 /*! Opens stream for use in seeking, playing */ 00235 /*! 00236 * \param chan channel to work with 00237 * \param filename to use 00238 * \param preflang prefered language to use 00239 * Returns a ast_filestream pointer if it opens the file, NULL on error 00240 */ 00241 struct ast_filestream *ast_openvstream(struct ast_channel *chan, const char *filename, const char *preflang); 00242 00243 /*! Applys a open stream to a channel. */ 00244 /*! 00245 * \param chan channel to work 00246 * \param s ast_filestream to apply 00247 * Returns 0 for success, -1 on failure 00248 */ 00249 int ast_applystream(struct ast_channel *chan, struct ast_filestream *s); 00250 00251 /*! play a open stream on a channel. */ 00252 /*! 00253 * \param s filestream to play 00254 * Returns 0 for success, -1 on failure 00255 */ 00256 int ast_playstream(struct ast_filestream *s); 00257 00258 /*! Seeks into stream */ 00259 /*! 00260 * \param fs ast_filestream to perform seek on 00261 * \param sample_offset numbers of samples to seek 00262 * \param whence SEEK_SET, SEEK_CUR, SEEK_END 00263 * Returns 0 for success, or -1 for error 00264 */ 00265 int ast_seekstream(struct ast_filestream *fs, long sample_offset, int whence); 00266 00267 /*! Trunc stream at current location */ 00268 /*! 00269 * \param fs filestream to act on 00270 * Returns 0 for success, or -1 for error 00271 */ 00272 int ast_truncstream(struct ast_filestream *fs); 00273 00274 /*! Fast forward stream ms */ 00275 /*! 00276 * \param fs filestream to act on 00277 * \param ms milliseconds to move 00278 * Returns 0 for success, or -1 for error 00279 */ 00280 int ast_stream_fastforward(struct ast_filestream *fs, long ms); 00281 00282 /*! Rewind stream ms */ 00283 /*! 00284 * \param fs filestream to act on 00285 * \param ms milliseconds to move 00286 * Returns 0 for success, or -1 for error 00287 */ 00288 int ast_stream_rewind(struct ast_filestream *fs, long ms); 00289 00290 /*! Tell where we are in a stream */ 00291 /*! 00292 * \param fs fs to act on 00293 * Returns a long as a sample offset into stream 00294 */ 00295 long ast_tellstream(struct ast_filestream *fs); 00296 00297 /*! Read a frame from a filestream */ 00298 /*! 00299 * \param s ast_filestream to act on 00300 * Returns a frame or NULL if read failed 00301 */ 00302 struct ast_frame *ast_readframe(struct ast_filestream *s); 00303 00304 /*! Initialize file stuff */ 00305 /*! 00306 * Initializes all the various file stuff. Basically just registers the cli stuff 00307 * Returns 0 all the time 00308 */ 00309 extern int ast_file_init(void); 00310 00311 00312 #define AST_RESERVED_POINTERS 20 00313 00314 #if defined(__cplusplus) || defined(c_plusplus) 00315 } 00316 #endif 00317 00318 #endif /* _ASTERISK_FILE_H */