Mon May 14 04:42:55 2007

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

Generated on Mon May 14 04:42:55 2007 for Asterisk - the Open Source PBX by  doxygen 1.5.1