Mercurial > pidgin.yaz
annotate src/value.h @ 14039:5e6d4c36630a
[gaim-migrate @ 16643]
Return g_string_free(str, FALSE) directly instead of assigning
str->str to a temporary directory and returning that.
committer: Tailor Script <tailor@pidgin.im>
author | Mark Doliner <mark@kingant.net> |
---|---|
date | Sat, 05 Aug 2006 09:17:09 +0000 |
parents | 0567de116699 |
children |
rev | line source |
---|---|
6562 | 1 /** |
2 * @file value.h Value wrapper API | |
3 * @ingroup core | |
4 * | |
5 * gaim | |
6 * | |
8046 | 7 * Gaim is the legal property of its developers, whose names are too numerous |
8 * to list here. Please refer to the COPYRIGHT file distributed with this | |
9 * source distribution. | |
6562 | 10 * |
11 * This program is free software; you can redistribute it and/or modify | |
12 * it under the terms of the GNU General Public License as published by | |
13 * the Free Software Foundation; either version 2 of the License, or | |
14 * (at your option) any later version. | |
15 * | |
16 * This program is distributed in the hope that it will be useful, | |
17 * but WITHOUT ANY WARRANTY; without even the implied warranty of | |
18 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the | |
19 * GNU General Public License for more details. | |
20 * | |
21 * You should have received a copy of the GNU General Public License | |
22 * along with this program; if not, write to the Free Software | |
23 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA | |
24 */ | |
25 #ifndef _GAIM_VALUE_H_ | |
26 #define _GAIM_VALUE_H_ | |
27 | |
6565
cb00e9647033
[gaim-migrate @ 7087]
Christian Hammond <chipx86@chipx86.com>
parents:
6563
diff
changeset
|
28 #include <glib.h> |
cb00e9647033
[gaim-migrate @ 7087]
Christian Hammond <chipx86@chipx86.com>
parents:
6563
diff
changeset
|
29 |
6562 | 30 /** |
31 * Specific value types. | |
32 */ | |
33 typedef enum | |
34 { | |
35 GAIM_TYPE_UNKNOWN = 0, /**< Unknown type. */ | |
36 GAIM_TYPE_SUBTYPE, /**< Subtype. */ | |
37 GAIM_TYPE_CHAR, /**< Character. */ | |
38 GAIM_TYPE_UCHAR, /**< Unsigned character. */ | |
39 GAIM_TYPE_BOOLEAN, /**< Boolean. */ | |
40 GAIM_TYPE_SHORT, /**< Short integer. */ | |
41 GAIM_TYPE_USHORT, /**< Unsigned short integer. */ | |
42 GAIM_TYPE_INT, /**< Integer. */ | |
43 GAIM_TYPE_UINT, /**< Unsigned integer. */ | |
44 GAIM_TYPE_LONG, /**< Long integer. */ | |
45 GAIM_TYPE_ULONG, /**< Unsigned long integer. */ | |
46 GAIM_TYPE_INT64, /**< 64-bit integer. */ | |
47 GAIM_TYPE_UINT64, /**< 64-bit unsigned integer. */ | |
48 GAIM_TYPE_STRING, /**< String. */ | |
49 GAIM_TYPE_OBJECT, /**< Object pointer. */ | |
50 GAIM_TYPE_POINTER, /**< Generic pointer. */ | |
51 GAIM_TYPE_ENUM, /**< Enum. */ | |
52 GAIM_TYPE_BOXED /**< Boxed pointer with specific type. */ | |
53 | |
54 } GaimType; | |
55 | |
13987
f94309c7c480
[gaim-migrate @ 16559]
Richard Laager <rlaager@wiktel.com>
parents:
13387
diff
changeset
|
56 |
6562 | 57 /** |
6563
122cb375be2d
[gaim-migrate @ 7085]
Christian Hammond <chipx86@chipx86.com>
parents:
6562
diff
changeset
|
58 * Gaim-specific subtype values. |
122cb375be2d
[gaim-migrate @ 7085]
Christian Hammond <chipx86@chipx86.com>
parents:
6562
diff
changeset
|
59 */ |
122cb375be2d
[gaim-migrate @ 7085]
Christian Hammond <chipx86@chipx86.com>
parents:
6562
diff
changeset
|
60 typedef enum |
122cb375be2d
[gaim-migrate @ 7085]
Christian Hammond <chipx86@chipx86.com>
parents:
6562
diff
changeset
|
61 { |
122cb375be2d
[gaim-migrate @ 7085]
Christian Hammond <chipx86@chipx86.com>
parents:
6562
diff
changeset
|
62 GAIM_SUBTYPE_UNKNOWN = 0, |
122cb375be2d
[gaim-migrate @ 7085]
Christian Hammond <chipx86@chipx86.com>
parents:
6562
diff
changeset
|
63 GAIM_SUBTYPE_ACCOUNT, |
122cb375be2d
[gaim-migrate @ 7085]
Christian Hammond <chipx86@chipx86.com>
parents:
6562
diff
changeset
|
64 GAIM_SUBTYPE_BLIST, |
122cb375be2d
[gaim-migrate @ 7085]
Christian Hammond <chipx86@chipx86.com>
parents:
6562
diff
changeset
|
65 GAIM_SUBTYPE_BLIST_BUDDY, |
122cb375be2d
[gaim-migrate @ 7085]
Christian Hammond <chipx86@chipx86.com>
parents:
6562
diff
changeset
|
66 GAIM_SUBTYPE_BLIST_GROUP, |
122cb375be2d
[gaim-migrate @ 7085]
Christian Hammond <chipx86@chipx86.com>
parents:
6562
diff
changeset
|
67 GAIM_SUBTYPE_BLIST_CHAT, |
10934 | 68 GAIM_SUBTYPE_BUDDY_ICON, |
6563
122cb375be2d
[gaim-migrate @ 7085]
Christian Hammond <chipx86@chipx86.com>
parents:
6562
diff
changeset
|
69 GAIM_SUBTYPE_CONNECTION, |
122cb375be2d
[gaim-migrate @ 7085]
Christian Hammond <chipx86@chipx86.com>
parents:
6562
diff
changeset
|
70 GAIM_SUBTYPE_CONVERSATION, |
8817 | 71 GAIM_SUBTYPE_PLUGIN, |
10684
72a5babfa8b4
[gaim-migrate @ 12231]
Luke Schierer <lschiere@pidgin.im>
parents:
10477
diff
changeset
|
72 GAIM_SUBTYPE_BLIST_NODE, |
11979
717cbb3115bc
[gaim-migrate @ 14272]
Gary Kramlich <grim@reaperworld.com>
parents:
10934
diff
changeset
|
73 GAIM_SUBTYPE_CIPHER, |
12737
a1e241dd50b6
[gaim-migrate @ 15082]
Richard Laager <rlaager@wiktel.com>
parents:
11979
diff
changeset
|
74 GAIM_SUBTYPE_STATUS, |
13219
d0f7f698b6de
[gaim-migrate @ 15583]
Richard Laager <rlaager@wiktel.com>
parents:
12837
diff
changeset
|
75 GAIM_SUBTYPE_LOG, |
13387
d9dbb874a30c
[gaim-migrate @ 15760]
Richard Laager <rlaager@wiktel.com>
parents:
13219
diff
changeset
|
76 GAIM_SUBTYPE_XFER, |
d9dbb874a30c
[gaim-migrate @ 15760]
Richard Laager <rlaager@wiktel.com>
parents:
13219
diff
changeset
|
77 GAIM_SUBTYPE_SAVEDSTATUS |
6563
122cb375be2d
[gaim-migrate @ 7085]
Christian Hammond <chipx86@chipx86.com>
parents:
6562
diff
changeset
|
78 } GaimSubType; |
122cb375be2d
[gaim-migrate @ 7085]
Christian Hammond <chipx86@chipx86.com>
parents:
6562
diff
changeset
|
79 |
122cb375be2d
[gaim-migrate @ 7085]
Christian Hammond <chipx86@chipx86.com>
parents:
6562
diff
changeset
|
80 /** |
6562 | 81 * A wrapper for a type, subtype, and specific type of value. |
82 */ | |
83 typedef struct | |
84 { | |
85 GaimType type; | |
86 unsigned short flags; | |
87 | |
88 union | |
89 { | |
90 char char_data; | |
91 unsigned char uchar_data; | |
92 gboolean boolean_data; | |
93 short short_data; | |
94 unsigned short ushort_data; | |
95 int int_data; | |
96 unsigned int uint_data; | |
97 long long_data; | |
98 unsigned long ulong_data; | |
99 gint64 int64_data; | |
100 guint64 uint64_data; | |
101 char *string_data; | |
102 void *object_data; | |
103 void *pointer_data; | |
104 int enum_data; | |
105 void *boxed_data; | |
106 | |
107 } data; | |
108 | |
109 union | |
110 { | |
111 unsigned int subtype; | |
112 char *specific_type; | |
113 | |
114 } u; | |
115 | |
116 } GaimValue; | |
117 | |
6563
122cb375be2d
[gaim-migrate @ 7085]
Christian Hammond <chipx86@chipx86.com>
parents:
6562
diff
changeset
|
118 #ifdef __cplusplus |
122cb375be2d
[gaim-migrate @ 7085]
Christian Hammond <chipx86@chipx86.com>
parents:
6562
diff
changeset
|
119 extern "C" { |
122cb375be2d
[gaim-migrate @ 7085]
Christian Hammond <chipx86@chipx86.com>
parents:
6562
diff
changeset
|
120 #endif |
122cb375be2d
[gaim-migrate @ 7085]
Christian Hammond <chipx86@chipx86.com>
parents:
6562
diff
changeset
|
121 |
6562 | 122 /** |
123 * Creates a new GaimValue. | |
124 * | |
125 * This function takes a type and, depending on that type, a sub-type | |
126 * or specific type. | |
127 * | |
10477 | 128 * If @a type is GAIM_TYPE_BOXED, the next parameter must be a |
6562 | 129 * string representing the specific type. |
130 * | |
131 * If @a type is GAIM_TYPE_SUBTYPE, the next parameter must be a | |
132 * integer or enum representing the sub-type. | |
133 * | |
134 * If the subtype or specific type is not set when required, random | |
135 * errors may occur. You have been warned. | |
136 * | |
137 * @param type The type. | |
138 * | |
139 * @return The new value. | |
140 */ | |
141 GaimValue *gaim_value_new(GaimType type, ...); | |
142 | |
143 /** | |
10477 | 144 * Creates a new outgoing GaimValue. If a value is an "outgoing" value |
145 * it means the value can be modified by plugins and scripts. | |
6562 | 146 * |
147 * This function takes a type and, depending on that type, a sub-type | |
148 * or specific type. | |
149 * | |
10477 | 150 * If @a type is GAIM_TYPE_BOXED, the next parameter must be a |
6562 | 151 * string representing the specific type. |
152 * | |
153 * If @a type is GAIM_TYPE_SUBTYPE, the next parameter must be a | |
154 * integer or enum representing the sub-type. | |
155 * | |
156 * If the sub-type or specific type is not set when required, random | |
157 * errors may occur. You have been warned. | |
158 * | |
159 * @param type The type. | |
160 * | |
161 * @return The new value. | |
162 */ | |
163 GaimValue *gaim_value_new_outgoing(GaimType type, ...); | |
164 | |
165 /** | |
166 * Destroys a GaimValue. | |
167 * | |
168 * @param value The value to destroy. | |
169 */ | |
170 void gaim_value_destroy(GaimValue *value); | |
171 | |
172 /** | |
8809
fde4101fa183
[gaim-migrate @ 9571]
Christian Hammond <chipx86@chipx86.com>
parents:
8046
diff
changeset
|
173 * Duplicated a GaimValue. |
fde4101fa183
[gaim-migrate @ 9571]
Christian Hammond <chipx86@chipx86.com>
parents:
8046
diff
changeset
|
174 * |
fde4101fa183
[gaim-migrate @ 9571]
Christian Hammond <chipx86@chipx86.com>
parents:
8046
diff
changeset
|
175 * @param value The value to duplicate. |
fde4101fa183
[gaim-migrate @ 9571]
Christian Hammond <chipx86@chipx86.com>
parents:
8046
diff
changeset
|
176 * |
fde4101fa183
[gaim-migrate @ 9571]
Christian Hammond <chipx86@chipx86.com>
parents:
8046
diff
changeset
|
177 * @return The duplicate value. |
fde4101fa183
[gaim-migrate @ 9571]
Christian Hammond <chipx86@chipx86.com>
parents:
8046
diff
changeset
|
178 */ |
fde4101fa183
[gaim-migrate @ 9571]
Christian Hammond <chipx86@chipx86.com>
parents:
8046
diff
changeset
|
179 GaimValue *gaim_value_dup(const GaimValue *value); |
fde4101fa183
[gaim-migrate @ 9571]
Christian Hammond <chipx86@chipx86.com>
parents:
8046
diff
changeset
|
180 |
fde4101fa183
[gaim-migrate @ 9571]
Christian Hammond <chipx86@chipx86.com>
parents:
8046
diff
changeset
|
181 /** |
6562 | 182 * Returns a value's type. |
183 * | |
10071 | 184 * @param value The value whose type you want. |
185 * | |
6562 | 186 * @return The value's type. |
187 */ | |
188 GaimType gaim_value_get_type(const GaimValue *value); | |
189 | |
190 /** | |
191 * Returns a value's subtype. | |
192 * | |
193 * If the value's type is not GAIM_TYPE_SUBTYPE, this will return 0. | |
194 * Subtypes should never have a subtype of 0. | |
195 * | |
10071 | 196 * @param value The value whose subtype you want. |
197 * | |
6562 | 198 * @return The value's subtype, or 0 if @a type is not GAIM_TYPE_SUBTYPE. |
199 */ | |
200 unsigned int gaim_value_get_subtype(const GaimValue *value); | |
201 | |
202 /** | |
203 * Returns a value's specific type. | |
204 * | |
205 * If the value's type is not GAIM_TYPE_BOXED, this will return @c NULL. | |
206 * | |
10071 | 207 * @param value The value whose specific type you want. |
208 * | |
6562 | 209 * @return The value's specific type, or @a NULL if not GAIM_TYPE_BOXED. |
210 */ | |
211 const char *gaim_value_get_specific_type(const GaimValue *value); | |
212 | |
213 /** | |
214 * Returns whether or not the value is an outgoing value. | |
215 * | |
216 * @param value The value. | |
217 * | |
218 * @return TRUE if the value is outgoing, or FALSE otherwise. | |
219 */ | |
220 gboolean gaim_value_is_outgoing(const GaimValue *value); | |
221 | |
222 /** | |
223 * Sets the value's character data. | |
224 * | |
225 * @param value The value. | |
226 * @param data The character data. | |
227 */ | |
228 void gaim_value_set_char(GaimValue *value, char data); | |
229 | |
230 /** | |
231 * Sets the value's unsigned character data. | |
232 * | |
233 * @param value The value. | |
234 * @param data The unsigned character data. | |
235 */ | |
236 void gaim_value_set_uchar(GaimValue *value, unsigned char data); | |
237 | |
238 /** | |
239 * Sets the value's boolean data. | |
240 * | |
241 * @param value The value. | |
242 * @param data The boolean data. | |
243 */ | |
244 void gaim_value_set_boolean(GaimValue *value, gboolean data); | |
245 | |
246 /** | |
247 * Sets the value's short integer data. | |
248 * | |
249 * @param value The value. | |
250 * @param data The short integer data. | |
251 */ | |
252 void gaim_value_set_short(GaimValue *value, short data); | |
253 | |
254 /** | |
255 * Sets the value's unsigned short integer data. | |
256 * | |
257 * @param value The value. | |
258 * @param data The unsigned short integer data. | |
259 */ | |
260 void gaim_value_set_ushort(GaimValue *value, unsigned short data); | |
261 | |
262 /** | |
263 * Sets the value's integer data. | |
264 * | |
265 * @param value The value. | |
266 * @param data The integer data. | |
267 */ | |
268 void gaim_value_set_int(GaimValue *value, int data); | |
269 | |
270 /** | |
271 * Sets the value's unsigned integer data. | |
272 * | |
273 * @param value The value. | |
274 * @param data The unsigned integer data. | |
275 */ | |
276 void gaim_value_set_uint(GaimValue *value, unsigned int data); | |
277 | |
278 /** | |
279 * Sets the value's long integer data. | |
280 * | |
281 * @param value The value. | |
282 * @param data The long integer data. | |
283 */ | |
284 void gaim_value_set_long(GaimValue *value, long data); | |
285 | |
286 /** | |
287 * Sets the value's unsigned long integer data. | |
288 * | |
289 * @param value The value. | |
290 * @param data The unsigned long integer data. | |
291 */ | |
292 void gaim_value_set_ulong(GaimValue *value, unsigned long data); | |
293 | |
294 /** | |
295 * Sets the value's 64-bit integer data. | |
296 * | |
297 * @param value The value. | |
298 * @param data The 64-bit integer data. | |
299 */ | |
300 void gaim_value_set_int64(GaimValue *value, gint64 data); | |
301 | |
302 /** | |
303 * Sets the value's unsigned 64-bit integer data. | |
304 * | |
305 * @param value The value. | |
306 * @param data The unsigned 64-bit integer data. | |
307 */ | |
308 void gaim_value_set_uint64(GaimValue *value, guint64 data); | |
309 | |
310 /** | |
311 * Sets the value's string data. | |
312 * | |
313 * @param value The value. | |
314 * @param data The string data. | |
315 */ | |
316 void gaim_value_set_string(GaimValue *value, const char *data); | |
317 | |
318 /** | |
319 * Sets the value's object data. | |
320 * | |
321 * @param value The value. | |
322 * @param data The object data. | |
323 */ | |
324 void gaim_value_set_object(GaimValue *value, void *data); | |
325 | |
326 /** | |
327 * Sets the value's pointer data. | |
328 * | |
329 * @param value The value. | |
330 * @param data The pointer data. | |
331 */ | |
332 void gaim_value_set_pointer(GaimValue *value, void *data); | |
333 | |
334 /** | |
335 * Sets the value's enum data. | |
336 * | |
337 * @param value The value. | |
338 * @param data The enum data. | |
339 */ | |
340 void gaim_value_set_enum(GaimValue *value, int data); | |
341 | |
342 /** | |
343 * Sets the value's boxed data. | |
344 * | |
345 * @param value The value. | |
346 * @param data The boxed data. | |
347 */ | |
348 void gaim_value_set_boxed(GaimValue *value, void *data); | |
349 | |
350 /** | |
351 * Returns the value's character data. | |
352 * | |
353 * @param value The value. | |
354 * | |
355 * @return The character data. | |
356 */ | |
357 char gaim_value_get_char(const GaimValue *value); | |
358 | |
359 /** | |
360 * Returns the value's unsigned character data. | |
361 * | |
362 * @param value The value. | |
363 * | |
364 * @return The unsigned character data. | |
365 */ | |
366 unsigned char gaim_value_get_uchar(const GaimValue *value); | |
367 | |
368 /** | |
369 * Returns the value's boolean data. | |
370 * | |
371 * @param value The value. | |
372 * | |
373 * @return The boolean data. | |
374 */ | |
375 gboolean gaim_value_get_boolean(const GaimValue *value); | |
376 | |
377 /** | |
378 * Returns the value's short integer data. | |
379 * | |
380 * @param value The value. | |
381 * | |
382 * @return The short integer data. | |
383 */ | |
384 short gaim_value_get_short(const GaimValue *value); | |
385 | |
386 /** | |
387 * Returns the value's unsigned short integer data. | |
388 * | |
389 * @param value The value. | |
390 * | |
391 * @return The unsigned short integer data. | |
392 */ | |
393 unsigned short gaim_value_get_ushort(const GaimValue *value); | |
394 | |
395 /** | |
396 * Returns the value's integer data. | |
397 * | |
398 * @param value The value. | |
399 * | |
400 * @return The integer data. | |
401 */ | |
402 int gaim_value_get_int(const GaimValue *value); | |
403 | |
404 /** | |
405 * Returns the value's unsigned integer data. | |
406 * | |
407 * @param value The value. | |
408 * | |
409 * @return The unsigned integer data. | |
410 */ | |
411 unsigned int gaim_value_get_uint(const GaimValue *value); | |
412 | |
413 /** | |
414 * Returns the value's long integer data. | |
415 * | |
416 * @param value The value. | |
417 * | |
418 * @return The long integer data. | |
419 */ | |
420 long gaim_value_get_long(const GaimValue *value); | |
421 | |
422 /** | |
423 * Returns the value's unsigned long integer data. | |
424 * | |
425 * @param value The value. | |
426 * | |
427 * @return The unsigned long integer data. | |
428 */ | |
429 unsigned long gaim_value_get_ulong(const GaimValue *value); | |
430 | |
431 /** | |
432 * Returns the value's 64-bit integer data. | |
433 * | |
434 * @param value The value. | |
435 * | |
436 * @return The 64-bit integer data. | |
437 */ | |
438 gint64 gaim_value_get_int64(const GaimValue *value); | |
439 | |
440 /** | |
441 * Returns the value's unsigned 64-bit integer data. | |
442 * | |
443 * @param value The value. | |
444 * | |
445 * @return The unsigned 64-bit integer data. | |
446 */ | |
447 guint64 gaim_value_get_uint64(const GaimValue *value); | |
448 | |
449 /** | |
450 * Returns the value's string data. | |
451 * | |
452 * @param value The value. | |
453 * | |
454 * @return The string data. | |
455 */ | |
456 const char *gaim_value_get_string(const GaimValue *value); | |
457 | |
458 /** | |
459 * Returns the value's object data. | |
460 * | |
461 * @param value The value. | |
462 * | |
463 * @return The object data. | |
464 */ | |
465 void *gaim_value_get_object(const GaimValue *value); | |
466 | |
467 /** | |
468 * Returns the value's pointer data. | |
469 * | |
470 * @param value The value. | |
471 * | |
472 * @return The pointer data. | |
473 */ | |
474 void *gaim_value_get_pointer(const GaimValue *value); | |
475 | |
476 /** | |
477 * Returns the value's enum data. | |
478 * | |
479 * @param value The value. | |
480 * | |
481 * @return The enum data. | |
482 */ | |
483 int gaim_value_get_enum(const GaimValue *value); | |
484 | |
485 /** | |
486 * Returns the value's boxed data. | |
487 * | |
488 * @param value The value. | |
489 * | |
490 * @return The boxed data. | |
491 */ | |
492 void *gaim_value_get_boxed(const GaimValue *value); | |
493 | |
6563
122cb375be2d
[gaim-migrate @ 7085]
Christian Hammond <chipx86@chipx86.com>
parents:
6562
diff
changeset
|
494 #ifdef __cplusplus |
122cb375be2d
[gaim-migrate @ 7085]
Christian Hammond <chipx86@chipx86.com>
parents:
6562
diff
changeset
|
495 } |
122cb375be2d
[gaim-migrate @ 7085]
Christian Hammond <chipx86@chipx86.com>
parents:
6562
diff
changeset
|
496 #endif |
122cb375be2d
[gaim-migrate @ 7085]
Christian Hammond <chipx86@chipx86.com>
parents:
6562
diff
changeset
|
497 |
6562 | 498 #endif /* _GAIM_VALUE_H_ */ |