media formats: re-architect handling of media for performance improvements
[asterisk/asterisk.git] / include / asterisk / slinfactory.h
1 /*
2  * Asterisk -- An open source telephony toolkit.
3  *
4  * Copyright (C) 2005, Anthony Minessale II
5  *
6  * Anthony Minessale <anthmct@yahoo.com>
7  *
8  * See http://www.asterisk.org for more information about
9  * the Asterisk project. Please do not directly contact
10  * any of the maintainers of this project for assistance;
11  * the project provides a web site, mailing lists and IRC
12  * channels for your use.
13  *
14  * This program is free software, distributed under the terms of
15  * the GNU General Public License Version 2. See the LICENSE file
16  * at the top of the source tree.
17  */
18
19 /*! \file
20  * \brief A machine to gather up arbitrary frames and convert them
21  * to raw slinear on demand.
22  */
23
24 #ifndef _ASTERISK_SLINFACTORY_H
25 #define _ASTERISK_SLINFACTORY_H
26
27 #include "asterisk/format.h"
28
29 #if defined(__cplusplus) || defined(c_plusplus)
30 extern "C" {
31 #endif
32
33 #define AST_SLINFACTORY_MAX_HOLD 1280
34
35 struct ast_slinfactory {
36         AST_LIST_HEAD_NOLOCK(, ast_frame) queue; /*!< A list of unaltered frames */
37         struct ast_trans_pvt *trans;             /*!< Translation path that converts fed frames into signed linear */
38         short hold[AST_SLINFACTORY_MAX_HOLD];    /*!< Hold for audio that no longer belongs to a frame (ie: if only some samples were taken from a frame) */
39         short *offset;                           /*!< Offset into the hold where audio begins */
40         size_t holdlen;                          /*!< Number of samples currently in the hold */
41         unsigned int size;                       /*!< Number of samples currently in the factory */
42         struct ast_format *format;               /*!< Current format the translation path is converting from */
43         struct ast_format *output_format;        /*!< The output format desired */
44 };
45
46 /*!
47  * \brief Initialize a slinfactory
48  *
49  * \param sf The slinfactory to initialize
50  *
51  * \return Nothing
52  */
53 void ast_slinfactory_init(struct ast_slinfactory *sf);
54
55 /*!
56  * \brief Initialize a slinfactory
57  *
58  * \param sf The slinfactory to initialize
59  * \param slin_out the slinear output format desired.
60  *
61  * \return 0 on success, non-zero on failure
62  */
63 int ast_slinfactory_init_with_format(struct ast_slinfactory *sf, struct ast_format *slin_out);
64
65 /*!
66  * \brief Destroy the contents of a slinfactory
67  *
68  * \param sf The slinfactory that is no longer needed
69  *
70  * This function will free any memory allocated for the contents of the
71  * slinfactory.  It does not free the slinfactory itself.  If the sf is
72  * malloc'd, then it must be explicitly free'd after calling this function.
73  *
74  * \return Nothing
75  */
76 void ast_slinfactory_destroy(struct ast_slinfactory *sf);
77
78 /*!
79  * \brief Feed audio into a slinfactory
80  *
81  * \param sf The slinfactory to feed into
82  * \param f Frame containing audio to feed in
83  *
84  * \return Number of frames currently in factory
85  */
86 int ast_slinfactory_feed(struct ast_slinfactory *sf, struct ast_frame *f);
87
88 /*!
89  * \brief Read samples from a slinfactory
90  *
91  * \param sf The slinfactory to read from
92  * \param buf Buffer to put samples into
93  * \param samples Number of samples wanted
94  *
95  * \return Number of samples read
96  */
97 int ast_slinfactory_read(struct ast_slinfactory *sf, short *buf, size_t samples);
98
99 /*!
100  * \brief Retrieve number of samples currently in a slinfactory
101  *
102  * \param sf The slinfactory to peek into
103  *
104  * \return Number of samples in slinfactory
105  */
106 unsigned int ast_slinfactory_available(const struct ast_slinfactory *sf);
107
108 /*!
109  * \brief Flush the contents of a slinfactory
110  *
111  * \param sf The slinfactory to flush
112  *
113  * \return Nothing
114  */
115 void ast_slinfactory_flush(struct ast_slinfactory *sf);
116
117 #if defined(__cplusplus) || defined(c_plusplus)
118 }
119 #endif
120
121 #endif /* _ASTERISK_SLINFACTORY_H */