Fri Jul 24 00:40:55 2009

Asterisk developer's documentation


file.h

Go to the documentation of this file.
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 */

Generated on Fri Jul 24 00:40:55 2009 for Asterisk - the Open Source PBX by  doxygen 1.4.7