src/include/gnunet_psyc_env.h

   1 /*
   2  * This file is part of GNUnet.
   3  * Copyright (C) 2013 GNUnet e.V.
   4  *
   5  * GNUnet is free software; you can redistribute it and/or modify
   6  * it under the terms of the GNU General Public License as published
   7  * by the Free Software Foundation; either version 3, or (at your
   8  * option) any later version.
   9  *
  10  * GNUnet is distributed in the hope that it will be useful, but
  11  * WITHOUT ANY WARRANTY; without even the implied warranty of
  12  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  13  * General Public License for more details.
  14  *
  15  * You should have received a copy of the GNU General Public License
  16  * along with GNUnet; see the file COPYING.  If not, write to the
  17  * Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
  18  * Boston, MA 02110-1301, USA.
  19  */
  20
  21 /**
  22  * @author Gabor X Toth
  23  *
  24  * @file
  25  * PSYC Environment library
  26  *
  27  * @defgroup psyc-util-env  PSYC Utilities library: Environment
  28  * Environment data structure operations for PSYC and Social messages.
  29  *
  30  * Library providing operations for the @e environment of
  31  * PSYC and Social messages, and for (de)serializing variable values.
  32  *
  33  * @{
  34  */
  35
  36
  37 #ifndef GNUNET_PSYC_ENV_H
  38 #define GNUNET_PSYC_ENV_H
  39
  40 #ifdef __cplusplus
  41 extern "C"
  42 {
  43 #if 0                           /* keep Emacsens' auto-indent happy */
  44 }
  45 #endif
  46 #endif
  47
  48
  49 /**
  50  * Possible operations on PSYC state (persistent) and transient variables (per message).
  51  */
  52 enum GNUNET_PSYC_Operator
  53 {
  54   /**
  55    * Set value of a transient variable.
  56    */
  57   GNUNET_PSYC_OP_SET = ':',
  58
  59   /**
  60    * Assign value for a persistent state variable.
  61    *
  62    * If an assigned value is NULL, the variable is deleted.
  63    */
  64   GNUNET_PSYC_OP_ASSIGN = '=',
  65
  66   /**
  67    * Augment state variable.
  68    *
  69    * Used for appending strings, adding numbers, and adding new items to a list or dictionary.
  70    */
  71   GNUNET_PSYC_OP_AUGMENT = '+',
  72
  73   /**
  74    * Diminish state variable.
  75    *
  76    * Used for subtracting numbers, and removing items from a list or dictionary.
  77    */
  78   GNUNET_PSYC_OP_DIMINISH = '-',
  79
  80   /**
  81    * Update state variable.
  82    *
  83    * Used for modifying a single item of a list or dictionary.
  84    */
  85   GNUNET_PSYC_OP_UPDATE = '@',
  86 };
  87
  88
  89 /**
  90  * PSYC variable types.
  91  */
  92 enum GNUNET_PSYC_Type
  93 {
  94   GNUNET_PSYC_TYPE_DATA = 0,
  95   GNUNET_PSYC_TYPE_NUMBER,
  96   GNUNET_PSYC_TYPE_LIST,
  97   GNUNET_PSYC_TYPE_DICT
  98 };
  99
 100
 101 /**
 102  * PSYC state modifier.
 103  */
 104 struct GNUNET_PSYC_Modifier
 105 {
 106   /**
 107    * State operation.
 108    */
 109   enum GNUNET_PSYC_Operator oper;
 110
 111   /**
 112    * Variable name.
 113    */
 114   const char *name;
 115
 116   /**
 117    * Size of @a value.
 118    */
 119   size_t value_size;
 120
 121   /**
 122    * Value of variable.
 123    */
 124   const void *value;
 125
 126   /**
 127    * Next modifier.
 128    */
 129   struct GNUNET_PSYC_Modifier *next;
 130
 131   /**
 132    * Previous modifier.
 133    */
 134   struct GNUNET_PSYC_Modifier *prev;
 135 };
 136
 137
 138 /**
 139  * Environment for a message.
 140  *
 141  * Contains modifiers.
 142  */
 143 struct GNUNET_PSYC_Environment;
 144
 145
 146 /**
 147  * Create an environment.
 148  *
 149  * @return A newly allocated environment.
 150  */
 151 struct GNUNET_PSYC_Environment *
 152 GNUNET_PSYC_env_create ();
 153
 154
 155 /**
 156  * Add a modifier to the environment.
 157  *
 158  * @param env The environment.
 159  * @param oper Operation to perform.
 160  * @param name Name of the variable.
 161  * @param value Value of the variable.
 162  * @param value_size Size of @a value.
 163  */
 164 void
 165 GNUNET_PSYC_env_add (struct GNUNET_PSYC_Environment *env,
 166                             enum GNUNET_PSYC_Operator oper, const char *name,
 167                             const void *value, size_t value_size);
 168
 169
 170 /**
 171  * Get the first modifier of the environment.
 172  */
 173 struct GNUNET_PSYC_Modifier *
 174 GNUNET_PSYC_env_head (const struct GNUNET_PSYC_Environment *env);
 175
 176
 177
 178 /**
 179  * Get the last modifier of the environment.
 180  */
 181 struct GNUNET_PSYC_Modifier *
 182 GNUNET_PSYC_env_tail (const struct GNUNET_PSYC_Environment *env);
 183
 184
 185 /**
 186  * Remove a modifier from the environment.
 187  */
 188 void
 189 GNUNET_PSYC_env_remove (struct GNUNET_PSYC_Environment *env,
 190                                struct GNUNET_PSYC_Modifier *mod);
 191
 192
 193 /**
 194  * Remove a modifier at the beginning of the environment.
 195  */
 196 int
 197 GNUNET_PSYC_env_shift (struct GNUNET_PSYC_Environment *env,
 198                               enum GNUNET_PSYC_Operator *oper, const char **name,
 199                               const void **value, size_t *value_size);
 200
 201
 202 /**
 203  * Iterator for modifiers in the environment.
 204  *
 205  * @param cls Closure.
 206  * @param mod Modifier.
 207  *
 208  * @return #GNUNET_YES to continue iterating,
 209  *         #GNUNET_NO to stop.
 210  */
 211 typedef int
 212 (*GNUNET_PSYC_Iterator) (void *cls, enum GNUNET_PSYC_Operator oper,
 213                         const char *name, const char *value,
 214                         uint32_t value_size);
 215
 216
 217 /**
 218  * Iterate through all modifiers in the environment.
 219  *
 220  * @param env The environment.
 221  * @param it Iterator.
 222  * @param it_cls Closure for iterator.
 223  */
 224 void
 225 GNUNET_PSYC_env_iterate (const struct GNUNET_PSYC_Environment *env,
 226                                 GNUNET_PSYC_Iterator it, void *it_cls);
 227
 228
 229 /**
 230  * Get the number of modifiers in the environment.
 231  *
 232  * @param env The environment.
 233  *
 234  * @return Number of modifiers.
 235  */
 236 size_t
 237 GNUNET_PSYC_env_get_count (const struct GNUNET_PSYC_Environment *env);
 238
 239
 240 /**
 241  * Destroy an environment.
 242  *
 243  * @param env The environment to destroy.
 244  */
 245 void
 246 GNUNET_PSYC_env_destroy (struct GNUNET_PSYC_Environment *env);
 247
 248
 249 /**
 250  * Get the type of variable.
 251  *
 252  * @param name Name of the variable.
 253  *
 254  * @return Variable type.
 255  */
 256 enum GNUNET_PSYC_Type
 257 GNUNET_PSYC_var_get_type (char *name);
 258
 259
 260 /**
 261  * Perform an operation on a variable.
 262  *
 263  * @param name Name of variable.
 264  * @param current_value Current value of variable.
 265  * @param current_value_size Size of @a current_value.
 266  * @param oper Operator.
 267  * @param args Arguments for the operation.
 268  * @param args_size Size of @a args.
 269  * @param return_value Return value.
 270  * @param return_value_size Size of @a return_value.
 271  *
 272  * @return #GNUNET_OK on success, else #GNUNET_SYSERR
 273  */
 274 int
 275 GNUNET_PSYC_operation (char *name, void *current_value, size_t current_value_size,
 276                       enum GNUNET_PSYC_Operator oper, void *args, size_t args_size,
 277                       void **return_value, size_t *return_value_size);
 278
 279
 280 /**
 281  * Get the variable's value as an integer.
 282  *
 283  * @param size Size of value.
 284  * @param value Raw value of variable.
 285  * @param[out] number Value converted to a 64-bit integer.
 286  *
 287  * @return #GNUNET_OK on success, #GNUNET_SYSERR if an error occurred (e.g. the value is invalid).
 288  */
 289 int
 290 GNUNET_PSYC_value_to_number (size_t size, const void *value, int64_t *number);
 291
 292
 293 /**
 294  * Get the variable's value as a dictionary.
 295  *
 296  * @param size Size of value.
 297  * @param value Raw value of variable.
 298  * @param[out] dict A newly created hashmap holding the elements of the dictionary.
 299  *
 300  * @return #GNUNET_OK on success, #GNUNET_SYSERR if an error occurred (e.g. the value is invalid).
 301  */
 302 int
 303 GNUNET_PSYC_value_to_dict (size_t size, const void *value, struct GNUNET_CONTAINER_MultiHashMap **dict);
 304
 305
 306 /**
 307  * Create a PSYC variable value from an integer.
 308  *
 309  * @param number The number to convert.
 310  * @param[out] value_size Size of returned value.
 311  *
 312  * @return A newly allocated value or NULL on error.
 313  */
 314 void *
 315 GNUNET_PSYC_value_from_number (int64_t number, size_t *value_size);
 316
 317
 318 /**
 319  * Create a PSYC variable value from a dictionary.
 320  *
 321  * @param dict The dict to convert.
 322  * @param[out] value_size Size of returned value.
 323  *
 324  * @return A newly allocated value or NULL on error.
 325  */
 326 void *
 327 GNUNET_PSYC_value_from_dict (struct GNUNET_CONTAINER_MultiHashMap *dict, size_t *value_size);
 328
 329
 330 #if 0                           /* keep Emacsens' auto-indent happy */
 331 {
 332 #endif
 333 #ifdef __cplusplus
 334 }
 335 #endif
 336
 337 /* ifndef GNUNET_PSYC_ENV_H */
 338 #endif
 339
 340 /** @} */  /* end of group */