Mercurial > pidgin3 / file comparison

comparison: libgaim/value.h

libgaim/value.h

branch
cpw.khc.msnp14
changeset 20472
6a6d2ef151e6
parent 13388
56132ad4179e
parent 15326
84d9b06b591e
equal deleted inserted replaced
13912:463b4fa9f067 20472:6a6d2ef151e6
1 /**
2 * @file value.h Value wrapper API
3 * @ingroup core
4 *
5 * gaim
6 *
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.
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
28 #include <glib.h>
29
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
56
57 /**
58 * Gaim-specific subtype values.
59 */
60 typedef enum
61 {
62 GAIM_SUBTYPE_UNKNOWN = 0,
63 GAIM_SUBTYPE_ACCOUNT,
64 GAIM_SUBTYPE_BLIST,
65 GAIM_SUBTYPE_BLIST_BUDDY,
66 GAIM_SUBTYPE_BLIST_GROUP,
67 GAIM_SUBTYPE_BLIST_CHAT,
68 GAIM_SUBTYPE_BUDDY_ICON,
69 GAIM_SUBTYPE_CONNECTION,
70 GAIM_SUBTYPE_CONVERSATION,
71 GAIM_SUBTYPE_PLUGIN,
72 GAIM_SUBTYPE_BLIST_NODE,
73 GAIM_SUBTYPE_CIPHER,
74 GAIM_SUBTYPE_STATUS,
75 GAIM_SUBTYPE_LOG,
76 GAIM_SUBTYPE_XFER,
77 GAIM_SUBTYPE_SAVEDSTATUS,
78 GAIM_SUBTYPE_XMLNODE,
79 GAIM_SUBTYPE_USERINFO
80 } GaimSubType;
81
82 /**
83 * A wrapper for a type, subtype, and specific type of value.
84 */
85 typedef struct
86 {
87 GaimType type;
88 unsigned short flags;
89
90 union
91 {
92 char char_data;
93 unsigned char uchar_data;
94 gboolean boolean_data;
95 short short_data;
96 unsigned short ushort_data;
97 int int_data;
98 unsigned int uint_data;
99 long long_data;
100 unsigned long ulong_data;
101 gint64 int64_data;
102 guint64 uint64_data;
103 char *string_data;
104 void *object_data;
105 void *pointer_data;
106 int enum_data;
107 void *boxed_data;
108
109 } data;
110
111 union
112 {
113 unsigned int subtype;
114 char *specific_type;
115
116 } u;
117
118 } GaimValue;
119
120 #ifdef __cplusplus
121 extern "C" {
122 #endif
123
124 /**
125 * Creates a new GaimValue.
126 *
127 * This function takes a type and, depending on that type, a sub-type
128 * or specific type.
129 *
130 * If @a type is GAIM_TYPE_BOXED, the next parameter must be a
131 * string representing the specific type.
132 *
133 * If @a type is GAIM_TYPE_SUBTYPE, the next parameter must be a
134 * integer or enum representing the sub-type.
135 *
136 * If the subtype or specific type is not set when required, random
137 * errors may occur. You have been warned.
138 *
139 * @param type The type.
140 *
141 * @return The new value.
142 */
143 GaimValue *gaim_value_new(GaimType type, ...);
144
145 /**
146 * Creates a new outgoing GaimValue. If a value is an "outgoing" value
147 * it means the value can be modified by plugins and scripts.
148 *
149 * This function takes a type and, depending on that type, a sub-type
150 * or specific type.
151 *
152 * If @a type is GAIM_TYPE_BOXED, the next parameter must be a
153 * string representing the specific type.
154 *
155 * If @a type is GAIM_TYPE_SUBTYPE, the next parameter must be a
156 * integer or enum representing the sub-type.
157 *
158 * If the sub-type or specific type is not set when required, random
159 * errors may occur. You have been warned.
160 *
161 * @param type The type.
162 *
163 * @return The new value.
164 */
165 GaimValue *gaim_value_new_outgoing(GaimType type, ...);
166
167 /**
168 * Destroys a GaimValue.
169 *
170 * @param value The value to destroy.
171 */
172 void gaim_value_destroy(GaimValue *value);
173
174 /**
175 * Duplicated a GaimValue.
176 *
177 * @param value The value to duplicate.
178 *
179 * @return The duplicate value.
180 */
181 GaimValue *gaim_value_dup(const GaimValue *value);
182
183 /**
184 * Returns a value's type.
185 *
186 * @param value The value whose type you want.
187 *
188 * @return The value's type.
189 */
190 GaimType gaim_value_get_type(const GaimValue *value);
191
192 /**
193 * Returns a value's subtype.
194 *
195 * If the value's type is not GAIM_TYPE_SUBTYPE, this will return 0.
196 * Subtypes should never have a subtype of 0.
197 *
198 * @param value The value whose subtype you want.
199 *
200 * @return The value's subtype, or 0 if @a type is not GAIM_TYPE_SUBTYPE.
201 */
202 unsigned int gaim_value_get_subtype(const GaimValue *value);
203
204 /**
205 * Returns a value's specific type.
206 *
207 * If the value's type is not GAIM_TYPE_BOXED, this will return @c NULL.
208 *
209 * @param value The value whose specific type you want.
210 *
211 * @return The value's specific type, or @a NULL if not GAIM_TYPE_BOXED.
212 */
213 const char *gaim_value_get_specific_type(const GaimValue *value);
214
215 /**
216 * Returns whether or not the value is an outgoing value.
217 *
218 * @param value The value.
219 *
220 * @return TRUE if the value is outgoing, or FALSE otherwise.
221 */
222 gboolean gaim_value_is_outgoing(const GaimValue *value);
223
224 /**
225 * Sets the value's character data.
226 *
227 * @param value The value.
228 * @param data The character data.
229 */
230 void gaim_value_set_char(GaimValue *value, char data);
231
232 /**
233 * Sets the value's unsigned character data.
234 *
235 * @param value The value.
236 * @param data The unsigned character data.
237 */
238 void gaim_value_set_uchar(GaimValue *value, unsigned char data);
239
240 /**
241 * Sets the value's boolean data.
242 *
243 * @param value The value.
244 * @param data The boolean data.
245 */
246 void gaim_value_set_boolean(GaimValue *value, gboolean data);
247
248 /**
249 * Sets the value's short integer data.
250 *
251 * @param value The value.
252 * @param data The short integer data.
253 */
254 void gaim_value_set_short(GaimValue *value, short data);
255
256 /**
257 * Sets the value's unsigned short integer data.
258 *
259 * @param value The value.
260 * @param data The unsigned short integer data.
261 */
262 void gaim_value_set_ushort(GaimValue *value, unsigned short data);
263
264 /**
265 * Sets the value's integer data.
266 *
267 * @param value The value.
268 * @param data The integer data.
269 */
270 void gaim_value_set_int(GaimValue *value, int data);
271
272 /**
273 * Sets the value's unsigned integer data.
274 *
275 * @param value The value.
276 * @param data The unsigned integer data.
277 */
278 void gaim_value_set_uint(GaimValue *value, unsigned int data);
279
280 /**
281 * Sets the value's long integer data.
282 *
283 * @param value The value.
284 * @param data The long integer data.
285 */
286 void gaim_value_set_long(GaimValue *value, long data);
287
288 /**
289 * Sets the value's unsigned long integer data.
290 *
291 * @param value The value.
292 * @param data The unsigned long integer data.
293 */
294 void gaim_value_set_ulong(GaimValue *value, unsigned long data);
295
296 /**
297 * Sets the value's 64-bit integer data.
298 *
299 * @param value The value.
300 * @param data The 64-bit integer data.
301 */
302 void gaim_value_set_int64(GaimValue *value, gint64 data);
303
304 /**
305 * Sets the value's unsigned 64-bit integer data.
306 *
307 * @param value The value.
308 * @param data The unsigned 64-bit integer data.
309 */
310 void gaim_value_set_uint64(GaimValue *value, guint64 data);
311
312 /**
313 * Sets the value's string data.
314 *
315 * @param value The value.
316 * @param data The string data.
317 */
318 void gaim_value_set_string(GaimValue *value, const char *data);
319
320 /**
321 * Sets the value's object data.
322 *
323 * @param value The value.
324 * @param data The object data.
325 */
326 void gaim_value_set_object(GaimValue *value, void *data);
327
328 /**
329 * Sets the value's pointer data.
330 *
331 * @param value The value.
332 * @param data The pointer data.
333 */
334 void gaim_value_set_pointer(GaimValue *value, void *data);
335
336 /**
337 * Sets the value's enum data.
338 *
339 * @param value The value.
340 * @param data The enum data.
341 */
342 void gaim_value_set_enum(GaimValue *value, int data);
343
344 /**
345 * Sets the value's boxed data.
346 *
347 * @param value The value.
348 * @param data The boxed data.
349 */
350 void gaim_value_set_boxed(GaimValue *value, void *data);
351
352 /**
353 * Returns the value's character data.
354 *
355 * @param value The value.
356 *
357 * @return The character data.
358 */
359 char gaim_value_get_char(const GaimValue *value);
360
361 /**
362 * Returns the value's unsigned character data.
363 *
364 * @param value The value.
365 *
366 * @return The unsigned character data.
367 */
368 unsigned char gaim_value_get_uchar(const GaimValue *value);
369
370 /**
371 * Returns the value's boolean data.
372 *
373 * @param value The value.
374 *
375 * @return The boolean data.
376 */
377 gboolean gaim_value_get_boolean(const GaimValue *value);
378
379 /**
380 * Returns the value's short integer data.
381 *
382 * @param value The value.
383 *
384 * @return The short integer data.
385 */
386 short gaim_value_get_short(const GaimValue *value);
387
388 /**
389 * Returns the value's unsigned short integer data.
390 *
391 * @param value The value.
392 *
393 * @return The unsigned short integer data.
394 */
395 unsigned short gaim_value_get_ushort(const GaimValue *value);
396
397 /**
398 * Returns the value's integer data.
399 *
400 * @param value The value.
401 *
402 * @return The integer data.
403 */
404 int gaim_value_get_int(const GaimValue *value);
405
406 /**
407 * Returns the value's unsigned integer data.
408 *
409 * @param value The value.
410 *
411 * @return The unsigned integer data.
412 */
413 unsigned int gaim_value_get_uint(const GaimValue *value);
414
415 /**
416 * Returns the value's long integer data.
417 *
418 * @param value The value.
419 *
420 * @return The long integer data.
421 */
422 long gaim_value_get_long(const GaimValue *value);
423
424 /**
425 * Returns the value's unsigned long integer data.
426 *
427 * @param value The value.
428 *
429 * @return The unsigned long integer data.
430 */
431 unsigned long gaim_value_get_ulong(const GaimValue *value);
432
433 /**
434 * Returns the value's 64-bit integer data.
435 *
436 * @param value The value.
437 *
438 * @return The 64-bit integer data.
439 */
440 gint64 gaim_value_get_int64(const GaimValue *value);
441
442 /**
443 * Returns the value's unsigned 64-bit integer data.
444 *
445 * @param value The value.
446 *
447 * @return The unsigned 64-bit integer data.
448 */
449 guint64 gaim_value_get_uint64(const GaimValue *value);
450
451 /**
452 * Returns the value's string data.
453 *
454 * @param value The value.
455 *
456 * @return The string data.
457 */
458 const char *gaim_value_get_string(const GaimValue *value);
459
460 /**
461 * Returns the value's object data.
462 *
463 * @param value The value.
464 *
465 * @return The object data.
466 */
467 void *gaim_value_get_object(const GaimValue *value);
468
469 /**
470 * Returns the value's pointer data.
471 *
472 * @param value The value.
473 *
474 * @return The pointer data.
475 */
476 void *gaim_value_get_pointer(const GaimValue *value);
477
478 /**
479 * Returns the value's enum data.
480 *
481 * @param value The value.
482 *
483 * @return The enum data.
484 */
485 int gaim_value_get_enum(const GaimValue *value);
486
487 /**
488 * Returns the value's boxed data.
489 *
490 * @param value The value.
491 *
492 * @return The boxed data.
493 */
494 void *gaim_value_get_boxed(const GaimValue *value);
495
496 #ifdef __cplusplus
497 }
498 #endif
499
500 #endif /* _GAIM_VALUE_H_ */

Mercurial Repository: pidgin3

mercurial