xine-lib: xine-lib-1.2.13/include/xine/xine_buffer.h Source File

xine-lib 1.2.13-20230125hg15249

xine_buffer.h
Go to the documentation of this file.
1/*
2 * Copyright (C) 2000-2017 the xine project
3 *
4 * This file is part of xine, a free video player.
5 *
6 * xine is free software; you can redistribute it and/or modify
7 * it under the terms of the GNU General Public License as published by
8 * the Free Software Foundation; either version 2 of the License, or
9 * (at your option) any later version.
10 *
11 * xine is distributed in the hope that it will be useful,
12 * but WITHOUT ANY WARRANTY; without even the implied warranty of
13 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
14 * GNU General Public License for more details.
15 *
16 * You should have received a copy of the GNU General Public License
17 * along with this program; if not, write to the Free Software
18 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110, USA
19 *
20 *
21 * generic dynamic buffer functions. The goals
22 * of these functions are (in fact many of these points
23 * are todos):
24 * - dynamic allocation and reallocation depending
25 * on the size of data written to it.
26 * - fast and transparent access to the data.
27 * The user sees only the raw data chunk as it is
28 * returned by the well-known malloc function.
29 * This is necessary since not all data-accessing
30 * functions can be wrapped here.
31 * - some additional health checks are made during
32 * development (eg boundary checks after direct
33 * access to a buffer). This can be turned off in
34 * production state for higher performance.
35 * - A lot of convenient string and memory manipulation
36 * functions are implemented here, where the user
37 * do not have to care about memory chunk sizes.
38 * - Some garbage collention could be implemented as well;
39 * i think of a global structure containing infos
40 * about all allocated chunks. This must be implemented
41 * in a thread-save way...
42 *
43 * Here are some drawbacks (aka policies):
44 * - The user must not pass indexed buffers to xine_buffer_*
45 * functions.
46 * - The pointers passed to xine_buffer_* functions may change
47 * (eg during reallocation). The user must respect that.
48 */
49
50#ifndef HAVE_XINE_BUFFER_H
51#define HAVE_XINE_BUFFER_H
52
53#include <xine/attributes.h>
54#include <xine/os_types.h>
55
56/*
57 * returns an initialized pointer to a buffer.
58 * The buffer will be allocated in blocks of
59 * chunk_size bytes. This will prevent permanent
60 * reallocation on slow growing buffers.
61 */
62void *xine_buffer_init(int chunk_size) XINE_PROTECTED;
63
64/*
65 * frees a buffer, the macro ensures, that a freed
66 * buffer pointer is set to NULL
67 */
68#define xine_buffer_free(buf) buf=_xine_buffer_free(buf)
69void *_xine_buffer_free(void *buf) XINE_PROTECTED;
70
71/*
72 * duplicates a buffer
73 */
74void *xine_buffer_dup(const void *buf) XINE_PROTECTED;
75
76/*
77 * will copy len bytes of data into buf at position index.
78 */
79#define xine_buffer_copyin(buf,i,data,len) \
80 buf=_xine_buffer_copyin(buf,i,data,len)
81void *_xine_buffer_copyin(void *buf, int index, const void *data, int len) XINE_PROTECTED;
82
83/*
84 * will copy len bytes out of buf+index into data.
85 * no checks are made in data. It is treated as an ordinary
86 * user-malloced data chunk.
87 */
88void xine_buffer_copyout(const void *buf, int index, void *data, int len) XINE_PROTECTED;
89
90/*
91 * set len bytes in buf+index to b.
92 */
93#define xine_buffer_set(buf,i,b,len) \
94 buf=_xine_buffer_set(buf,i,b,len)
95void *_xine_buffer_set(void *buf, int index, uint8_t b, int len) XINE_PROTECTED;
96
97/*
98 * concatenates given buf (which should contain a null terminated string)
99 * with another string.
100 */
101#define xine_buffer_strcat(buf,data) \
102 buf=_xine_buffer_strcat(buf,data)
103void *_xine_buffer_strcat(void *buf, const char *data) XINE_PROTECTED;
104
105/*
106 * copies given string to buf+index
107 */
108#define xine_buffer_strcpy(buf,index,data) \
109 buf=_xine_buffer_strcpy(buf,index,data)
110void *_xine_buffer_strcpy(void *buf, int index, const char *data) XINE_PROTECTED;
111
112/*
113 * returns a pointer to the first occurence of ch.
114 * note, that the returned pointer cannot be used
115 * in any other xine_buffer_* functions.
116 */
117char *xine_buffer_strchr(const void *buf, int ch) XINE_PROTECTED;
118
119/*
120 * get allocated memory size
121 */
122int xine_buffer_get_size(const void *buf) XINE_PROTECTED;
123
124/*
125 * ensures a specified buffer size if the user want to
126 * write directly to the buffer. Normally the special
127 * access functions defined here should be used.
128 */
129#define xine_buffer_ensure_size(buf,data) \
130 buf=_xine_buffer_ensure_size(buf,data)
131void *_xine_buffer_ensure_size(void *buf, int size) XINE_PROTECTED;
132
133#endif
attributes.h
XINE_PROTECTED
#define XINE_PROTECTED
Definition attributes.h:75
os_types.h
_xine_buffer_copyin
void * _xine_buffer_copyin(void *buf, int index, const void *data, int len)
Definition xine_buffer.c:196
xine_buffer_copyout
void xine_buffer_copyout(const void *buf, int index, void *data, int len)
Definition xine_buffer.c:218
_xine_buffer_free
void * _xine_buffer_free(void *buf)
Definition xine_buffer.c:150
_xine_buffer_strcpy
void * _xine_buffer_strcpy(void *buf, int index, const char *data)
Definition xine_buffer.c:277
xine_buffer_dup
void * xine_buffer_dup(const void *buf)
Definition xine_buffer.c:168
xine_buffer_strchr
char * xine_buffer_strchr(const void *buf, int ch)
Definition xine_buffer.c:299
_xine_buffer_set
void * _xine_buffer_set(void *buf, int index, uint8_t b, int len)
Definition xine_buffer.c:245
_xine_buffer_strcat
void * _xine_buffer_strcat(void *buf, const char *data)
Definition xine_buffer.c:268
xine_buffer_init
void * xine_buffer_init(int chunk_size)
Definition xine_buffer.c:129
_xine_buffer_ensure_size
void * _xine_buffer_ensure_size(void *buf, int size)
Definition xine_buffer.c:334
xine_buffer_get_size
int xine_buffer_get_size(const void *buf)
Definition xine_buffer.c:314