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