annotate libpurple/circbuffer.h @ 29368:746bf7d8b34e

Combine the CurrentMedia and MsnUserPhoneInfo structs. This makes MsnUser smaller by the size of one pointer. Since both of these structs are used only rarely, this ends up saving memory for most people.
author Mark Doliner <mark@kingant.net>
date Fri, 05 Feb 2010 02:19:22 +0000
parents 6bf32c9e15a7
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
20074
6bf32c9e15a7 remove gpl boilerplate from doxygen docs
Sean Egan <seanegan@gmail.com>
parents: 19680
diff changeset
1 /**
15374
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
2 * @file circbuffer.h Buffer Utility Functions
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
3 * @ingroup core
20074
6bf32c9e15a7 remove gpl boilerplate from doxygen docs
Sean Egan <seanegan@gmail.com>
parents: 19680
diff changeset
4 */
6bf32c9e15a7 remove gpl boilerplate from doxygen docs
Sean Egan <seanegan@gmail.com>
parents: 19680
diff changeset
5
6bf32c9e15a7 remove gpl boilerplate from doxygen docs
Sean Egan <seanegan@gmail.com>
parents: 19680
diff changeset
6 /* Purple is the legal property of its developers, whose names are too numerous
15374
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
7 * to list here. Please refer to the COPYRIGHT file distributed with this
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
8 * source distribution.
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
9 *
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
10 * This program is free software; you can redistribute it and/or modify
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
11 * it under the terms of the GNU General Public License as published by
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
12 * the Free Software Foundation; either version 2 of the License, or
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
13 * (at your option) any later version.
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
14 *
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
15 * This program is distributed in the hope that it will be useful,
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
16 * but WITHOUT ANY WARRANTY; without even the implied warranty of
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
17 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
18 * GNU General Public License for more details.
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
19 *
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
20 * You should have received a copy of the GNU General Public License
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
21 * along with this program; if not, write to the Free Software
19680
44b4e8bd759b The FSF changed its address a while ago; our files were out of date.
John Bailey <rekkanoryo@rekkanoryo.org>
parents: 15823
diff changeset
22 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02111-1301 USA
15374
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
23 */
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
24 #ifndef _CIRCBUFFER_H
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
25 #define _CIRCBUFFER_H
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
26
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
27 #include <glib.h>
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
28
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
29 #ifdef __cplusplus
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
30 extern "C" {
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
31 #endif
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
32
15823
32c366eeeb99 sed -ie 's/gaim/purple/g'
Sean Egan <seanegan@gmail.com>
parents: 15548
diff changeset
33 typedef struct _PurpleCircBuffer {
15374
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
34
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
35 /** A pointer to the starting address of our chunk of memory. */
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
36 gchar *buffer;
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
37
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
38 /** The incremental amount to increase this buffer by when
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
39 * the buffer is not big enough to hold incoming data, in bytes. */
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
40 gsize growsize;
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
41
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
42 /** The length of this buffer, in bytes. */
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
43 gsize buflen;
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
44
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
45 /** The number of bytes of this buffer that contain unread data. */
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
46 gsize bufused;
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
47
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
48 /** A pointer to the next byte where new incoming data is
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
49 * buffered to. */
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
50 gchar *inptr;
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
51
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
52 /** A pointer to the next byte of buffered data that should be
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
53 * read by the consumer. */
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
54 gchar *outptr;
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
55
15823
32c366eeeb99 sed -ie 's/gaim/purple/g'
Sean Egan <seanegan@gmail.com>
parents: 15548
diff changeset
56 } PurpleCircBuffer;
15374
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
57
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
58 /**
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
59 * Creates a new circular buffer. This will not allocate any memory for the
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
60 * actual buffer until data is appended to it.
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
61 *
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
62 * @param growsize The amount that the buffer should grow the first time data
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
63 * is appended and every time more space is needed. Pass in
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
64 * "0" to use the default of 256 bytes.
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
65 *
15823
32c366eeeb99 sed -ie 's/gaim/purple/g'
Sean Egan <seanegan@gmail.com>
parents: 15548
diff changeset
66 * @return The new PurpleCircBuffer. This should be freed with
32c366eeeb99 sed -ie 's/gaim/purple/g'
Sean Egan <seanegan@gmail.com>
parents: 15548
diff changeset
67 * purple_circ_buffer_destroy when you are done with it
15374
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
68 */
15823
32c366eeeb99 sed -ie 's/gaim/purple/g'
Sean Egan <seanegan@gmail.com>
parents: 15548
diff changeset
69 PurpleCircBuffer *purple_circ_buffer_new(gsize growsize);
15374
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
70
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
71 /**
15823
32c366eeeb99 sed -ie 's/gaim/purple/g'
Sean Egan <seanegan@gmail.com>
parents: 15548
diff changeset
72 * Dispose of the PurpleCircBuffer and free any memory used by it (including any
15374
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
73 * memory used by the internal buffer).
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
74 *
15823
32c366eeeb99 sed -ie 's/gaim/purple/g'
Sean Egan <seanegan@gmail.com>
parents: 15548
diff changeset
75 * @param buf The PurpleCircBuffer to free
15374
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
76 */
15823
32c366eeeb99 sed -ie 's/gaim/purple/g'
Sean Egan <seanegan@gmail.com>
parents: 15548
diff changeset
77 void purple_circ_buffer_destroy(PurpleCircBuffer *buf);
15374
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
78
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
79 /**
15823
32c366eeeb99 sed -ie 's/gaim/purple/g'
Sean Egan <seanegan@gmail.com>
parents: 15548
diff changeset
80 * Append data to the PurpleCircBuffer. This will grow the internal
15374
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
81 * buffer to fit the added data, if needed.
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
82 *
15823
32c366eeeb99 sed -ie 's/gaim/purple/g'
Sean Egan <seanegan@gmail.com>
parents: 15548
diff changeset
83 * @param buf The PurpleCircBuffer to which to append the data
15374
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
84 * @param src pointer to the data to copy into the buffer
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
85 * @param len number of bytes to copy into the buffer
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
86 */
15823
32c366eeeb99 sed -ie 's/gaim/purple/g'
Sean Egan <seanegan@gmail.com>
parents: 15548
diff changeset
87 void purple_circ_buffer_append(PurpleCircBuffer *buf, gconstpointer src, gsize len);
15374
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
88
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
89 /**
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
90 * Determine the maximum number of contiguous bytes that can be read from the
15823
32c366eeeb99 sed -ie 's/gaim/purple/g'
Sean Egan <seanegan@gmail.com>
parents: 15548
diff changeset
91 * PurpleCircBuffer.
15374
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
92 * Note: This may not be the total number of bytes that are buffered - a
15823
32c366eeeb99 sed -ie 's/gaim/purple/g'
Sean Egan <seanegan@gmail.com>
parents: 15548
diff changeset
93 * subsequent call after calling purple_circ_buffer_mark_read() may indicate more
15374
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
94 * data is available to read.
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
95 *
15823
32c366eeeb99 sed -ie 's/gaim/purple/g'
Sean Egan <seanegan@gmail.com>
parents: 15548
diff changeset
96 * @param buf the PurpleCircBuffer for which to determine the maximum contiguous
15374
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
97 * bytes that can be read.
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
98 *
15823
32c366eeeb99 sed -ie 's/gaim/purple/g'
Sean Egan <seanegan@gmail.com>
parents: 15548
diff changeset
99 * @return the number of bytes that can be read from the PurpleCircBuffer
15374
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
100 */
15823
32c366eeeb99 sed -ie 's/gaim/purple/g'
Sean Egan <seanegan@gmail.com>
parents: 15548
diff changeset
101 gsize purple_circ_buffer_get_max_read(const PurpleCircBuffer *buf);
15374
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
102
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
103 /**
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
104 * Mark the number of bytes that have been read from the buffer.
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
105 *
15823
32c366eeeb99 sed -ie 's/gaim/purple/g'
Sean Egan <seanegan@gmail.com>
parents: 15548
diff changeset
106 * @param buf The PurpleCircBuffer to mark bytes read from
15374
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
107 * @param len The number of bytes to mark as read
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
108 *
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
109 * @return TRUE if we successfully marked the bytes as having been read, FALSE
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
110 * otherwise.
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
111 */
15823
32c366eeeb99 sed -ie 's/gaim/purple/g'
Sean Egan <seanegan@gmail.com>
parents: 15548
diff changeset
112 gboolean purple_circ_buffer_mark_read(PurpleCircBuffer *buf, gsize len);
15374
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
113
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
114 #ifdef __cplusplus
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
115 }
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
116 #endif
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
117
5fe8042783c1 Rename gtk/ and libgaim/ to pidgin/ and libpurple/
Sean Egan <seanegan@gmail.com>
parents:
diff changeset
118 #endif /* _CIRCBUFFER_H */