Asterisk - The Open Source Telephony Project  18.5.0
data_buffer.h
Go to the documentation of this file.
1 /*
2  * Asterisk -- An open source telephony toolkit.
3  *
4  * Copyright (C) 2018, Digium, Inc.
5  *
6  * Joshua Colp <[email protected]>
7  * Ben Ford <[email protected]>
8  *
9  * See http://www.asterisk.org for more information about
10  * the Asterisk project. Please do not directly contact
11  * any of the maintainers of this project for assistance;
12  * the project provides a web site, mailing lists and IRC
13  * channels for your use.
14  *
15  * This program is free software, distributed under the terms of
16  * the GNU General Public License Version 2. See the LICENSE file
17  * at the top of the source tree.
18  */
19 
20 /*!
21  * \file
22  * \brief Data Buffer API
23  *
24  * A data buffer acts as a ring buffer of data. It is given a fixed
25  * number of data packets to store (which may be dynamically changed).
26  * Given a number it will store a data packet at that position relative
27  * to the others. Given a number it will retrieve the given data packet
28  * if it is present. This is purposely a storage of arbitrary things so
29  * that it can be used for multiple things.
30  *
31  * \author Joshua Colp <[email protected]>
32  * \author Ben Ford <[email protected]>
33  */
34 
35 #ifndef _AST_DATA_BUFFER_H_
36 #define _AST_DATA_BUFFER_H_
37 
38 /*!
39  * \brief A buffer of data payloads.
40  */
41 struct ast_data_buffer;
42 
43 /*!
44  * \brief A callback function to free a data payload in a data buffer
45  *
46  * \param The data payload
47  */
48 typedef void (*ast_data_buffer_free_callback)(void *data);
49 
50 /*!
51  * \brief Allocate a data buffer
52  *
53  * \param free_fn Callback function to free a data payload
54  * \param size The maximum number of data payloads to contain in the data buffer
55  *
56  * \retval non-NULL success
57  * \retval NULL failure
58  *
59  * \note free_fn can be NULL. It is up to the consumer of this API to ensure that memory is
60  * managed appropriately.
61  *
62  * \since 15.4.0
63  */
64 struct ast_data_buffer *ast_data_buffer_alloc(ast_data_buffer_free_callback free_fn, size_t size);
65 
66 /*!
67  * \brief Resize a data buffer
68  *
69  * \param buffer The data buffer
70  * \param size The new maximum size of the data buffer
71  *
72  * \note If the data buffer is shrunk any old data payloads will be freed using the configured callback.
73  * The data buffer is flexible and can be used for multiple purposes. Therefore it is up to the
74  * caller of the function to know whether or not a buffer should have its size changed. Increasing
75  * the size of the buffer may make sense in some scenarios, but shrinking should always be handled
76  * with caution since data can be lost.
77  *
78  * \since 15.4.0
79  */
80 void ast_data_buffer_resize(struct ast_data_buffer *buffer, size_t size);
81 
82 /*!
83  * \brief Place a data payload at a position in the data buffer
84  *
85  * \param buffer The data buffer
86  * \param pos The position of the data payload
87  * \param payload The data payload
88  *
89  * \retval 0 success
90  * \retval -1 failure
91  *
92  * \note It is up to the consumer of this API to ensure proper memory management of data payloads
93  *
94  * \since 15.4.0
95  */
96 int ast_data_buffer_put(struct ast_data_buffer *buffer, size_t pos, void *payload);
97 
98 /*!
99  * \brief Retrieve a data payload from the data buffer
100  *
101  * \param buffer The data buffer
102  * \param pos The position of the data payload
103  *
104  * \retval non-NULL success
105  * \retval NULL failure
106  *
107  * \note This does not remove the data payload from the data buffer. It will be removed when it is displaced.
108  *
109  * \since 15.4.0
110  */
111 void *ast_data_buffer_get(const struct ast_data_buffer *buffer, size_t pos);
112 
113 /*!
114  * \brief Remove a data payload from the data buffer
115  *
116  * \param buffer The data buffer
117  * \param pos The position of the data payload
118  *
119  * \retval non-NULL success
120  * \retval NULL failure
121  *
122  * \note This DOES remove the data payload from the data buffer. It does not free it, though.
123  *
124  * \since 15.5.0
125  */
126 void *ast_data_buffer_remove(struct ast_data_buffer *buffer, size_t pos);
127 
128 /*!
129  * \brief Remove the first payload from the data buffer
130  *
131  * \param buffer The data buffer
132  *
133  * \retval non-NULL success
134  * \retval NULL failure
135  *
136  * \note This DOES remove the data payload from the data buffer.
137  *
138  * \since 15.5.0
139  */
140 void *ast_data_buffer_remove_head(struct ast_data_buffer *buffer);
141 
142 /*!
143  * \brief Free a data buffer (and all held data payloads)
144  *
145  * \param buffer The data buffer
146  *
147  * \since 15.4.0
148  */
149 void ast_data_buffer_free(struct ast_data_buffer *buffer);
150 
151 /*!
152  * \brief Return the number of payloads in a data buffer
153  *
154  * \param buffer The data buffer
155  *
156  * \retval the number of data payloads
157  *
158  * \since 15.4.0
159  */
160 size_t ast_data_buffer_count(const struct ast_data_buffer *buffer);
161 
162 /*!
163  * \brief Return the maximum number of payloads a data buffer can hold
164  *
165  * \param buffer The data buffer
166  *
167  * \retval the maximum number of data payloads
168  *
169  * \since 15.4.0
170  */
171 size_t ast_data_buffer_max(const struct ast_data_buffer *buffer);
172 
173 #endif /* _AST_DATA_BUFFER_H */
ast_data_buffer_free_callback
void(* ast_data_buffer_free_callback)(void *data)
A callback function to free a data payload in a data buffer.
Definition: data_buffer.h:48
ast_data_buffer
Data buffer containing fixed number of data payloads.
Definition: data_buffer.c:59
ast_data_buffer_alloc
struct ast_data_buffer * ast_data_buffer_alloc(ast_data_buffer_free_callback free_fn, size_t size)
Allocate a data buffer.
Definition: data_buffer.c:145
ast_data_buffer_remove
void * ast_data_buffer_remove(struct ast_data_buffer *buffer, size_t pos)
Remove a data payload from the data buffer.
Definition: data_buffer.c:299
ast_data_buffer_put
int ast_data_buffer_put(struct ast_data_buffer *buffer, size_t pos, void *payload)
Place a data payload at a position in the data buffer.
Definition: data_buffer.c:203
ast_data_buffer_get
void * ast_data_buffer_get(const struct ast_data_buffer *buffer, size_t pos)
Retrieve a data payload from the data buffer.
Definition: data_buffer.c:269
ast_data_buffer_count
size_t ast_data_buffer_count(const struct ast_data_buffer *buffer)
Return the number of payloads in a data buffer.
Definition: data_buffer.c:356
ast_data_buffer_resize
void ast_data_buffer_resize(struct ast_data_buffer *buffer, size_t size)
Resize a data buffer.
Definition: data_buffer.c:168
ast_data_buffer_max
size_t ast_data_buffer_max(const struct ast_data_buffer *buffer)
Return the maximum number of payloads a data buffer can hold.
Definition: data_buffer.c:363
ast_data_buffer_free
void ast_data_buffer_free(struct ast_data_buffer *buffer)
Free a data buffer (and all held data payloads)
Definition: data_buffer.c:338
ast_data_buffer_remove_head
void * ast_data_buffer_remove_head(struct ast_data_buffer *buffer)
Remove the first payload from the data buffer.
Definition: data_buffer.c:320
ast_data_buffer::free_fn
ast_data_buffer_free_callback free_fn
Callback function to free a data payload.
Definition: data_buffer.c:61
Generated on Sun Aug 8 2021 19:43:41 for Asterisk - The Open Source Telephony Project by   doxygen 1.8.13