diff options
author | oej <oej@f38db490-d61c-443f-a65b-d21fe96a405b> | 2006-06-04 08:57:34 +0000 |
---|---|---|
committer | oej <oej@f38db490-d61c-443f-a65b-d21fe96a405b> | 2006-06-04 08:57:34 +0000 |
commit | 275d3b04c46b0551bb15e6ae5dc237bc993d94ce (patch) | |
tree | 32f5bc579477a4c8e5c0fa8bbef1a220d9560afc /include/asterisk/translate.h | |
parent | f4dbdf8060b875202f7ce1c10aaf6a6931592983 (diff) |
Doxygen improvements
git-svn-id: http://svn.digium.com/svn/asterisk/trunk@31979 f38db490-d61c-443f-a65b-d21fe96a405b
Diffstat (limited to 'include/asterisk/translate.h')
-rw-r--r-- | include/asterisk/translate.h | 79 |
1 files changed, 42 insertions, 37 deletions
diff --git a/include/asterisk/translate.h b/include/asterisk/translate.h index d1431b3be..182330ace 100644 --- a/include/asterisk/translate.h +++ b/include/asterisk/translate.h @@ -38,14 +38,15 @@ extern "C" { struct ast_trans_pvt; /* declared below */ -/*! +/*! \brief * Descriptor of a translator. Name, callbacks, and various options * related to run-time operation (size of buffers, auxiliary * descriptors, etc). + * * A coded registers itself by filling the relevant fields * of a structure and passing it as an argument to * ast_register_translator(). The structure should not be - * modified after a successful register(), and its address + * modified after a successful registration, and its address * must be used as an argument to ast_unregister_translator(). * * As a minimum, a translator should supply name, srcfmt and dstfmt, @@ -64,49 +65,52 @@ struct ast_trans_pvt; /* declared below */ * Generic plc is only available for dstfmt = SLINEAR */ struct ast_translator { - const char name[80]; /*! Name of translator */ - int srcfmt; /*! Source format (note: bit position, + const char name[80]; /*!< Name of translator */ + int srcfmt; /*!< Source format (note: bit position, converted to index during registration) */ - int dstfmt; /*! Destination format (note: bit position, + int dstfmt; /*!< Destination format (note: bit position, converted to index during registration) */ - /*! initialize private data associated with the translator */ - void *(*newpvt)(struct ast_trans_pvt *); + void *(*newpvt)(struct ast_trans_pvt *); /*!< initialize private data + associated with the translator */ - /*! Input frame callback. Store (and possibly convert) input frame. */ int (*framein)(struct ast_trans_pvt *pvt, struct ast_frame *in); + /*!< Input frame callback. Store + (and possibly convert) input frame. */ - /*! Output frame callback. Generate a frame with outbuf content. */ struct ast_frame * (*frameout)(struct ast_trans_pvt *pvt); + /*!< Output frame callback. Generate a frame + with outbuf content. */ - /*! cleanup private data, if needed (often unnecessary). */ void (*destroy)(struct ast_trans_pvt *pvt); + /*!< cleanup private data, if needed + (often unnecessary). */ - struct ast_frame * (*sample)(void); /*! Generate an example frame */ + struct ast_frame * (*sample)(void); /*!< Generate an example frame */ - /*! size of outbuf, in samples. Leave it 0 if you want the framein + /*! \brief size of outbuf, in samples. Leave it 0 if you want the framein * callback deal with the frame. Set it appropriately if you * want the code to checks if the incoming frame fits the * outbuf (this is e.g. required for plc). */ - int buffer_samples; /* size of outbuf, in samples */ + int buffer_samples; /*< size of outbuf, in samples */ - /*! size of outbuf, in bytes. Mandatory. The wrapper code will also + /*! \brief size of outbuf, in bytes. Mandatory. The wrapper code will also * allocate an AST_FRIENDLY_OFFSET space before. */ int buf_size; - int desc_size; /*! size of private descriptor in pvt->pvt, if any */ - int plc_samples; /* set to the plc block size if used, 0 otherwise */ - int useplc; /* current status of plc, changed at runtime */ + int desc_size; /*!< size of private descriptor in pvt->pvt, if any */ + int plc_samples; /*!< set to the plc block size if used, 0 otherwise */ + int useplc; /*!< current status of plc, changed at runtime */ - void *module; /* opaque reference to the parent module */ + void *module; /*!< opaque reference to the parent module */ - int cost; /*! Cost in milliseconds for encoding/decoding 1 second of sound */ - AST_LIST_ENTRY(ast_translator) list; /*! link field */ + int cost; /*!< Cost in milliseconds for encoding/decoding 1 second of sound */ + AST_LIST_ENTRY(ast_translator) list; /*!< link field */ }; -/* +/*! \brief * Default structure for translators, with the basic fields and buffers, * all allocated as part of the same chunk of memory. The buffer is * preceded by AST_FRIENDLY_OFFSET bytes in front of the user portion. @@ -126,18 +130,18 @@ struct ast_translator { */ struct ast_trans_pvt { struct ast_translator *t; - struct ast_frame f; /* used in frameout */ - int samples; /* samples available in outbuf */ - int datalen; /* actual space used in outbuf */ - void *pvt; /* more private data, if any */ - char *outbuf; /* the useful portion of the buffer */ - plc_state_t *plc; /* optional plc pointer */ - struct ast_trans_pvt *next; /* next in translator chain */ + struct ast_frame f; /*!< used in frameout */ + int samples; /*!< samples available in outbuf */ + int datalen; /*!< actual space used in outbuf */ + void *pvt; /*!< more private data, if any */ + char *outbuf; /*!< the useful portion of the buffer */ + plc_state_t *plc; /*!< optional plc pointer */ + struct ast_trans_pvt *next; /*!< next in translator chain */ struct timeval nextin; struct timeval nextout; }; -/* generic frameout function */ +/*! \brief generic frameout function */ struct ast_frame *ast_trans_frameout(struct ast_trans_pvt *pvt, int datalen, int samples); @@ -145,17 +149,17 @@ struct ast_trans_pvt; /*! * \brief Register a translator + * This registers a codec translator with asterisk * \param t populated ast_translator structure * \param module handle to the module that owns this translator - * This registers a codec translator with asterisk * \return 0 on success, -1 on failure */ int ast_register_translator(struct ast_translator *t, void *module); /*! * \brief Unregister a translator - * \param t translator to unregister * Unregisters the given tranlator + * \param t translator to unregister * \return 0 on success, -1 on failure */ int ast_unregister_translator(struct ast_translator *t); @@ -164,34 +168,35 @@ int ast_unregister_translator(struct ast_translator *t); * \brief Chooses the best translation path * * Given a list of sources, and a designed destination format, which should - * I choose? Returns 0 on success, -1 if no path could be found. Modifies - * dests and srcs in place + * I choose? + * \return Returns 0 on success, -1 if no path could be found. + * \note Modifies dests and srcs in place */ int ast_translator_best_choice(int *dsts, int *srcs); /*! * \brief Builds a translator path + * Build a path (possibly NULL) from source to dest * \param dest destination format * \param source source format - * Build a path (possibly NULL) from source to dest * \return ast_trans_pvt on success, NULL on failure * */ struct ast_trans_pvt *ast_translator_build_path(int dest, int source); /*! * \brief Frees a translator path - * \param tr translator path to get rid of * Frees the given translator path structure + * \param tr translator path to get rid of */ void ast_translator_free_path(struct ast_trans_pvt *tr); /*! * \brief translates one or more frames + * Apply an input frame into the translator and receive zero or one output frames. Consume + * determines whether the original frame should be freed * \param tr translator structure to use for translation * \param f frame to translate * \param consume Whether or not to free the original frame - * Apply an input frame into the translator and receive zero or one output frames. Consume - * determines whether the original frame should be freed * \return an ast_frame of the new translation format on success, NULL on failure */ struct ast_frame *ast_translate(struct ast_trans_pvt *tr, struct ast_frame *f, int consume); |