src/include/gnunet_psyc_slicer.h

   1 /*
   2      This file is part of GNUnet.
   3      Copyright (C) 2013 Christian Grothoff (and other contributing authors)
   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 nym
  67  *        The sender of the message.
  68  *        Can be NULL if the message is not connected to a pseudonym.
  69  * @param flags
  70  *        OR'ed GNUNET_PSYC_MessageFlags
  71  * @param method_name
  72  *        Original method name from PSYC.
  73  *        May be more specific than the registered method name due to
  74  *        try-and-slice matching.
  75  */
  76 typedef void
  77 (*GNUNET_PSYC_MethodCallback) (void *cls,
  78                                const struct GNUNET_PSYC_MessageMethod *msg,
  79                                uint64_t message_id,
  80                                uint32_t flags,
  81                                const struct GNUNET_CRYPTO_EcdsaPublicKey *nym_pub_key,
  82                                const char *method_name);
  83
  84
  85 /**
  86  * Function called upon receiving a modifier of a message.
  87  *
  88  * @param cls
  89  *        Closure.
  90  * @param message_id
  91  *        Message ID this data fragment belongs to.
  92  * @param msg
  93  *        Message part, as it arrived from the network.
  94  * @param oper
  95  *        Operation to perform.
  96  *        0 in case of a modifier continuation.
  97  * @param name
  98  *        Name of the modifier.
  99  *        NULL in case of a modifier continuation.
 100  * @param value
 101  *        Value of the modifier.
 102  * @param value_size
 103  *        Size of @value.
 104  */
 105 typedef void
 106 (*GNUNET_PSYC_ModifierCallback) (void *cls,
 107                                  const struct GNUNET_MessageHeader *msg,
 108                                  uint64_t message_id,
 109                                  enum GNUNET_PSYC_Operator oper,
 110                                  const char *name,
 111                                  const void *value,
 112                                  uint16_t value_size,
 113                                  uint16_t full_value_size);
 114
 115
 116 /**
 117  * Function called upon receiving a data fragment of a message.
 118  *
 119  * @param cls
 120  *        Closure.
 121  * @param message_id
 122  *        Message ID this data fragment belongs to.
 123  * @param msg
 124  *        Message part, as it arrived from the network.
 125  * @param data_offset
 126  *        Byte offset of @a data in the overall data of the method.
 127  * @param data_size
 128  *        Number of bytes in @a data.
 129  * @param data
 130  *        Data stream given to the method.
 131  * @param end
 132  *        End of message?
 133  *        #GNUNET_NO     if there are further fragments,
 134  *        #GNUNET_YES    if this is the last fragment,
 135  *        #GNUNET_SYSERR indicates the message was cancelled by the sender.
 136  */
 137 typedef void
 138 (*GNUNET_PSYC_DataCallback) (void *cls,
 139                              const struct GNUNET_MessageHeader *msg,
 140                              uint64_t message_id,
 141                              uint64_t data_offset,
 142                              const void *data,
 143                              uint16_t data_size);
 144
 145
 146 /**
 147  * End of message.
 148  *
 149  * @param cls
 150  *        Closure.
 151  * @param msg
 152  *        Message part, as it arrived from the network.
 153  * @param message_id
 154  *        Message ID this data fragment belongs to.
 155  * @param cancelled
 156  *        #GNUNET_YES if the message was cancelled,
 157  *        #GNUNET_NO  if the message is complete.
 158  */
 159 typedef void
 160 (*GNUNET_PSYC_EndOfMessageCallback) (void *cls,
 161                                      const struct GNUNET_MessageHeader *msg,
 162                                      uint64_t message_id,
 163                                      uint8_t cancelled);
 164
 165
 166 /**
 167  * Create a try-and-slice instance.
 168  *
 169  * A slicer processes incoming messages and notifies callbacks about matching
 170  * methods or modifiers encountered.
 171  *
 172  * @return A new try-and-slice construct.
 173  */
 174 struct GNUNET_PSYC_Slicer *
 175 GNUNET_PSYC_slicer_create (void);
 176
 177
 178 /**
 179  * Add a method to the try-and-slice instance.
 180  *
 181  * The callbacks are called for messages with a matching @a method_name prefix.
 182  *
 183  * @param slicer
 184  *        The try-and-slice instance to extend.
 185  * @param method_name
 186  *        Name of the given method, use empty string to match all.
 187  * @param method_cb
 188  *        Method handler invoked upon a matching message.
 189  * @param modifier_cb
 190  *        Modifier handler, invoked after @a method_cb
 191  *        for each modifier in the message.
 192  * @param data_cb
 193  *        Data handler, invoked after @a modifier_cb for each data fragment.
 194  * @param eom_cb
 195  *        Invoked upon reaching the end of a matching message.
 196  * @param cls
 197  *        Closure for the callbacks.
 198  */
 199 void
 200 GNUNET_PSYC_slicer_method_add (struct GNUNET_PSYC_Slicer *slicer,
 201                                const char *method_name,
 202                                GNUNET_PSYC_MethodCallback method_cb,
 203                                GNUNET_PSYC_ModifierCallback modifier_cb,
 204                                GNUNET_PSYC_DataCallback data_cb,
 205                                GNUNET_PSYC_EndOfMessageCallback eom_cb,
 206                                void *cls);
 207
 208 /**
 209  * Remove a registered method from the try-and-slice instance.
 210  *
 211  * Removes one matching handler registered with the given
 212  * @a method_name and callbacks.
 213  *
 214  * @param slicer
 215  *        The try-and-slice instance.
 216  * @param method_name
 217  *        Name of the method to remove.
 218  * @param method_cb
 219  *        Method handler.
 220  * @param modifier_cb
 221  *        Modifier handler.
 222  * @param data_cb
 223  *        Data handler.
 224  * @param eom_cb
 225  *        End of message handler.
 226  *
 227  * @return #GNUNET_OK if a method handler was removed,
 228  *         #GNUNET_NO if no handler matched the given method name and callbacks.
 229  */
 230 int
 231 GNUNET_PSYC_slicer_method_remove (struct GNUNET_PSYC_Slicer *slicer,
 232                                   const char *method_name,
 233                                   GNUNET_PSYC_MethodCallback method_cb,
 234                                   GNUNET_PSYC_ModifierCallback modifier_cb,
 235                                   GNUNET_PSYC_DataCallback data_cb,
 236                                   GNUNET_PSYC_EndOfMessageCallback eom_cb);
 237
 238
 239 /**
 240  * Watch a place for changed objects.
 241  *
 242  * @param slicer
 243  *        The try-and-slice instance.
 244  * @param object_filter
 245  *        Object prefix to match.
 246  * @param modifier_cb
 247  *        Function to call when encountering a state modifier.
 248  * @param cls
 249  *        Closure for callback.
 250  */
 251 void
 252 GNUNET_PSYC_slicer_modifier_add (struct GNUNET_PSYC_Slicer *slicer,
 253                                    const char *object_filter,
 254                                    GNUNET_PSYC_ModifierCallback modifier_cb,
 255                                    void *cls);
 256
 257
 258 /**
 259  * Remove a registered modifier from the try-and-slice instance.
 260  *
 261  * Removes one matching handler registered with the given
 262  * @a object_filter and callback.
 263  *
 264  * @param slicer
 265  *        The try-and-slice instance.
 266  * @param object_filter
 267  *        Object prefix to match.
 268  * @param modifier_cb
 269  *        Function to call when encountering a state modifier changes.
 270  */
 271 int
 272 GNUNET_PSYC_slicer_modifier_remove (struct GNUNET_PSYC_Slicer *slicer,
 273                                       const char *object_filter,
 274                                       GNUNET_PSYC_ModifierCallback modifier_cb);
 275
 276
 277 /**
 278  * Process an incoming message part and call matching handlers.
 279  *
 280  * @param cls
 281  *        Closure.
 282  * @param message_id
 283  *        ID of the message.
 284  * @param flags
 285  *        Flags for the message.
 286  *        @see enum GNUNET_PSYC_MessageFlags
 287  * @param msg
 288  *        The message part. as it arrived from the network.
 289  */
 290 void
 291 GNUNET_PSYC_slicer_message (void *cls,
 292                             const struct GNUNET_CRYPTO_EcdsaPublicKey *slave_pub_key,
 293                             uint64_t message_id,
 294                             uint32_t flags,
 295                             uint64_t fragment_offset,
 296                             const struct GNUNET_MessageHeader *msg);
 297
 298
 299 /**
 300  * Destroy a given try-and-slice instance.
 301  *
 302  * @param slicer
 303  *        Slicer to destroy
 304  */
 305 void
 306 GNUNET_PSYC_slicer_destroy (struct GNUNET_PSYC_Slicer *slicer);
 307
 308
 309 #if 0                           /* keep Emacsens' auto-indent happy */
 310 {
 311 #endif
 312 #ifdef __cplusplus
 313 }
 314 #endif
 315
 316 /* ifndef GNUNET_PSYC_SLICER_H */
 317 #endif
 318
 319 /** @} */  /* end of group */