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