1 /** 2 * @file value.h Value wrapper API 3 * @ingroup core 4 */ 5 6 /* purple 7 * 8 * Purple is the legal property of its developers, whose names are too numerous 9 * to list here. Please refer to the COPYRIGHT file distributed with this 10 * source distribution. 11 * 12 * This program is free software; you can redistribute it and/or modify 13 * it under the terms of the GNU General Public License as published by 14 * the Free Software Foundation; either version 2 of the License, or 15 * (at your option) any later version. 16 * 17 * This program is distributed in the hope that it will be useful, 18 * but WITHOUT ANY WARRANTY; without even the implied warranty of 19 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 20 * GNU General Public License for more details. 21 * 22 * You should have received a copy of the GNU General Public License 23 * along with this program; if not, write to the Free Software 24 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02111-1301 USA 25 */ 26 #ifndef _PURPLE_VALUE_H_ 27 #define _PURPLE_VALUE_H_ 28 29 #include <glib.h> 30 31 /** 32 * Specific value types. 33 */ 34 typedef enum 35 { 36 PURPLE_TYPE_UNKNOWN = 0, /**< Unknown type. */ 37 PURPLE_TYPE_SUBTYPE, /**< Subtype. */ 38 PURPLE_TYPE_CHAR, /**< Character. */ 39 PURPLE_TYPE_UCHAR, /**< Unsigned character. */ 40 PURPLE_TYPE_BOOLEAN, /**< Boolean. */ 41 PURPLE_TYPE_SHORT, /**< Short integer. */ 42 PURPLE_TYPE_USHORT, /**< Unsigned short integer. */ 43 PURPLE_TYPE_INT, /**< Integer. */ 44 PURPLE_TYPE_UINT, /**< Unsigned integer. */ 45 PURPLE_TYPE_LONG, /**< Long integer. */ 46 PURPLE_TYPE_ULONG, /**< Unsigned long integer. */ 47 PURPLE_TYPE_INT64, /**< 64-bit integer. */ 48 PURPLE_TYPE_UINT64, /**< 64-bit unsigned integer. */ 49 PURPLE_TYPE_STRING, /**< String. */ 50 PURPLE_TYPE_OBJECT, /**< Object pointer. */ 51 PURPLE_TYPE_POINTER, /**< Generic pointer. */ 52 PURPLE_TYPE_ENUM, /**< Enum. */ 53 PURPLE_TYPE_BOXED /**< Boxed pointer with specific type. */ 54 55 } PurpleType; 56 57 58 /** 59 * Purple-specific subtype values. 60 */ 61 typedef enum 62 { 63 PURPLE_SUBTYPE_UNKNOWN = 0, 64 PURPLE_SUBTYPE_ACCOUNT, 65 PURPLE_SUBTYPE_BLIST, 66 PURPLE_SUBTYPE_BLIST_BUDDY, 67 PURPLE_SUBTYPE_BLIST_GROUP, 68 PURPLE_SUBTYPE_BLIST_CHAT, 69 PURPLE_SUBTYPE_BUDDY_ICON, 70 PURPLE_SUBTYPE_CONNECTION, 71 PURPLE_SUBTYPE_CONVERSATION, 72 PURPLE_SUBTYPE_PLUGIN, 73 PURPLE_SUBTYPE_BLIST_NODE, 74 PURPLE_SUBTYPE_CIPHER, 75 PURPLE_SUBTYPE_STATUS, 76 PURPLE_SUBTYPE_LOG, 77 PURPLE_SUBTYPE_XFER, 78 PURPLE_SUBTYPE_SAVEDSTATUS, 79 PURPLE_SUBTYPE_XMLNODE, 80 PURPLE_SUBTYPE_USERINFO, 81 PURPLE_SUBTYPE_STORED_IMAGE, 82 PURPLE_SUBTYPE_CERTIFICATEPOOL, 83 PURPLE_SUBTYPE_CHATBUDDY 84 } PurpleSubType; 85 86 /** 87 * A wrapper for a type, subtype, and specific type of value. 88 */ 89 typedef struct 90 { 91 PurpleType type; 92 unsigned short flags; 93 94 union 95 { 96 char char_data; 97 unsigned char uchar_data; 98 gboolean boolean_data; 99 short short_data; 100 unsigned short ushort_data; 101 int int_data; 102 unsigned int uint_data; 103 long long_data; 104 unsigned long ulong_data; 105 gint64 int64_data; 106 guint64 uint64_data; 107 char *string_data; 108 void *object_data; 109 void *pointer_data; 110 int enum_data; 111 void *boxed_data; 112 113 } data; 114 115 union 116 { 117 unsigned int subtype; 118 char *specific_type; 119 120 } u; 121 122 } PurpleValue; 123 124 #ifdef __cplusplus 125 extern "C" { 126 #endif 127 128 /** 129 * Creates a new PurpleValue. 130 * 131 * This function takes a type and, depending on that type, a sub-type 132 * or specific type. 133 * 134 * If @a type is PURPLE_TYPE_BOXED, the next parameter must be a 135 * string representing the specific type. 136 * 137 * If @a type is PURPLE_TYPE_SUBTYPE, the next parameter must be a 138 * integer or enum representing the sub-type. 139 * 140 * If the subtype or specific type is not set when required, random 141 * errors may occur. You have been warned. 142 * 143 * @param type The type. 144 * 145 * @return The new value. 146 */ 147 PurpleValue *purple_value_new(PurpleType type, ...); 148 149 /** 150 * Creates a new outgoing PurpleValue. If a value is an "outgoing" value 151 * it means the value can be modified by plugins and scripts. 152 * 153 * This function takes a type and, depending on that type, a sub-type 154 * or specific type. 155 * 156 * If @a type is PURPLE_TYPE_BOXED, the next parameter must be a 157 * string representing the specific type. 158 * 159 * If @a type is PURPLE_TYPE_SUBTYPE, the next parameter must be a 160 * integer or enum representing the sub-type. 161 * 162 * If the sub-type or specific type is not set when required, random 163 * errors may occur. You have been warned. 164 * 165 * @param type The type. 166 * 167 * @return The new value. 168 */ 169 PurpleValue *purple_value_new_outgoing(PurpleType type, ...); 170 171 /** 172 * Destroys a PurpleValue. 173 * 174 * @param value The value to destroy. 175 */ 176 void purple_value_destroy(PurpleValue *value); 177 178 /** 179 * Duplicated a PurpleValue. 180 * 181 * @param value The value to duplicate. 182 * 183 * @return The duplicate value. 184 */ 185 PurpleValue *purple_value_dup(const PurpleValue *value); 186 187 /** 188 * Returns a value's type. 189 * 190 * @param value The value whose type you want. 191 * 192 * @return The value's type. 193 */ 194 PurpleType purple_value_get_type(const PurpleValue *value); 195 196 /** 197 * Returns a value's subtype. 198 * 199 * If the value's type is not PURPLE_TYPE_SUBTYPE, this will return 0. 200 * Subtypes should never have a subtype of 0. 201 * 202 * @param value The value whose subtype you want. 203 * 204 * @return The value's subtype, or 0 if @a type is not PURPLE_TYPE_SUBTYPE. 205 */ 206 unsigned int purple_value_get_subtype(const PurpleValue *value); 207 208 /** 209 * Returns a value's specific type. 210 * 211 * If the value's type is not PURPLE_TYPE_BOXED, this will return @c NULL. 212 * 213 * @param value The value whose specific type you want. 214 * 215 * @return The value's specific type, or @a NULL if not PURPLE_TYPE_BOXED. 216 */ 217 const char *purple_value_get_specific_type(const PurpleValue *value); 218 219 /** 220 * Returns whether or not the value is an outgoing value. 221 * 222 * @param value The value. 223 * 224 * @return TRUE if the value is outgoing, or FALSE otherwise. 225 */ 226 gboolean purple_value_is_outgoing(const PurpleValue *value); 227 228 /** 229 * Sets the value's character data. 230 * 231 * @param value The value. 232 * @param data The character data. 233 */ 234 void purple_value_set_char(PurpleValue *value, char data); 235 236 /** 237 * Sets the value's unsigned character data. 238 * 239 * @param value The value. 240 * @param data The unsigned character data. 241 */ 242 void purple_value_set_uchar(PurpleValue *value, unsigned char data); 243 244 /** 245 * Sets the value's boolean data. 246 * 247 * @param value The value. 248 * @param data The boolean data. 249 */ 250 void purple_value_set_boolean(PurpleValue *value, gboolean data); 251 252 /** 253 * Sets the value's short integer data. 254 * 255 * @param value The value. 256 * @param data The short integer data. 257 */ 258 void purple_value_set_short(PurpleValue *value, short data); 259 260 /** 261 * Sets the value's unsigned short integer data. 262 * 263 * @param value The value. 264 * @param data The unsigned short integer data. 265 */ 266 void purple_value_set_ushort(PurpleValue *value, unsigned short data); 267 268 /** 269 * Sets the value's integer data. 270 * 271 * @param value The value. 272 * @param data The integer data. 273 */ 274 void purple_value_set_int(PurpleValue *value, int data); 275 276 /** 277 * Sets the value's unsigned integer data. 278 * 279 * @param value The value. 280 * @param data The unsigned integer data. 281 */ 282 void purple_value_set_uint(PurpleValue *value, unsigned int data); 283 284 /** 285 * Sets the value's long integer data. 286 * 287 * @param value The value. 288 * @param data The long integer data. 289 */ 290 void purple_value_set_long(PurpleValue *value, long data); 291 292 /** 293 * Sets the value's unsigned long integer data. 294 * 295 * @param value The value. 296 * @param data The unsigned long integer data. 297 */ 298 void purple_value_set_ulong(PurpleValue *value, unsigned long data); 299 300 /** 301 * Sets the value's 64-bit integer data. 302 * 303 * @param value The value. 304 * @param data The 64-bit integer data. 305 */ 306 void purple_value_set_int64(PurpleValue *value, gint64 data); 307 308 /** 309 * Sets the value's unsigned 64-bit integer data. 310 * 311 * @param value The value. 312 * @param data The unsigned 64-bit integer data. 313 */ 314 void purple_value_set_uint64(PurpleValue *value, guint64 data); 315 316 /** 317 * Sets the value's string data. 318 * 319 * @param value The value. 320 * @param data The string data. 321 */ 322 void purple_value_set_string(PurpleValue *value, const char *data); 323 324 /** 325 * Sets the value's object data. 326 * 327 * @param value The value. 328 * @param data The object data. 329 */ 330 void purple_value_set_object(PurpleValue *value, void *data); 331 332 /** 333 * Sets the value's pointer data. 334 * 335 * @param value The value. 336 * @param data The pointer data. 337 */ 338 void purple_value_set_pointer(PurpleValue *value, void *data); 339 340 /** 341 * Sets the value's enum data. 342 * 343 * @param value The value. 344 * @param data The enum data. 345 */ 346 void purple_value_set_enum(PurpleValue *value, int data); 347 348 /** 349 * Sets the value's boxed data. 350 * 351 * @param value The value. 352 * @param data The boxed data. 353 */ 354 void purple_value_set_boxed(PurpleValue *value, void *data); 355 356 /** 357 * Returns the value's character data. 358 * 359 * @param value The value. 360 * 361 * @return The character data. 362 */ 363 char purple_value_get_char(const PurpleValue *value); 364 365 /** 366 * Returns the value's unsigned character data. 367 * 368 * @param value The value. 369 * 370 * @return The unsigned character data. 371 */ 372 unsigned char purple_value_get_uchar(const PurpleValue *value); 373 374 /** 375 * Returns the value's boolean data. 376 * 377 * @param value The value. 378 * 379 * @return The boolean data. 380 */ 381 gboolean purple_value_get_boolean(const PurpleValue *value); 382 383 /** 384 * Returns the value's short integer data. 385 * 386 * @param value The value. 387 * 388 * @return The short integer data. 389 */ 390 short purple_value_get_short(const PurpleValue *value); 391 392 /** 393 * Returns the value's unsigned short integer data. 394 * 395 * @param value The value. 396 * 397 * @return The unsigned short integer data. 398 */ 399 unsigned short purple_value_get_ushort(const PurpleValue *value); 400 401 /** 402 * Returns the value's integer data. 403 * 404 * @param value The value. 405 * 406 * @return The integer data. 407 */ 408 int purple_value_get_int(const PurpleValue *value); 409 410 /** 411 * Returns the value's unsigned integer data. 412 * 413 * @param value The value. 414 * 415 * @return The unsigned integer data. 416 */ 417 unsigned int purple_value_get_uint(const PurpleValue *value); 418 419 /** 420 * Returns the value's long integer data. 421 * 422 * @param value The value. 423 * 424 * @return The long integer data. 425 */ 426 long purple_value_get_long(const PurpleValue *value); 427 428 /** 429 * Returns the value's unsigned long integer data. 430 * 431 * @param value The value. 432 * 433 * @return The unsigned long integer data. 434 */ 435 unsigned long purple_value_get_ulong(const PurpleValue *value); 436 437 /** 438 * Returns the value's 64-bit integer data. 439 * 440 * @param value The value. 441 * 442 * @return The 64-bit integer data. 443 */ 444 gint64 purple_value_get_int64(const PurpleValue *value); 445 446 /** 447 * Returns the value's unsigned 64-bit integer data. 448 * 449 * @param value The value. 450 * 451 * @return The unsigned 64-bit integer data. 452 */ 453 guint64 purple_value_get_uint64(const PurpleValue *value); 454 455 /** 456 * Returns the value's string data. 457 * 458 * @param value The value. 459 * 460 * @return The string data. 461 */ 462 const char *purple_value_get_string(const PurpleValue *value); 463 464 /** 465 * Returns the value's object data. 466 * 467 * @param value The value. 468 * 469 * @return The object data. 470 */ 471 void *purple_value_get_object(const PurpleValue *value); 472 473 /** 474 * Returns the value's pointer data. 475 * 476 * @param value The value. 477 * 478 * @return The pointer data. 479 */ 480 void *purple_value_get_pointer(const PurpleValue *value); 481 482 /** 483 * Returns the value's enum data. 484 * 485 * @param value The value. 486 * 487 * @return The enum data. 488 */ 489 int purple_value_get_enum(const PurpleValue *value); 490 491 /** 492 * Returns the value's boxed data. 493 * 494 * @param value The value. 495 * 496 * @return The boxed data. 497 */ 498 void *purple_value_get_boxed(const PurpleValue *value); 499 500 #ifdef __cplusplus 501 } 502 #endif 503 504 #endif /* _PURPLE_VALUE_H_ */ 505