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