annotate libgaim/value.h @ 14303:d9aa45c10588

[gaim-migrate @ 16993] Patch from wabz (Richard Nelson): Do not crash when there are too many popups. Move the new ones to a different column instead. committer: Tailor Script <[e-mail]>

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