src/include/gnunet_psyc_slicer.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
  16 /**
  17  * @author Gabor X Toth
  18  * @author Christian Grothoff
  19  *
  20  * @file
  21  * PSYC Slicer library
  22  *
  23  * @defgroup psyc-util-slicer  PSYC Utilities library: Slicer
  24  * Try-and-slice processing of PSYC method names and environment.
  25  * @{
  26  */
  27
  28 #ifndef GNUNET_PSYC_SLICER_H
  29 #define GNUNET_PSYC_SLICER_H
  30
  31
  32 #ifdef __cplusplus
  33 extern "C"
  34 {
  35 #if 0                           /* keep Emacsens' auto-indent happy */
  36 }
  37 #endif
  38 #endif
  39
  40 #include "gnunet_util_lib.h"
  41
  42
  43 /**
  44  * Handle to an implementation of try-and-slice.
  45  */
  46 struct GNUNET_PSYC_Slicer;
  47
  48
  49 /**
  50  * Function called upon receiving a message indicating a call to a @e method.
  51  *
  52  * This function is called one or more times for each message until all data
  53  * fragments arrive from the network.
  54  *
  55  * @param cls
  56  *        Closure.
  57  * @param msg
  58  *        Message part, as it arrived from the network.
  59  * @param message_id
  60  *        Message counter, monotonically increasing from 1.
  61  * @param flags
  62  *        OR'ed GNUNET_PSYC_MessageFlags
  63  * @param fragment_offset
  64  *        Multicast message fragment offset.
  65  * @param tmit_flags
  66  *        OR'ed GNUNET_PSYC_MasterTransmitFlags
  67  * @param nym
  68  *        The sender of the message.
  69  *        Can be NULL if the message is not connected to a pseudonym.
  70  * @param method_name
  71  *        Original method name from PSYC.
  72  *        May be more specific than the registered method name due to
  73  *        try-and-slice matching.
  74  */
  75 typedef void
  76 (*GNUNET_PSYC_MethodCallback) (void *cls,
  77                                const struct GNUNET_PSYC_MessageHeader *msg,
  78                                const struct GNUNET_PSYC_MessageMethod *meth,
  79                                uint64_t message_id,
  80                                const char *method_name);
  81
  82
  83 /**
  84  * Function called upon receiving a modifier of a message.
  85  *
  86  * @param cls
  87  *        Closure.
  88  * @param message_id
  89  *        Message ID this data fragment belongs to.
  90  * @param flags
  91  *        OR'ed GNUNET_PSYC_MessageFlags
  92  * @param fragment_offset
  93  *        Multicast message fragment offset.
  94  * @param msg
  95  *        Message part, as it arrived from the network.
  96  * @param oper
  97  *        Operation to perform.
  98  *        0 in case of a modifier continuation.
  99  * @param name
 100  *        Name of the modifier.
 101  *        NULL in case of a modifier continuation.
 102  * @param value
 103  *        Value of the modifier.
 104  * @param value_size
 105  *        Size of @value.
 106  */
 107 typedef void
 108 (*GNUNET_PSYC_ModifierCallback) (void *cls,
 109                                  const struct GNUNET_PSYC_MessageHeader *msg,
 110                                  const struct GNUNET_MessageHeader *pmsg,
 111                                  uint64_t message_id,
 112                                  enum GNUNET_PSYC_Operator oper,
 113                                  const char *name,
 114                                  const void *value,
 115                                  uint16_t value_size,
 116                                  uint16_t full_value_size);
 117
 118
 119 /**
 120  * Function called upon receiving a data fragment of a message.
 121  *
 122  * @param cls
 123  *        Closure.
 124  * @param msg
 125  *        Message part, as it arrived from the network.
 126  * @param message_id
 127  *        Message ID this data fragment belongs to.
 128  * @param flags
 129  *        OR'ed GNUNET_PSYC_MessageFlags
 130  * @param fragment_offset
 131  *        Multicast message fragment offset.
 132  * @param data
 133  *        Data stream given to the method.
 134  * @param data_size
 135  *        Number of bytes in @a data.
 136  * @param end
 137  *        End of message?
 138  *        #GNUNET_NO     if there are further fragments,
 139  *        #GNUNET_YES    if this is the last fragment,
 140  *        #GNUNET_SYSERR indicates the message was cancelled by the sender.
 141  */
 142 typedef void
 143 (*GNUNET_PSYC_DataCallback) (void *cls,
 144                              const struct GNUNET_PSYC_MessageHeader *msg,
 145                              const struct GNUNET_MessageHeader *pmsg,
 146                              uint64_t message_id,
 147                              const void *data,
 148                              uint16_t data_size);
 149
 150
 151 /**
 152  * End of message.
 153  *
 154  * @param cls
 155  *        Closure.
 156  * @param msg
 157  *        Message part, as it arrived from the network.
 158  * @param message_id
 159  *        Message ID this data fragment belongs to.
 160  * @param flags
 161  *        OR'ed GNUNET_PSYC_MessageFlags
 162  * @param fragment_offset
 163  *        Multicast message fragment offset.
 164  * @param cancelled
 165  *        #GNUNET_YES if the message was cancelled,
 166  *        #GNUNET_NO  if the message is complete.
 167  */
 168 typedef void
 169 (*GNUNET_PSYC_EndOfMessageCallback) (void *cls,
 170                                      const struct GNUNET_PSYC_MessageHeader *msg,
 171                                      const struct GNUNET_MessageHeader *pmsg,
 172                                      uint64_t message_id,
 173                                      uint8_t is_cancelled);
 174
 175
 176 /**
 177  * Create a try-and-slice instance.
 178  *
 179  * A slicer processes incoming messages and notifies callbacks about matching
 180  * methods or modifiers encountered.
 181  *
 182  * @return A new try-and-slice construct.
 183  */
 184 struct GNUNET_PSYC_Slicer *
 185 GNUNET_PSYC_slicer_create (void);
 186
 187
 188 /**
 189  * Add a method to the try-and-slice instance.
 190  *
 191  * The callbacks are called for messages with a matching @a method_name prefix.
 192  *
 193  * @param slicer
 194  *        The try-and-slice instance to extend.
 195  * @param method_name
 196  *        Name of the given method, use empty string to match all.
 197  * @param method_cb
 198  *        Method handler invoked upon a matching message.
 199  * @param modifier_cb
 200  *        Modifier handler, invoked after @a method_cb
 201  *        for each modifier in the message.
 202  * @param data_cb
 203  *        Data handler, invoked after @a modifier_cb for each data fragment.
 204  * @param eom_cb
 205  *        Invoked upon reaching the end of a matching message.
 206  * @param cls
 207  *        Closure for the callbacks.
 208  */
 209 void
 210 GNUNET_PSYC_slicer_method_add (struct GNUNET_PSYC_Slicer *slicer,
 211                                const char *method_name,
 212                                GNUNET_PSYC_MessageCallback msg_cb,
 213                                GNUNET_PSYC_MethodCallback method_cb,
 214                                GNUNET_PSYC_ModifierCallback modifier_cb,
 215                                GNUNET_PSYC_DataCallback data_cb,
 216                                GNUNET_PSYC_EndOfMessageCallback eom_cb,
 217                                void *cls);
 218
 219 /**
 220  * Remove a registered method from the try-and-slice instance.
 221  *
 222  * Removes one matching handler registered with the given
 223  * @a method_name and callbacks.
 224  *
 225  * @param slicer
 226  *        The try-and-slice instance.
 227  * @param method_name
 228  *        Name of the method to remove.
 229  * @param method_cb
 230  *        Only remove matching method handler, or NULL.
 231  * @param modifier_cb
 232  *        Only remove matching modifier handler, or NULL.
 233  * @param data_cb
 234  *        Only remove matching data handler, or NULL.
 235  * @param eom_cb
 236  *        Only remove matching End of Message handler, or NULL.
 237  *
 238  * @return #GNUNET_OK if a method handler was removed,
 239  *         #GNUNET_NO if no handler matched the given method name and callbacks.
 240  */
 241 int
 242 GNUNET_PSYC_slicer_method_remove (struct GNUNET_PSYC_Slicer *slicer,
 243                                   const char *method_name,
 244                                   GNUNET_PSYC_MessageCallback msg_cb,
 245                                   GNUNET_PSYC_MethodCallback method_cb,
 246                                   GNUNET_PSYC_ModifierCallback modifier_cb,
 247                                   GNUNET_PSYC_DataCallback data_cb,
 248                                   GNUNET_PSYC_EndOfMessageCallback eom_cb);
 249
 250
 251 /**
 252  * Watch a place for changed objects.
 253  *
 254  * @param slicer
 255  *        The try-and-slice instance.
 256  * @param object_filter
 257  *        Object prefix to match.
 258  * @param modifier_cb
 259  *        Function to call when encountering a state modifier.
 260  * @param cls
 261  *        Closure for callback.
 262  */
 263 void
 264 GNUNET_PSYC_slicer_modifier_add (struct GNUNET_PSYC_Slicer *slicer,
 265                                  const char *object_filter,
 266                                  GNUNET_PSYC_ModifierCallback modifier_cb,
 267                                  void *cls);
 268
 269
 270 /**
 271  * Remove a registered modifier from the try-and-slice instance.
 272  *
 273  * Removes one matching handler registered with the given
 274  * @a object_filter and callback.
 275  *
 276  * @param slicer
 277  *        The try-and-slice instance.
 278  * @param object_filter
 279  *        Object prefix to match.
 280  * @param modifier_cb
 281  *        Function to call when encountering a state modifier changes.
 282  */
 283 int
 284 GNUNET_PSYC_slicer_modifier_remove (struct GNUNET_PSYC_Slicer *slicer,
 285                                     const char *object_filter,
 286                                     GNUNET_PSYC_ModifierCallback modifier_cb);
 287
 288
 289 /**
 290  * Process an incoming message and call matching handlers.
 291  *
 292  * @param slicer
 293  *        The slicer to use.
 294  * @param msg
 295  *        The message as it arrived from the network.
 296  */
 297 void
 298 GNUNET_PSYC_slicer_message (struct GNUNET_PSYC_Slicer *slicer,
 299                             const struct GNUNET_PSYC_MessageHeader *msg);
 300
 301
 302 /**
 303  * Process an incoming message part and call matching handlers.
 304  *
 305  * @param slicer
 306  *        The slicer to use.
 307  * @param message_id
 308  *        ID of the message.
 309  * @param flags
 310  *        Flags for the message.
 311  *        @see enum GNUNET_PSYC_MessageFlags
 312  * @param fragment offset
 313  *        Fragment offset of the message.
 314  * @param msg
 315  *        The message part as it arrived from the network.
 316  */
 317 void
 318 GNUNET_PSYC_slicer_message_part (struct GNUNET_PSYC_Slicer *slicer,
 319                                  const struct GNUNET_PSYC_MessageHeader *msg,
 320                                  const struct GNUNET_MessageHeader *pmsg);
 321
 322
 323 /**
 324  * Remove all registered method handlers.
 325  *
 326  * @param slicer
 327  *        Slicer to clear.
 328  */
 329 void
 330 GNUNET_PSYC_slicer_method_clear (struct GNUNET_PSYC_Slicer *slicer);
 331
 332
 333 /**
 334  * Remove all registered modifier handlers.
 335  *
 336  * @param slicer
 337  *        Slicer to clear.
 338  */
 339 void
 340 GNUNET_PSYC_slicer_modifier_clear (struct GNUNET_PSYC_Slicer *slicer);
 341
 342
 343 /**
 344  * Remove all registered method & modifier handlers.
 345  *
 346  * @param slicer
 347  *        Slicer to clear.
 348  */
 349 void
 350 GNUNET_PSYC_slicer_clear (struct GNUNET_PSYC_Slicer *slicer);
 351
 352
 353 /**
 354  * Destroy a given try-and-slice instance.
 355  *
 356  * @param slicer
 357  *        Slicer to destroy
 358  */
 359 void
 360 GNUNET_PSYC_slicer_destroy (struct GNUNET_PSYC_Slicer *slicer);
 361
 362
 363 #if 0                           /* keep Emacsens' auto-indent happy */
 364 {
 365 #endif
 366 #ifdef __cplusplus
 367 }
 368 #endif
 369
 370 /* ifndef GNUNET_PSYC_SLICER_H */
 371 #endif
 372
 373 /** @} */  /* end of group */