Frameworks/libpurple.framework/Versions/2.10.12r8d2874a79747/Headers/value.h
branchadium-1.5.11
changeset 6014 fcb71cb71a3d
parent 5941 307f53385811
parent 6013 f8d0dc659e3f
child 6016 325e2ab3406f
equal deleted inserted replaced
5941:307f53385811 6014:fcb71cb71a3d
     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_ */