libpurple/value.h

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