Sat Aug 6 00:39:28 2011

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  */
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 */

Generated on Sat Aug 6 00:39:28 2011 for Asterisk - the Open Source PBX by  doxygen 1.4.7