src/include/gnunet_regex_service.h

   1 /*
   2      This file is part of GNUnet
   3      Copyright (C) 2012, 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 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  * @author Maximilian Szengel
  17  * @author Christian Grothoff
  18  *
  19  * @file
  20  * API to access regex service to advertise capabilities via regex and discover
  21  * respective peers using matching strings
  22  *
  23  * @defgroup regex  RegEx service
  24  * Advertise capabilities via RegEx and discover
  25  * respective peers using matching strings.
  26  *
  27  * @see [Documentation](https://gnunet.org/regex)
  28  *
  29  * @{
  30  */
  31 #ifndef GNUNET_REGEX_SERVICE_H
  32 #define GNUNET_REGEX_SERVICE_H
  33
  34 #include "gnunet_util_lib.h"
  35
  36 #ifdef __cplusplus
  37 extern "C"
  38 {
  39 #if 0                           /* keep Emacsens' auto-indent happy */
  40 }
  41 #endif
  42 #endif
  43
  44
  45 /**
  46  * Constant for how many bytes the initial string regex should have.
  47  */
  48 #define GNUNET_REGEX_INITIAL_BYTES 24
  49
  50
  51 /**
  52  * Handle to store cached data about a regex announce.
  53  */
  54 struct GNUNET_REGEX_Announcement;
  55
  56 /**
  57  * Handle to store data about a regex search.
  58  */
  59 struct GNUNET_REGEX_Search;
  60
  61
  62 /**
  63  * Announce this peer under the given regular expression.  Does
  64  * not free resources, must call #GNUNET_REGEX_announce_cancel for
  65  * that.
  66  *
  67  * @param cfg configuration to use
  68  * @param regex Regular expression to announce.
  69  * @param refresh_delay after what delay should the announcement be repeated?
  70  * @param compression How many characters per edge can we squeeze?
  71  * @return Handle to reuse o free cached resources.
  72  *         Must be freed by calling #GNUNET_REGEX_announce_cancel.
  73  */
  74 struct GNUNET_REGEX_Announcement *
  75 GNUNET_REGEX_announce (const struct GNUNET_CONFIGURATION_Handle *cfg,
  76                        const char *regex,
  77                        struct GNUNET_TIME_Relative refresh_delay,
  78                        uint16_t compression);
  79
  80
  81 /**
  82  * Stop announcing the regex specified by the given handle.
  83  *
  84  * @param a handle returned by a previous #GNUNET_REGEX_announce call.
  85  */
  86 void
  87 GNUNET_REGEX_announce_cancel (struct GNUNET_REGEX_Announcement *a);
  88
  89
  90 /**
  91  * Search callback function, invoked for every result that was found.
  92  *
  93  * @param cls Closure provided in #GNUNET_REGEX_search.
  94  * @param id Peer providing a regex that matches the string.
  95  * @param get_path Path of the get request.
  96  * @param get_path_length Lenght of @a get_path.
  97  * @param put_path Path of the put request.
  98  * @param put_path_length Length of the @a put_path.
  99  */
 100 typedef void
 101 (*GNUNET_REGEX_Found)(void *cls,
 102                       const struct GNUNET_PeerIdentity *id,
 103                       const struct GNUNET_PeerIdentity *get_path,
 104                       unsigned int get_path_length,
 105                       const struct GNUNET_PeerIdentity *put_path,
 106                       unsigned int put_path_length);
 107
 108
 109 /**
 110  * Search for a peer offering a regex matching certain string in the DHT.
 111  * The search runs until #GNUNET_REGEX_search_cancel is called, even if results
 112  * are returned.
 113  *
 114  * @param cfg configuration to use
 115  * @param string String to match against the regexes in the DHT.
 116  * @param callback Callback for found peers.
 117  * @param callback_cls Closure for @c callback.
 118  * @return Handle to stop search and free resources.
 119  *         Must be freed by calling #GNUNET_REGEX_search_cancel.
 120  */
 121 struct GNUNET_REGEX_Search *
 122 GNUNET_REGEX_search (const struct GNUNET_CONFIGURATION_Handle *cfg,
 123                      const char *string,
 124                      GNUNET_REGEX_Found callback,
 125                      void *callback_cls);
 126
 127
 128 /**
 129  * Stop search and free all data used by a #GNUNET_REGEX_search call.
 130  *
 131  * @param s Handle returned by a previous #GNUNET_REGEX_search call.
 132  */
 133 void
 134 GNUNET_REGEX_search_cancel (struct GNUNET_REGEX_Search *s);
 135
 136
 137 #if 0                           /* keep Emacsens' auto-indent happy */
 138 {
 139 #endif
 140 #ifdef __cplusplus
 141 }
 142 #endif
 143
 144 #endif
 145
 146 /** @} */  /* end of group */