Thu Feb 5 16:25:46 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  */
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    /* pointer to private buffer */
00136    union {
00137       void *_private;
00138 #if !defined(__cplusplus) && !defined(c_plusplus)
00139       void *private attribute_deprecated;
00140 #endif
00141    };
00142    const char *orig_chan_name;
00143 };
00144 
00145 #define SEEK_FORCECUR   10
00146    
00147 /*! Register a new file format capability
00148  * Adds a format to Asterisk's format abilities.
00149  * returns 0 on success, -1 on failure
00150  */
00151 int __ast_format_register(const struct ast_format *f, struct ast_module *mod);
00152 #define ast_format_register(f) __ast_format_register(f, ast_module_info->self)
00153 
00154 /*! Unregisters a file format */
00155 /*!
00156  * \param name the name of the format you wish to unregister
00157  * Unregisters a format based on the name of the format.
00158  * Returns 0 on success, -1 on failure to unregister
00159  */
00160 int ast_format_unregister(const char *name);
00161 
00162 /*! Streams a file */
00163 /*!
00164  * \param c channel to stream the file to
00165  * \param filename the name of the file you wish to stream, minus the extension
00166  * \param preflang the preferred language you wish to have the file streamed to you in
00167  * Prepares a channel for the streaming of a file.  To start the stream, afterward do a ast_waitstream() on the channel
00168  * Also, it will stop any existing streams on the channel.
00169  * Returns 0 on success, or -1 on failure.
00170  */
00171 int ast_streamfile(struct ast_channel *c, const char *filename, const char *preflang);
00172 
00173 /*
00174  * if the file name is non-empty, try to play it.
00175  * Return 0 if success, -1 if error, digit if interrupted by a digit.
00176  * If digits == "" then we can simply check for non-zero.
00177  */
00178 int ast_stream_and_wait(struct ast_channel *chan, const char *file,
00179    const char *language, const char *digits);
00180 
00181 /*! 
00182  * \brief Stops a stream 
00183  *
00184  * \param c The channel you wish to stop playback on
00185  *
00186  * Stop playback of a stream 
00187  *
00188  * \retval 0 always
00189  *
00190  * \note The channel does not need to be locked before calling this function.
00191  */
00192 int ast_stopstream(struct ast_channel *c);
00193 
00194 /*! Checks for the existence of a given file */
00195 /*!
00196  * \param filename name of the file you wish to check, minus the extension
00197  * \param fmt the format you wish to check (the extension)
00198  * \param preflang (the preferred language you wisht to find the file in)
00199  * See if a given file exists in a given format.  If fmt is NULL,  any format is accepted.
00200  * Returns -1 if file does not exist, non-zero positive otherwise.
00201  */
00202 int ast_fileexists(const char *filename, const char *fmt, const char *preflang);
00203 
00204 /*! Renames a file */
00205 /*! 
00206  * \param oldname the name of the file you wish to act upon (minus the extension)
00207  * \param newname the name you wish to rename the file to (minus the extension)
00208  * \param fmt the format of the file
00209  * Rename a given file in a given format, or if fmt is NULL, then do so for all 
00210  * Returns -1 on failure
00211  */
00212 int ast_filerename(const char *oldname, const char *newname, const char *fmt);
00213 
00214 /*! Deletes a file */
00215 /*! 
00216  * \param filename name of the file you wish to delete (minus the extension)
00217  * \param fmt of the file
00218  * Delete a given file in a given format, or if fmt is NULL, then do so for all 
00219  */
00220 int ast_filedelete(const char *filename, const char *fmt);
00221 
00222 /*! Copies a file */
00223 /*!
00224  * \param oldname name of the file you wish to copy (minus extension)
00225  * \param newname name you wish the file to be copied to (minus extension)
00226  * \param fmt the format of the file
00227  * Copy a given file in a given format, or if fmt is NULL, then do so for all 
00228  */
00229 int ast_filecopy(const char *oldname, const char *newname, const char *fmt);
00230 
00231 /*! Waits for a stream to stop or digit to be pressed */
00232 /*!
00233  * \param c channel to waitstream on
00234  * \param breakon string of DTMF digits to break upon
00235  * Begins playback of a stream...
00236  * Wait for a stream to stop or for any one of a given digit to arrive,  Returns 0 
00237  * if the stream finishes, the character if it was interrupted, and -1 on error 
00238  */
00239 int ast_waitstream(struct ast_channel *c, const char *breakon);
00240 
00241 /*! Waits for a stream to stop or digit matching a valid one digit exten to be pressed */
00242 /*!
00243  * \param c channel to waitstream on
00244  * \param context string of context to match digits to break upon
00245  * Begins playback of a stream...
00246  * Wait for a stream to stop or for any one of a valid extension digit to arrive,  Returns 0 
00247  * if the stream finishes, the character if it was interrupted, and -1 on error 
00248  */
00249 int ast_waitstream_exten(struct ast_channel *c, const char *context);
00250 
00251 /*! Same as waitstream but allows stream to be forwarded or rewound */
00252 /*!
00253  * \param c channel to waitstream on
00254  * \param breakon string of DTMF digits to break upon
00255  * \param forward DTMF digit to fast forward upon
00256  * \param rewind DTMF digit to rewind upon
00257  * \param ms How many miliseconds to skip forward/back
00258  * Begins playback of a stream...
00259  * Wait for a stream to stop or for any one of a given digit to arrive,  Returns 0 
00260  * if the stream finishes, the character if it was interrupted, and -1 on error 
00261  */
00262 int ast_waitstream_fr(struct ast_channel *c, const char *breakon, const char *forward, const char *rewind, int ms);
00263 
00264 /* Same as waitstream, but with audio output to fd and monitored fd checking.  Returns
00265    1 if monfd is ready for reading */
00266 int ast_waitstream_full(struct ast_channel *c, const char *breakon, int audiofd, int monfd);
00267 
00268 /*! Starts reading from a file */
00269 /*!
00270  * \param filename the name of the file to read from
00271  * \param type format of file you wish to read from
00272  * \param comment comment to go with
00273  * \param flags file flags
00274  * \param check (unimplemented, hence negligible)
00275  * \param mode Open mode
00276  * Open an incoming file stream.  flags are flags for the open() command, and 
00277  * if check is non-zero, then it will not read a file if there are any files that 
00278  * start with that name and have an extension
00279  * Please note, this is a blocking function.  Program execution will not return until ast_waitstream completes it's execution.
00280  * Returns a struct ast_filestream on success, NULL on failure
00281  */
00282 struct ast_filestream *ast_readfile(const char *filename, const char *type, const char *comment, int flags, int check, mode_t mode);
00283 
00284 /*! Starts writing a file */
00285 /*!
00286  * \param filename the name of the file to write to
00287  * \param type format of file you wish to write out to
00288  * \param comment comment to go with
00289  * \param flags output file flags
00290  * \param check (unimplemented, hence negligible)
00291  * \param mode Open mode
00292  * Create an outgoing file stream.  oflags are flags for the open() command, and 
00293  * if check is non-zero, then it will not write a file if there are any files that 
00294  * start with that name and have an extension
00295  * Please note, this is a blocking function.  Program execution will not return until ast_waitstream completes it's execution.
00296  * Returns a struct ast_filestream on success, NULL on failure
00297  */
00298 struct ast_filestream *ast_writefile(const char *filename, const char *type, const char *comment, int flags, int check, mode_t mode);
00299 
00300 /*! Writes a frame to a stream */
00301 /*! 
00302  * \param fs filestream to write to
00303  * \param f frame to write to the filestream
00304  * Send a frame to a filestream -- note: does NOT free the frame, call ast_frfree manually
00305  * Returns 0 on success, -1 on failure.
00306  */
00307 int ast_writestream(struct ast_filestream *fs, struct ast_frame *f);
00308 
00309 /*! Closes a stream */
00310 /*!
00311  * \param f filestream to close
00312  * Close a playback or recording stream
00313  * Returns 0 on success, -1 on failure
00314  */
00315 int ast_closestream(struct ast_filestream *f);
00316 
00317 /*! Opens stream for use in seeking, playing */
00318 /*!
00319  * \param chan channel to work with
00320  * \param filename to use
00321  * \param preflang prefered language to use
00322  * Returns a ast_filestream pointer if it opens the file, NULL on error
00323  */
00324 struct ast_filestream *ast_openstream(struct ast_channel *chan, const char *filename, const char *preflang);
00325 
00326 /*! Opens stream for use in seeking, playing */
00327 /*!
00328  * \param chan channel to work with
00329  * \param filename to use
00330  * \param preflang prefered language to use
00331  * \param asis if set, don't clear generators
00332  * Returns a ast_filestream pointer if it opens the file, NULL on error
00333  */
00334 struct ast_filestream *ast_openstream_full(struct ast_channel *chan, const char *filename, const char *preflang, int asis);
00335 /*! Opens stream for use in seeking, playing */
00336 /*!
00337  * \param chan channel to work with
00338  * \param filename to use
00339  * \param preflang prefered language to use
00340  * Returns a ast_filestream pointer if it opens the file, NULL on error
00341  */
00342 struct ast_filestream *ast_openvstream(struct ast_channel *chan, const char *filename, const char *preflang);
00343 
00344 /*! Applys a open stream to a channel. */
00345 /*!
00346  * \param chan channel to work
00347  * \param s ast_filestream to apply
00348  * Returns 0 for success, -1 on failure
00349  */
00350 int ast_applystream(struct ast_channel *chan, struct ast_filestream *s);
00351 
00352 /*! play a open stream on a channel. */
00353 /*!
00354  * \param s filestream to play
00355  * Returns 0 for success, -1 on failure
00356  */
00357 int ast_playstream(struct ast_filestream *s);
00358 
00359 /*! Seeks into stream */
00360 /*!
00361  * \param fs ast_filestream to perform seek on
00362  * \param sample_offset numbers of samples to seek
00363  * \param whence SEEK_SET, SEEK_CUR, SEEK_END 
00364  * Returns 0 for success, or -1 for error
00365  */
00366 int ast_seekstream(struct ast_filestream *fs, off_t sample_offset, int whence);
00367 
00368 /*! Trunc stream at current location */
00369 /*!
00370  * \param fs filestream to act on
00371  * Returns 0 for success, or -1 for error
00372  */
00373 int ast_truncstream(struct ast_filestream *fs);
00374 
00375 /*! Fast forward stream ms */
00376 /*!
00377  * \param fs filestream to act on
00378  * \param ms milliseconds to move
00379  * Returns 0 for success, or -1 for error
00380  */
00381 int ast_stream_fastforward(struct ast_filestream *fs, off_t ms);
00382 
00383 /*! Rewind stream ms */
00384 /*!
00385  * \param fs filestream to act on
00386  * \param ms milliseconds to move
00387  * Returns 0 for success, or -1 for error
00388  */
00389 int ast_stream_rewind(struct ast_filestream *fs, off_t ms);
00390 
00391 /*! Tell where we are in a stream */
00392 /*!
00393  * \param fs fs to act on
00394  * Returns a long as a sample offset into stream
00395  */
00396 off_t ast_tellstream(struct ast_filestream *fs);
00397 
00398 /*! Read a frame from a filestream */
00399 /*!
00400  * \param s ast_filestream to act on
00401  * Returns a frame or NULL if read failed
00402  */ 
00403 struct ast_frame *ast_readframe(struct ast_filestream *s);
00404 
00405 /*!\brief destroy a filestream using an ast_frame as input
00406  *
00407  * This is a hack that is used also by the ast_trans_pvt and
00408  * ast_dsp structures. When a structure contains an ast_frame
00409  * pointer as one of its fields. It may be that the frame is
00410  * still used after the outer structure is freed. This leads to
00411  * invalid memory accesses. This function allows for us to hold
00412  * off on destroying the ast_filestream until we are done using
00413  * the ast_frame pointer that is part of it
00414  *
00415  * \param fr The ast_frame that is part of an ast_filestream we wish
00416  * to free.
00417  */
00418 void ast_filestream_frame_freed(struct ast_frame *fr);
00419 
00420 /*! Initialize file stuff */
00421 /*!
00422  * Initializes all the various file stuff.  Basically just registers the cli stuff
00423  * Returns 0 all the time
00424  */
00425 int ast_file_init(void);
00426 
00427 
00428 #define AST_RESERVED_POINTERS 20
00429 
00430 #if defined(__cplusplus) || defined(c_plusplus)
00431 }
00432 #endif
00433 
00434 #endif /* _ASTERISK_FILE_H */

Generated on Thu Feb 5 16:25:46 2009 for Asterisk - the Open Source PBX by  doxygen 1.4.7