Mercurial > pidgin3 / file comparison

comparison: libpurple/circularbuffer.h

libpurple/circularbuffer.h

changeset 43299
9454cc5cd5fb
parent 43298
623929763caf
child 43300
0604c6839974
equal deleted inserted replaced
43298:623929763caf 43299:9454cc5cd5fb
1 /*
2 * Purple - Internet Messaging Library
3 * Copyright (C) Pidgin Developers <devel@pidgin.im>
4 *
5 * Purple is the legal property of its developers, whose names are too numerous
6 * to list here. Please refer to the COPYRIGHT file distributed with this
7 * source distribution.
8 *
9 * This library is free software; you can redistribute it and/or modify it
10 * under the terms of the GNU General Public License as published by the Free
11 * Software Foundation; either version 2 of the License, or (at your option)
12 * any later version.
13 *
14 * This library is distributed in the hope that it will be useful, but WITHOUT
15 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
16 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for
17 * more details.
18 *
19 * You should have received a copy of the GNU General Public License along with
20 * this library; if not, see <https://www.gnu.org/licenses/>.
21 */
22
23 #if !defined(PURPLE_GLOBAL_HEADER_INSIDE) && !defined(PURPLE_COMPILATION)
24 # error "only <purple.h> may be included directly"
25 #endif
26
27 #ifndef PURPLE_CIRCULAR_BUFFER_H
28 #define PURPLE_CIRCULAR_BUFFER_H
29
30 #include <glib.h>
31 #include <glib-object.h>
32
33 #include "purpleversion.h"
34
35 G_BEGIN_DECLS
36
37 /**
38 * PurpleCircularBuffer:
39 *
40 * A circular buffer implementation.
41 *
42 * Since: 3.0
43 */
44 #define PURPLE_TYPE_CIRCULAR_BUFFER (purple_circular_buffer_get_type())
45
46 PURPLE_AVAILABLE_IN_3_0
47 G_DECLARE_DERIVABLE_TYPE(PurpleCircularBuffer, purple_circular_buffer, PURPLE,
48 CIRCULAR_BUFFER, GObject)
49
50 struct _PurpleCircularBufferClass {
51 /*< private >*/
52 GObjectClass parent;
53
54 void (*grow)(PurpleCircularBuffer *buffer, gsize len);
55 void (*append)(PurpleCircularBuffer *buffer, gconstpointer src, gsize len);
56 gsize (*max_read_size)(PurpleCircularBuffer *buffer);
57 gboolean (*mark_read)(PurpleCircularBuffer *buffer, gsize len);
58
59 void (*purple_reserved1)(void);
60 void (*purple_reserved2)(void);
61 void (*purple_reserved3)(void);
62 void (*purple_reserved4)(void);
63 };
64
65 /**
66 * purple_circular_buffer_new:
67 * @growsize: The amount that the buffer should grow the first time data
68 * is appended and every time more space is needed. Pass in
69 * "0" to use the default of 256 bytes.
70 *
71 * Creates a new circular buffer. This will not allocate any memory for the
72 * actual buffer until data is appended to it.
73 *
74 * Returns: The new PurpleCircularBuffer.
75 *
76 * Since: 3.0
77 */
78 PURPLE_AVAILABLE_IN_3_0
79 PurpleCircularBuffer *purple_circular_buffer_new(gsize growsize);
80
81 /**
82 * purple_circular_buffer_append:
83 * @buffer: The PurpleCircularBuffer to which to append the data
84 * @src: pointer to the data to copy into the buffer
85 * @len: number of bytes to copy into the buffer
86 *
87 * Append data to the PurpleCircularBuffer. This will grow the internal
88 * buffer to fit the added data, if needed.
89 *
90 * Since: 3.0
91 */
92 PURPLE_AVAILABLE_IN_3_0
93 void purple_circular_buffer_append(PurpleCircularBuffer *buffer, gconstpointer src, gsize len);
94
95 /**
96 * purple_circular_buffer_get_max_read:
97 * @buffer: the PurpleCircularBuffer for which to determine the maximum
98 * contiguous bytes that can be read.
99 *
100 * Determine the maximum number of contiguous bytes that can be read from the
101 * PurpleCircularBuffer.
102 * Note: This may not be the total number of bytes that are buffered - a
103 * subsequent call after calling purple_circular_buffer_mark_read() may indicate
104 * more data is available to read.
105 *
106 * Returns: the number of bytes that can be read from the PurpleCircularBuffer
107 *
108 * Since: 3.0
109 */
110 PURPLE_AVAILABLE_IN_3_0
111 gsize purple_circular_buffer_get_max_read(PurpleCircularBuffer *buffer);
112
113 /**
114 * purple_circular_buffer_mark_read:
115 * @buffer: The PurpleCircularBuffer to mark bytes read from
116 * @len: The number of bytes to mark as read
117 *
118 * Mark the number of bytes that have been read from the buffer.
119 *
120 * Returns: TRUE if we successfully marked the bytes as having been read, FALSE
121 * otherwise.
122 *
123 * Since: 3.0
124 */
125 PURPLE_AVAILABLE_IN_3_0
126 gboolean purple_circular_buffer_mark_read(PurpleCircularBuffer *buffer, gsize len);
127
128 /**
129 * purple_circular_buffer_grow:
130 * @buffer: The PurpleCircularBuffer to grow.
131 * @len: The number of bytes the buffer should be able to hold.
132 *
133 * Increases the buffer size by a multiple of grow size, so that it can hold at
134 * least 'len' bytes.
135 *
136 * Since: 3.0
137 */
138 PURPLE_AVAILABLE_IN_3_0
139 void purple_circular_buffer_grow(PurpleCircularBuffer *buffer, gsize len);
140
141 /**
142 * purple_circular_buffer_get_grow_size:
143 * @buffer: The PurpleCircularBuffer from which to get grow size.
144 *
145 * Returns the number of bytes by which the buffer grows when more space is
146 * needed.
147 *
148 * Returns: The grow size of the buffer.
149 *
150 * Since: 3.0
151 */
152 PURPLE_AVAILABLE_IN_3_0
153 gsize purple_circular_buffer_get_grow_size(PurpleCircularBuffer *buffer);
154
155 /**
156 * purple_circular_buffer_get_used:
157 * @buffer: The PurpleCircularBuffer from which to get used count.
158 *
159 * Returns the number of bytes of this buffer that contain unread data.
160 *
161 * Returns: The number of bytes that contain unread data.
162 *
163 * Since: 3.0
164 */
165 PURPLE_AVAILABLE_IN_3_0
166 gsize purple_circular_buffer_get_used(PurpleCircularBuffer *buffer);
167
168 /**
169 * purple_circular_buffer_get_output:
170 * @buffer: The PurpleCircularBuffer from which to get the output pointer.
171 *
172 * Returns the output pointer of the buffer, where unread data is available.
173 * Use purple_circular_buffer_get_max_read() to determine the number of
174 * contiguous bytes that can be read from this output. After reading the data,
175 * call purple_circular_buffer_mark_read() to mark the retrieved data as read.
176 *
177 * Returns: The output pointer for the buffer.
178 *
179 * Since: 3.0
180 */
181 PURPLE_AVAILABLE_IN_3_0
182 const gchar *purple_circular_buffer_get_output(PurpleCircularBuffer *buffer);
183
184 /**
185 * purple_circular_buffer_reset:
186 * @buffer: The PurpleCircularBuffer to reset.
187 *
188 * Resets the buffer input and output pointers to the start of the buffer.
189 *
190 * Since: 3.0
191 */
192 PURPLE_AVAILABLE_IN_3_0
193 void purple_circular_buffer_reset(PurpleCircularBuffer *buffer);
194
195 G_END_DECLS
196
197 #endif /* PURPLE_CIRCULAR_BUFFER_H */
198

Mercurial Repository: pidgin3

mercurial