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