src/include/gnunet_regex_service.h

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