Asterisk.org: Developer Documentation (28 Oct 2009)

Wed Oct 28 15:47:56 2009

## Asterisk developer's documentation

# translate.h

Go to the documentation of this file.

    00001 /*
    00002  * Asterisk -- An open source telephony toolkit.
    00003  *
    00004  * Copyright (C) 1999 - 2005, 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 Translate via the use of pseudo channels
    00021  */
    00022
    00023 #ifndef _ASTERISK_TRANSLATE_H
    00024 #define _ASTERISK_TRANSLATE_H
    00025
    00026 #define MAX_FORMAT 32
    00027
    00028 #if defined(__cplusplus) || defined(c_plusplus)
    00029 extern "C" {
    00030 #endif
    00031
    00032 #include "asterisk/frame.h"
    00033 #include "asterisk/plc.h"
    00034
    00035 /* Declared by individual translators */
    00036 struct ast_translator_pvt;
    00037
    00038 /*! data structure associated with a translator */
    00039 struct ast_translator {
    00040    /*! Name of translator */
    00041    char name[80];
    00042    /*! Source format */
    00043    int srcfmt;
    00044    /*! Destination format */
    00045    int dstfmt;
    00046    /*! Private data associated with the translator */
    00047    struct ast_translator_pvt *(*newpvt)(void);
    00048    /*! Input frame callback */
    00049    int (*framein)(struct ast_translator_pvt *pvt, struct ast_frame *in);
    00050    /*! Output frame callback */
    00051    struct ast_frame * (*frameout)(struct ast_translator_pvt *pvt);
    00052    /*! Destroy translator callback */
    00053    void (*destroy)(struct ast_translator_pvt *pvt);
    00054    /* For performance measurements */
    00055    /*! Generate an example frame */
    00056    struct ast_frame * (*sample)(void);
    00057    /*! Cost in milliseconds for encoding/decoding 1 second of sound */
    00058    int cost;
    00059    /*! For linking, not to be modified by the translator */
    00060    struct ast_translator *next;
    00061 };
    00062
    00063 struct ast_trans_pvt;
    00064
    00065 /*! Register a translator */
    00066 /*!
    00067  * \param t populated ast_translator structure
    00068  * This registers a codec translator with asterisk
    00069  * Returns 0 on success, -1 on failure
    00070  */
    00071 extern int ast_register_translator(struct ast_translator *t);
    00072
    00073 /*! Unregister a translator */
    00074 /*!
    00075  * \param t translator to unregister
    00076  * Unregisters the given tranlator
    00077  * Returns 0 on success, -1 on failure
    00078  */
    00079 extern int ast_unregister_translator(struct ast_translator *t);
    00080
    00081 /*! Chooses the best translation path */
    00082 /*!
    00083  * Given a list of sources, and a designed destination format, which should
    00084    I choose? Returns 0 on success, -1 if no path could be found.  Modifies
    00085    dests and srcs in place
    00086    */
    00087 extern int ast_translator_best_choice(int *dsts, int *srcs);
    00088
    00089 /*!Builds a translator path */
    00090 /*!
    00091  * \param dest destination format
    00092  * \param source source format
    00093  * Build a path (possibly NULL) from source to dest
    00094  * Returns ast_trans_pvt on success, NULL on failure
    00095  * */
    00096 extern struct ast_trans_pvt *ast_translator_build_path(int dest, int source);
    00097
    00098 /*! Frees a translator path */
    00099 /*!
    00100  * \param tr translator path to get rid of
    00101  * Frees the given translator path structure
    00102  */
    00103 extern void ast_translator_free_path(struct ast_trans_pvt *tr);
    00104
    00105 /*! translates one or more frames */
    00106 /*!
    00107  * \param tr translator structure to use for translation
    00108  * \param f frame to translate
    00109  * \param consume Whether or not to free the original frame
    00110  * Apply an input frame into the translator and receive zero or one output frames.  Consume
    00111  * determines whether the original frame should be freed
    00112  * Returns an ast_frame of the new translation format on success, NULL on failure
    00113  */
    00114 extern struct ast_frame *ast_translate(struct ast_trans_pvt *tr, struct ast_frame *f, int consume);
    00115
    00116 #if defined(__cplusplus) || defined(c_plusplus)
    00117 }
    00118 #endif
    00119
    00120 #endif /* _ASTERISK_TRANSLATE_H */