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