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 */ 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 #if defined(__cplusplus) || defined(c_plusplus) 00035 extern "C" { 00036 #endif 00037 00038 00039 /*! Convenient for waiting */ 00040 #define AST_DIGIT_ANY "0123456789#*ABCD" 00041 #define AST_DIGIT_ANYNUM "0123456789" 00042 00043 /*! structure used for lock and refcount of format handlers. 00044 * Should not be here, but this is a temporary workaround 00045 * until we implement a more general mechanism. 00046 * The format handler should include a pointer to 00047 * this structure. 00048 * As a trick, if usecnt is initialized with -1, 00049 * ast_format_register will init the mutex for you. 00050 */ 00051 struct ast_format_lock { 00052 ast_mutex_t lock; 00053 int usecnt; /* number of active clients */ 00054 }; 00055 00056 /*! 00057 * Each supported file format is described by the following fields. 00058 * Not all are necessary, the support routine implement default 00059 * values for some of them. 00060 * A handler typically fills a structure initializing the desired 00061 * fields, and then calls ast_format_register() with the (readonly) 00062 * structure as an argument. 00063 */ 00064 struct ast_format { 00065 char name[80]; /*! Name of format */ 00066 char exts[80]; /*! Extensions (separated by | if more than one) 00067 this format can read. First is assumed for writing (e.g. .mp3) */ 00068 int format; /*! Format of frames it uses/provides (one only) */ 00069 /*! Prepare an input stream for playback. Return 0 on success, -1 on error. 00070 * The FILE is already open (in s->f) so this function only needs to perform 00071 * any applicable validity checks on the file. If none is required, the 00072 * function can be omitted. 00073 */ 00074 int (*open)(struct ast_filestream *s); 00075 /*! Prepare a stream for output, and comment it appropriately if applicable. 00076 * Return 0 on success, -1 on error. Same as the open, the FILE is already 00077 * open so the function just needs to prepare any header and other fields, 00078 * if any. The function can be omitted if nothing is needed. 00079 */ 00080 int (*rewrite)(struct ast_filestream *s, const char *comment); 00081 /*! Write a frame to a channel */ 00082 int (*write)(struct ast_filestream *, struct ast_frame *); 00083 /*! seek num samples into file, whence - like a normal seek but with offset in samples */ 00084 int (*seek)(struct ast_filestream *, off_t, int); 00085 int (*trunc)(struct ast_filestream *fs); /*! trunc file to current position */ 00086 off_t (*tell)(struct ast_filestream *fs); /*! tell current position */ 00087 /*! Read the next frame from the filestream (if available) and report 00088 * when to get next frame (in samples) 00089 */ 00090 struct ast_frame * (*read)(struct ast_filestream *, int *whennext); 00091 /*! Do any closing actions, if any. The descriptor and structure are closed 00092 * and destroyed by the generic routines, so they must not be done here. */ 00093 void (*close)(struct ast_filestream *); 00094 char * (*getcomment)(struct ast_filestream *); /*! Retrieve file comment */ 00095 00096 AST_LIST_ENTRY(ast_format) list; /*! Link */ 00097 00098 /*! 00099 * If the handler needs a buffer (for read, typically) 00100 * and/or a private descriptor, put here the 00101 * required size (in bytes) and the support routine will allocate them 00102 * for you, pointed by s->buf and s->private, respectively. 00103 * When allocating a buffer, remember to leave AST_FRIENDLY_OFFSET 00104 * spare bytes at the bginning. 00105 */ 00106 int buf_size; /*! size of frame buffer, if any, aligned to 8 bytes. */ 00107 int desc_size; /*! size of private descriptor, if any */ 00108 00109 struct ast_module *module; 00110 }; 00111 00112 /* 00113 * This structure is allocated by file.c in one chunk, 00114 * together with buf_size and desc_size bytes of memory 00115 * to be used for private purposes (e.g. buffers etc.) 00116 */ 00117 struct ast_filestream { 00118 /*! Everybody reserves a block of AST_RESERVED_POINTERS pointers for us */ 00119 struct ast_format *fmt; /* need to write to the lock and usecnt */ 00120 int flags; 00121 mode_t mode; 00122 char *filename; 00123 char *realfilename; 00124 /*! Video file stream */ 00125 struct ast_filestream *vfs; 00126 /*! Transparently translate from another format -- just once */ 00127 struct ast_trans_pvt *trans; 00128 struct ast_tranlator_pvt *tr; 00129 int lastwriteformat; 00130 int lasttimeout; 00131 struct ast_channel *owner; 00132 FILE *f; 00133 struct ast_frame fr; /* frame produced by read, typically */ 00134 char *buf; /* buffer pointed to by ast_frame; */ 00135 void *private; /* pointer to private buffer */ 00136 }; 00137 00138 #define SEEK_FORCECUR 10 00139 00140 /*! Register a new file format capability 00141 * Adds a format to Asterisk's format abilities. 00142 * returns 0 on success, -1 on failure 00143 */ 00144 int __ast_format_register(const struct ast_format *f, struct ast_module *mod); 00145 #define ast_format_register(f) __ast_format_register(f, ast_module_info->self) 00146 00147 /*! Unregisters a file format */ 00148 /*! 00149 * \param name the name of the format you wish to unregister 00150 * Unregisters a format based on the name of the format. 00151 * Returns 0 on success, -1 on failure to unregister 00152 */ 00153 int ast_format_unregister(const char *name); 00154 00155 /*! Streams a file */ 00156 /*! 00157 * \param c channel to stream the file to 00158 * \param filename the name of the file you wish to stream, minus the extension 00159 * \param preflang the preferred language you wish to have the file streamed to you in 00160 * Prepares a channel for the streaming of a file. To start the stream, afterward do a ast_waitstream() on the channel 00161 * Also, it will stop any existing streams on the channel. 00162 * Returns 0 on success, or -1 on failure. 00163 */ 00164 int ast_streamfile(struct ast_channel *c, const char *filename, const char *preflang); 00165 00166 /* 00167 * if the file name is non-empty, try to play it. 00168 * Return 0 if success, -1 if error, digit if interrupted by a digit. 00169 * If digits == "" then we can simply check for non-zero. 00170 */ 00171 int ast_stream_and_wait(struct ast_channel *chan, const char *file, 00172 const char *language, const char *digits); 00173 00174 /*! Stops a stream */ 00175 /*! 00176 * \param c The channel you wish to stop playback on 00177 * Stop playback of a stream 00178 * Returns 0 regardless 00179 */ 00180 int ast_stopstream(struct ast_channel *c); 00181 00182 /*! Checks for the existence of a given file */ 00183 /*! 00184 * \param filename name of the file you wish to check, minus the extension 00185 * \param fmt the format you wish to check (the extension) 00186 * \param preflang (the preferred language you wisht to find the file in) 00187 * See if a given file exists in a given format. If fmt is NULL, any format is accepted. 00188 * Returns -1 if file does not exist, non-zero positive otherwise. 00189 */ 00190 int ast_fileexists(const char *filename, const char *fmt, const char *preflang); 00191 00192 /*! Renames a file */ 00193 /*! 00194 * \param oldname the name of the file you wish to act upon (minus the extension) 00195 * \param newname the name you wish to rename the file to (minus the extension) 00196 * \param fmt the format of the file 00197 * Rename a given file in a given format, or if fmt is NULL, then do so for all 00198 * Returns -1 on failure 00199 */ 00200 int ast_filerename(const char *oldname, const char *newname, const char *fmt); 00201 00202 /*! Deletes a file */ 00203 /*! 00204 * \param filename name of the file you wish to delete (minus the extension) 00205 * \param fmt of the file 00206 * Delete a given file in a given format, or if fmt is NULL, then do so for all 00207 */ 00208 int ast_filedelete(const char *filename, const char *fmt); 00209 00210 /*! Copies a file */ 00211 /*! 00212 * \param oldname name of the file you wish to copy (minus extension) 00213 * \param newname name you wish the file to be copied to (minus extension) 00214 * \param fmt the format of the file 00215 * Copy a given file in a given format, or if fmt is NULL, then do so for all 00216 */ 00217 int ast_filecopy(const char *oldname, const char *newname, const char *fmt); 00218 00219 /*! Waits for a stream to stop or digit to be pressed */ 00220 /*! 00221 * \param c channel to waitstream on 00222 * \param breakon string of DTMF digits to break upon 00223 * Begins playback of a stream... 00224 * Wait for a stream to stop or for any one of a given digit to arrive, Returns 0 00225 * if the stream finishes, the character if it was interrupted, and -1 on error 00226 */ 00227 int ast_waitstream(struct ast_channel *c, const char *breakon); 00228 00229 /*! Waits for a stream to stop or digit matching a valid one digit exten to be pressed */ 00230 /*! 00231 * \param c channel to waitstream on 00232 * \param context string of context to match digits to break upon 00233 * Begins playback of a stream... 00234 * Wait for a stream to stop or for any one of a valid extension digit to arrive, Returns 0 00235 * if the stream finishes, the character if it was interrupted, and -1 on error 00236 */ 00237 int ast_waitstream_exten(struct ast_channel *c, const char *context); 00238 00239 /*! Same as waitstream but allows stream to be forwarded or rewound */ 00240 /*! 00241 * \param c channel to waitstream on 00242 * \param breakon string of DTMF digits to break upon 00243 * \param forward DTMF digit to fast forward upon 00244 * \param rewind DTMF digit to rewind upon 00245 * \param ms How many miliseconds to skip forward/back 00246 * Begins playback of a stream... 00247 * Wait for a stream to stop or for any one of a given digit to arrive, Returns 0 00248 * if the stream finishes, the character if it was interrupted, and -1 on error 00249 */ 00250 int ast_waitstream_fr(struct ast_channel *c, const char *breakon, const char *forward, const char *rewind, int ms); 00251 00252 /* Same as waitstream, but with audio output to fd and monitored fd checking. Returns 00253 1 if monfd is ready for reading */ 00254 int ast_waitstream_full(struct ast_channel *c, const char *breakon, int audiofd, int monfd); 00255 00256 /*! Starts reading from a file */ 00257 /*! 00258 * \param filename the name of the file to read from 00259 * \param type format of file you wish to read from 00260 * \param comment comment to go with 00261 * \param flags file flags 00262 * \param check (unimplemented, hence negligible) 00263 * \param mode Open mode 00264 * Open an incoming file stream. flags are flags for the open() command, and 00265 * if check is non-zero, then it will not read a file if there are any files that 00266 * start with that name and have an extension 00267 * Please note, this is a blocking function. Program execution will not return until ast_waitstream completes it's execution. 00268 * Returns a struct ast_filestream on success, NULL on failure 00269 */ 00270 struct ast_filestream *ast_readfile(const char *filename, const char *type, const char *comment, int flags, int check, mode_t mode); 00271 00272 /*! Starts writing a file */ 00273 /*! 00274 * \param filename the name of the file to write to 00275 * \param type format of file you wish to write out to 00276 * \param comment comment to go with 00277 * \param flags output file flags 00278 * \param check (unimplemented, hence negligible) 00279 * \param mode Open mode 00280 * Create an outgoing file stream. oflags are flags for the open() command, and 00281 * if check is non-zero, then it will not write a file if there are any files that 00282 * start with that name and have an extension 00283 * Please note, this is a blocking function. Program execution will not return until ast_waitstream completes it's execution. 00284 * Returns a struct ast_filestream on success, NULL on failure 00285 */ 00286 struct ast_filestream *ast_writefile(const char *filename, const char *type, const char *comment, int flags, int check, mode_t mode); 00287 00288 /*! Writes a frame to a stream */ 00289 /*! 00290 * \param fs filestream to write to 00291 * \param f frame to write to the filestream 00292 * Send a frame to a filestream -- note: does NOT free the frame, call ast_frfree manually 00293 * Returns 0 on success, -1 on failure. 00294 */ 00295 int ast_writestream(struct ast_filestream *fs, struct ast_frame *f); 00296 00297 /*! Closes a stream */ 00298 /*! 00299 * \param f filestream to close 00300 * Close a playback or recording stream 00301 * Returns 0 on success, -1 on failure 00302 */ 00303 int ast_closestream(struct ast_filestream *f); 00304 00305 /*! Opens stream for use in seeking, playing */ 00306 /*! 00307 * \param chan channel to work with 00308 * \param filename to use 00309 * \param preflang prefered language to use 00310 * Returns a ast_filestream pointer if it opens the file, NULL on error 00311 */ 00312 struct ast_filestream *ast_openstream(struct ast_channel *chan, const char *filename, const char *preflang); 00313 00314 /*! Opens stream for use in seeking, playing */ 00315 /*! 00316 * \param chan channel to work with 00317 * \param filename to use 00318 * \param preflang prefered language to use 00319 * \param asis if set, don't clear generators 00320 * Returns a ast_filestream pointer if it opens the file, NULL on error 00321 */ 00322 struct ast_filestream *ast_openstream_full(struct ast_channel *chan, const char *filename, const char *preflang, int asis); 00323 /*! Opens stream for use in seeking, playing */ 00324 /*! 00325 * \param chan channel to work with 00326 * \param filename to use 00327 * \param preflang prefered language to use 00328 * Returns a ast_filestream pointer if it opens the file, NULL on error 00329 */ 00330 struct ast_filestream *ast_openvstream(struct ast_channel *chan, const char *filename, const char *preflang); 00331 00332 /*! Applys a open stream to a channel. */ 00333 /*! 00334 * \param chan channel to work 00335 * \param s ast_filestream to apply 00336 * Returns 0 for success, -1 on failure 00337 */ 00338 int ast_applystream(struct ast_channel *chan, struct ast_filestream *s); 00339 00340 /*! play a open stream on a channel. */ 00341 /*! 00342 * \param s filestream to play 00343 * Returns 0 for success, -1 on failure 00344 */ 00345 int ast_playstream(struct ast_filestream *s); 00346 00347 /*! Seeks into stream */ 00348 /*! 00349 * \param fs ast_filestream to perform seek on 00350 * \param sample_offset numbers of samples to seek 00351 * \param whence SEEK_SET, SEEK_CUR, SEEK_END 00352 * Returns 0 for success, or -1 for error 00353 */ 00354 int ast_seekstream(struct ast_filestream *fs, off_t sample_offset, int whence); 00355 00356 /*! Trunc stream at current location */ 00357 /*! 00358 * \param fs filestream to act on 00359 * Returns 0 for success, or -1 for error 00360 */ 00361 int ast_truncstream(struct ast_filestream *fs); 00362 00363 /*! Fast forward stream ms */ 00364 /*! 00365 * \param fs filestream to act on 00366 * \param ms milliseconds to move 00367 * Returns 0 for success, or -1 for error 00368 */ 00369 int ast_stream_fastforward(struct ast_filestream *fs, off_t ms); 00370 00371 /*! Rewind stream ms */ 00372 /*! 00373 * \param fs filestream to act on 00374 * \param ms milliseconds to move 00375 * Returns 0 for success, or -1 for error 00376 */ 00377 int ast_stream_rewind(struct ast_filestream *fs, off_t ms); 00378 00379 /*! Tell where we are in a stream */ 00380 /*! 00381 * \param fs fs to act on 00382 * Returns a long as a sample offset into stream 00383 */ 00384 off_t ast_tellstream(struct ast_filestream *fs); 00385 00386 /*! Read a frame from a filestream */ 00387 /*! 00388 * \param s ast_filestream to act on 00389 * Returns a frame or NULL if read failed 00390 */ 00391 struct ast_frame *ast_readframe(struct ast_filestream *s); 00392 00393 /*! Initialize file stuff */ 00394 /*! 00395 * Initializes all the various file stuff. Basically just registers the cli stuff 00396 * Returns 0 all the time 00397 */ 00398 int ast_file_init(void); 00399 00400 00401 #define AST_RESERVED_POINTERS 20 00402 00403 #if defined(__cplusplus) || defined(c_plusplus) 00404 } 00405 #endif 00406 00407 #endif /* _ASTERISK_FILE_H */