Mercurial > pidgin.yaz
annotate src/gaim_buffer.h @ 13212:64bae3cbec8d
[gaim-migrate @ 15576]
Mostly documentation. Is there any reason the if statement was
written the way it was? This seems more clear to me.
Also, gaim_buffer.c doesn't seem like the best name for this. I
mean, it's a part of Gaim, does it really need "gaim" in the filename?
circbuffer.c seems better to me. Anyone else have an opinion?
Because you're wrong. No, just kidding.
committer: Tailor Script <tailor@pidgin.im>
author | Mark Doliner <mark@kingant.net> |
---|---|
date | Fri, 10 Feb 2006 06:07:19 +0000 |
parents | 33bef17125c2 |
children | cc84c3a2fe93 |
rev | line source |
---|---|
13200
33bef17125c2
[gaim-migrate @ 15563]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
diff
changeset
|
1 /* |
33bef17125c2
[gaim-migrate @ 15563]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
diff
changeset
|
2 * @file gaim_buffer.h Buffer Utility Functions |
33bef17125c2
[gaim-migrate @ 15563]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
diff
changeset
|
3 * @ingroup core |
33bef17125c2
[gaim-migrate @ 15563]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
diff
changeset
|
4 * |
33bef17125c2
[gaim-migrate @ 15563]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
diff
changeset
|
5 * Gaim is the legal property of its developers, whose names are too numerous |
33bef17125c2
[gaim-migrate @ 15563]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
diff
changeset
|
6 * to list here. Please refer to the COPYRIGHT file distributed with this |
33bef17125c2
[gaim-migrate @ 15563]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
diff
changeset
|
7 * source distribution. |
33bef17125c2
[gaim-migrate @ 15563]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
diff
changeset
|
8 * |
33bef17125c2
[gaim-migrate @ 15563]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
diff
changeset
|
9 * This program is free software; you can redistribute it and/or modify |
33bef17125c2
[gaim-migrate @ 15563]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
diff
changeset
|
10 * it under the terms of the GNU General Public License as published by |
33bef17125c2
[gaim-migrate @ 15563]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
diff
changeset
|
11 * the Free Software Foundation; either version 2 of the License, or |
33bef17125c2
[gaim-migrate @ 15563]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
diff
changeset
|
12 * (at your option) any later version. |
33bef17125c2
[gaim-migrate @ 15563]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
diff
changeset
|
13 * |
33bef17125c2
[gaim-migrate @ 15563]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
diff
changeset
|
14 * This program is distributed in the hope that it will be useful, |
33bef17125c2
[gaim-migrate @ 15563]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
diff
changeset
|
15 * but WITHOUT ANY WARRANTY; without even the implied warranty of |
33bef17125c2
[gaim-migrate @ 15563]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
diff
changeset
|
16 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the |
33bef17125c2
[gaim-migrate @ 15563]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
diff
changeset
|
17 * GNU General Public License for more details. |
33bef17125c2
[gaim-migrate @ 15563]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
diff
changeset
|
18 * |
33bef17125c2
[gaim-migrate @ 15563]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
diff
changeset
|
19 * You should have received a copy of the GNU General Public License |
33bef17125c2
[gaim-migrate @ 15563]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
diff
changeset
|
20 * along with this program; if not, write to the Free Software |
33bef17125c2
[gaim-migrate @ 15563]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
diff
changeset
|
21 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA |
33bef17125c2
[gaim-migrate @ 15563]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
diff
changeset
|
22 */ |
33bef17125c2
[gaim-migrate @ 15563]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
diff
changeset
|
23 #ifndef _GAIM_BUFFER_H |
33bef17125c2
[gaim-migrate @ 15563]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
diff
changeset
|
24 #define _GAIM_BUFFER_H |
33bef17125c2
[gaim-migrate @ 15563]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
diff
changeset
|
25 |
33bef17125c2
[gaim-migrate @ 15563]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
diff
changeset
|
26 #ifdef __cplusplus |
33bef17125c2
[gaim-migrate @ 15563]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
diff
changeset
|
27 extern "C" { |
33bef17125c2
[gaim-migrate @ 15563]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
diff
changeset
|
28 #endif |
33bef17125c2
[gaim-migrate @ 15563]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
diff
changeset
|
29 |
33bef17125c2
[gaim-migrate @ 15563]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
diff
changeset
|
30 typedef struct _GaimCircBuffer { |
33bef17125c2
[gaim-migrate @ 15563]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
diff
changeset
|
31 gchar *buffer; |
33bef17125c2
[gaim-migrate @ 15563]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
diff
changeset
|
32 gsize growsize; |
33bef17125c2
[gaim-migrate @ 15563]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
diff
changeset
|
33 gsize buflen; |
33bef17125c2
[gaim-migrate @ 15563]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
diff
changeset
|
34 gsize bufused; |
33bef17125c2
[gaim-migrate @ 15563]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
diff
changeset
|
35 gchar *inptr; |
33bef17125c2
[gaim-migrate @ 15563]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
diff
changeset
|
36 gchar *outptr; |
33bef17125c2
[gaim-migrate @ 15563]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
diff
changeset
|
37 } GaimCircBuffer; |
33bef17125c2
[gaim-migrate @ 15563]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
diff
changeset
|
38 |
33bef17125c2
[gaim-migrate @ 15563]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
diff
changeset
|
39 /** |
33bef17125c2
[gaim-migrate @ 15563]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
diff
changeset
|
40 * Creates a new circular buffer. This will not allocate any memory for the |
33bef17125c2
[gaim-migrate @ 15563]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
diff
changeset
|
41 * actual buffer until data is appended to it. |
33bef17125c2
[gaim-migrate @ 15563]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
diff
changeset
|
42 * |
13212 | 43 * @param growsize The amount that the buffer should grow the first time data |
44 * is appended and every time more space is needed. Pass in | |
45 * "0" to use the default of 256 bytes. | |
13200
33bef17125c2
[gaim-migrate @ 15563]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
diff
changeset
|
46 * |
33bef17125c2
[gaim-migrate @ 15563]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
diff
changeset
|
47 * @return The new GaimCircBuffer. This should be freed with |
33bef17125c2
[gaim-migrate @ 15563]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
diff
changeset
|
48 * gaim_circ_buffer_destroy when you are done with it |
33bef17125c2
[gaim-migrate @ 15563]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
diff
changeset
|
49 */ |
33bef17125c2
[gaim-migrate @ 15563]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
diff
changeset
|
50 GaimCircBuffer *gaim_circ_buffer_new(gsize growsize); |
33bef17125c2
[gaim-migrate @ 15563]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
diff
changeset
|
51 |
33bef17125c2
[gaim-migrate @ 15563]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
diff
changeset
|
52 /** |
33bef17125c2
[gaim-migrate @ 15563]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
diff
changeset
|
53 * Dispose of the GaimCircBuffer and free any memory used by it (including any |
33bef17125c2
[gaim-migrate @ 15563]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
diff
changeset
|
54 * memory used by the internal buffer). |
33bef17125c2
[gaim-migrate @ 15563]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
diff
changeset
|
55 * |
33bef17125c2
[gaim-migrate @ 15563]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
diff
changeset
|
56 * @param buf The GaimCircBuffer to free |
33bef17125c2
[gaim-migrate @ 15563]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
diff
changeset
|
57 */ |
33bef17125c2
[gaim-migrate @ 15563]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
diff
changeset
|
58 void gaim_circ_buffer_destroy(GaimCircBuffer *buf); |
33bef17125c2
[gaim-migrate @ 15563]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
diff
changeset
|
59 |
33bef17125c2
[gaim-migrate @ 15563]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
diff
changeset
|
60 /** |
13212 | 61 * Append data to the GaimCircBuffer. This will grow the internal |
62 * buffer to fit the added data, if needed. | |
13200
33bef17125c2
[gaim-migrate @ 15563]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
diff
changeset
|
63 * |
33bef17125c2
[gaim-migrate @ 15563]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
diff
changeset
|
64 * @param buf The GaimCircBuffer to which to append the data |
33bef17125c2
[gaim-migrate @ 15563]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
diff
changeset
|
65 * @param src pointer to the data to copy into the buffer |
33bef17125c2
[gaim-migrate @ 15563]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
diff
changeset
|
66 * @param len number of bytes to copy into the buffer |
33bef17125c2
[gaim-migrate @ 15563]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
diff
changeset
|
67 */ |
33bef17125c2
[gaim-migrate @ 15563]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
diff
changeset
|
68 void gaim_circ_buffer_append(GaimCircBuffer *buf, gconstpointer src, gsize len); |
33bef17125c2
[gaim-migrate @ 15563]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
diff
changeset
|
69 |
33bef17125c2
[gaim-migrate @ 15563]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
diff
changeset
|
70 /** |
33bef17125c2
[gaim-migrate @ 15563]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
diff
changeset
|
71 * Determine the maximum number of contiguous bytes that can be read from the |
33bef17125c2
[gaim-migrate @ 15563]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
diff
changeset
|
72 * GaimCircBuffer. |
33bef17125c2
[gaim-migrate @ 15563]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
diff
changeset
|
73 * Note: This may not be the total number of bytes that are buffered - a |
33bef17125c2
[gaim-migrate @ 15563]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
diff
changeset
|
74 * subsequent call after calling gaim_circ_buffer_mark_read() may indicate more |
33bef17125c2
[gaim-migrate @ 15563]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
diff
changeset
|
75 * data is available to read. |
33bef17125c2
[gaim-migrate @ 15563]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
diff
changeset
|
76 * |
33bef17125c2
[gaim-migrate @ 15563]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
diff
changeset
|
77 * @param buf the GaimCircBuffer for which to determine the maximum contiguous |
33bef17125c2
[gaim-migrate @ 15563]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
diff
changeset
|
78 * bytes that can be read. |
33bef17125c2
[gaim-migrate @ 15563]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
diff
changeset
|
79 * |
33bef17125c2
[gaim-migrate @ 15563]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
diff
changeset
|
80 * @return the number of bytes that can be read from the GaimCircBuffer |
33bef17125c2
[gaim-migrate @ 15563]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
diff
changeset
|
81 */ |
33bef17125c2
[gaim-migrate @ 15563]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
diff
changeset
|
82 gsize gaim_circ_buffer_get_max_read(GaimCircBuffer *buf); |
33bef17125c2
[gaim-migrate @ 15563]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
diff
changeset
|
83 |
33bef17125c2
[gaim-migrate @ 15563]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
diff
changeset
|
84 /** |
33bef17125c2
[gaim-migrate @ 15563]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
diff
changeset
|
85 * Mark the number of bytes that have been read from the buffer. |
33bef17125c2
[gaim-migrate @ 15563]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
diff
changeset
|
86 * |
33bef17125c2
[gaim-migrate @ 15563]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
diff
changeset
|
87 * @param buf The GaimCircBuffer to mark bytes read from |
33bef17125c2
[gaim-migrate @ 15563]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
diff
changeset
|
88 * @param len The number of bytes to mark as read |
33bef17125c2
[gaim-migrate @ 15563]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
diff
changeset
|
89 * |
33bef17125c2
[gaim-migrate @ 15563]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
diff
changeset
|
90 * @return TRUE if we successfully marked the bytes as having been read, FALSE |
33bef17125c2
[gaim-migrate @ 15563]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
diff
changeset
|
91 * otherwise. |
33bef17125c2
[gaim-migrate @ 15563]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
diff
changeset
|
92 */ |
33bef17125c2
[gaim-migrate @ 15563]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
diff
changeset
|
93 gboolean gaim_circ_buffer_mark_read(GaimCircBuffer *buf, gsize len); |
33bef17125c2
[gaim-migrate @ 15563]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
diff
changeset
|
94 |
33bef17125c2
[gaim-migrate @ 15563]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
diff
changeset
|
95 #ifdef __cplusplus |
33bef17125c2
[gaim-migrate @ 15563]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
diff
changeset
|
96 } |
33bef17125c2
[gaim-migrate @ 15563]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
diff
changeset
|
97 #endif |
33bef17125c2
[gaim-migrate @ 15563]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
diff
changeset
|
98 |
33bef17125c2
[gaim-migrate @ 15563]
Daniel Atallah <daniel.atallah@gmail.com>
parents:
diff
changeset
|
99 #endif /* _GAIM_BUFFER_H */ |