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