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 Header for providers of file and format handling routines. 00021 * Clients of these routines should include "asterisk/file.h" instead. 00022 */ 00023 00024 #ifndef _ASTERISK_MOD_FORMAT_H 00025 #define _ASTERISK_MOD_FORMAT_H 00026 00027 #include "asterisk/file.h" 00028 #include "asterisk/frame.h" 00029 00030 #if defined(__cplusplus) || defined(c_plusplus) 00031 extern "C" { 00032 #endif 00033 00034 /*! \brief 00035 * Each supported file format is described by the following structure. 00036 * 00037 * Not all are necessary, the support routine implement default 00038 * values for some of them. 00039 * A handler typically fills a structure initializing the desired 00040 * fields, and then calls ast_format_register() with the (readonly) 00041 * structure as an argument. 00042 */ 00043 struct ast_format { 00044 char name[80]; /*!< Name of format */ 00045 char exts[80]; /*!< Extensions (separated by | if more than one) 00046 this format can read. First is assumed for writing (e.g. .mp3) */ 00047 int format; /*!< Format of frames it uses/provides (one only) */ 00048 /*! 00049 * \brief Prepare an input stream for playback. 00050 * \return 0 on success, -1 on error. 00051 * The FILE is already open (in s->f) so this function only needs to perform 00052 * any applicable validity checks on the file. If none is required, the 00053 * function can be omitted. 00054 */ 00055 int (*open)(struct ast_filestream *s); 00056 /*! 00057 * \brief Prepare a stream for output, and comment it appropriately if applicable. 00058 * \return 0 on success, -1 on error. 00059 * Same as the open, the FILE is already open so the function just needs to 00060 * prepare any header and other fields, if any. 00061 * The function can be omitted if nothing is needed. 00062 */ 00063 int (*rewrite)(struct ast_filestream *s, const char *comment); 00064 /*! Write a frame to a channel */ 00065 int (*write)(struct ast_filestream *, struct ast_frame *); 00066 /*! seek num samples into file, whence - like a normal seek but with offset in samples */ 00067 int (*seek)(struct ast_filestream *, off_t, int); 00068 int (*trunc)(struct ast_filestream *fs); /*!< trunc file to current position */ 00069 off_t (*tell)(struct ast_filestream *fs); /*!< tell current position */ 00070 /*! Read the next frame from the filestream (if available) and report 00071 * when to get next frame (in samples) 00072 */ 00073 struct ast_frame * (*read)(struct ast_filestream *, int *whennext); 00074 /*! Do any closing actions, if any. The descriptor and structure are closed 00075 * and destroyed by the generic routines, so they must not be done here. */ 00076 void (*close)(struct ast_filestream *); 00077 char * (*getcomment)(struct ast_filestream *); /*!< Retrieve file comment */ 00078 00079 AST_LIST_ENTRY(ast_format) list; /*!< Link */ 00080 00081 /*! 00082 * If the handler needs a buffer (for read, typically) 00083 * and/or a private descriptor, put here the 00084 * required size (in bytes) and the support routine will allocate them 00085 * for you, pointed by s->buf and s->private, respectively. 00086 * When allocating a buffer, remember to leave AST_FRIENDLY_OFFSET 00087 * spare bytes at the bginning. 00088 */ 00089 int buf_size; /*!< size of frame buffer, if any, aligned to 8 bytes. */ 00090 int desc_size; /*!< size of private descriptor, if any */ 00091 00092 struct ast_module *module; 00093 }; 00094 00095 /*! \brief 00096 * This structure is allocated by file.c in one chunk, 00097 * together with buf_size and desc_size bytes of memory 00098 * to be used for private purposes (e.g. buffers etc.) 00099 */ 00100 struct ast_filestream { 00101 /*! Everybody reserves a block of AST_RESERVED_POINTERS pointers for us */ 00102 struct ast_format *fmt; /* need to write to the lock and usecnt */ 00103 int flags; 00104 mode_t mode; 00105 char *filename; 00106 char *realfilename; 00107 /*! Video file stream */ 00108 struct ast_filestream *vfs; 00109 /*! Transparently translate from another format -- just once */ 00110 struct ast_trans_pvt *trans; 00111 struct ast_tranlator_pvt *tr; 00112 int lastwriteformat; 00113 int lasttimeout; 00114 struct ast_channel *owner; 00115 FILE *f; 00116 struct ast_frame fr; /*!< frame produced by read, typically */ 00117 char *buf; /*!< buffer pointed to by ast_frame; */ 00118 void *_private; /*!< pointer to private buffer */ 00119 const char *orig_chan_name; 00120 char *write_buffer; 00121 }; 00122 00123 /*! 00124 * \brief Register a new file format capability. 00125 * Adds a format to Asterisk's format abilities. 00126 * \retval 0 on success 00127 * \retval -1 on failure 00128 */ 00129 int __ast_format_register(const struct ast_format *f, struct ast_module *mod); 00130 #define ast_format_register(f) __ast_format_register(f, ast_module_info->self) 00131 00132 /*! 00133 * \brief Unregisters a file format 00134 * \param name the name of the format you wish to unregister 00135 * Unregisters a format based on the name of the format. 00136 * \retval 0 on success 00137 * \retval -1 on failure to unregister 00138 */ 00139 int ast_format_unregister(const char *name); 00140 00141 #if defined(__cplusplus) || defined(c_plusplus) 00142 } 00143 #endif 00144 00145 #endif /* _ASTERISK_MOD_FORMAT_H */