Asterisk - The Open Source Telephony Project GIT-master-a358458
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 <jcolp@digium.com>
7 * Ben Ford <bford@digium.com>
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 <jcolp@digium.com>
32 * \author Ben Ford <bford@digium.com>
33 */
34
35#ifndef _AST_DATA_BUFFER_H_
36#define _AST_DATA_BUFFER_H_
37
38/*!
39 * \brief A buffer of data payloads.
40 */
41struct ast_data_buffer;
42
43/*!
44 * \brief A callback function to free a data payload in a data buffer
45 *
46 * \param data The data payload
47 */
48typedef 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 */
64struct 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 */
80void 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 */
96int 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 */
111void *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 */
126void *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 */
140void *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 */
149void 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 * \return the number of data payloads
157 *
158 * \since 15.4.0
159 */
160size_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 * \return the maximum number of data payloads
168 *
169 * \since 15.4.0
170 */
171size_t ast_data_buffer_max(const struct ast_data_buffer *buffer);
172
173#endif /* _AST_DATA_BUFFER_H */
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_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_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_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_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_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_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_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_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
Data buffer containing fixed number of data payloads.
Definition: data_buffer.c:59
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 Wed Apr 17 2024 20:04:19 for Asterisk - The Open Source Telephony Project by doxygen 1.9.4