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