src/include/gnunet_transport_hello_service.h

   1 /*
   2      This file is part of GNUnet.
   3      Copyright (C) 2009-2016 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 /**
  20  * @author Christian Grothoff
  21  *
  22  * @file
  23  * obtain information about our current address
  24  *
  25  * @defgroup transport  Transport service
  26  * address information
  27  *
  28  * @see [Documentation](https://gnunet.org/transport-service)
  29  *
  30  * @{
  31  */
  32 #ifndef GNUNET_TRANSPORT_HELLO_SERVICE_H
  33 #define GNUNET_TRANSPORT_HELLO_SERVICE_H
  34
  35 #ifdef __cplusplus
  36 extern "C"
  37 {
  38 #if 0                           /* keep Emacsens' auto-indent happy */
  39 }
  40 #endif
  41 #endif
  42
  43 #include "gnunet_util_lib.h"
  44 #include "gnunet_ats_service.h"
  45
  46 /**
  47  * Version number of the transport API.
  48  */
  49 #define GNUNET_TRANSPORT_HELLO_VERSION 0x00000000
  50
  51
  52 /**
  53  * Some addresses contain sensitive information or are
  54  * not suitable for global distribution.  We use address
  55  * classes to filter addresses by which domain they make
  56  * sense to be used in.  These are used in a bitmask.
  57  */
  58 enum GNUNET_TRANSPORT_AddressClass
  59 {
  60
  61   /**
  62    * No address.
  63    */
  64   GNUNET_TRANSPORT_AC_NONE = 0,
  65
  66   /**
  67    * Addresses that fall into no other category
  68    * (i.e. incoming which we cannot use elsewhere).
  69    */
  70   GNUNET_TRANSPORT_AC_OTHER = 1,
  71
  72   /**
  73    * Addresses that are global and are insensitive
  74    * (i.e. IPv4).
  75    */
  76   GNUNET_TRANSPORT_AC_GLOBAL = 2,
  77
  78   /**
  79    * Addresses that are global and are sensitive
  80    * (i.e. IPv6 with our MAC).
  81    */
  82   GNUNET_TRANSPORT_AC_GLOBAL_PRIVATE = 4,
  83
  84   /**
  85    * Addresses useful in the local wired network,
  86    * i.e. a MAC.  Sensitive, but obvious to people nearby.
  87    * Useful for broadcasts.
  88    */
  89   GNUNET_TRANSPORT_AC_LAN = 8,
  90
  91   /**
  92    * Addresses useful in the local wireless network,
  93    * i.e. a MAC.  Sensitive, but obvious to people nearby.
  94    * Useful for broadcasts.
  95    */
  96   GNUNET_TRANSPORT_AC_WLAN = 16,
  97
  98   /**
  99    * Addresses useful in the local bluetooth network.  Sensitive, but
 100    * obvious to people nearby.  Useful for broadcasts.
 101    */
 102   GNUNET_TRANSPORT_AC_BT = 32,
 103
 104   /**
 105    * Bitmask for "any" address.
 106    */
 107   GNUNET_TRANSPORT_AC_ANY = 65535
 108
 109 };
 110
 111
 112 /**
 113  * Function called whenever there is an update to the
 114  * HELLO of this peer.
 115  *
 116  * @param cls closure
 117  * @param hello our updated HELLO
 118  */
 119 typedef void
 120 (*GNUNET_TRANSPORT_HelloUpdateCallback) (void *cls,
 121                                          const struct GNUNET_MessageHeader *hello);
 122
 123
 124 /**
 125  * Handle to cancel a #GNUNET_TRANSPORT_hello_get() operation.
 126  */
 127 struct GNUNET_TRANSPORT_HelloGetHandle;
 128
 129
 130 /**
 131  * Obtain updates on changes to the HELLO message for this peer. The callback
 132  * given in this function is never called synchronously.
 133  *
 134  * @param cfg configuration to use
 135  * @param ac which network type should the addresses from the HELLO belong to?
 136  * @param rec function to call with the HELLO
 137  * @param rec_cls closure for @a rec
 138  * @return handle to cancel the operation
 139  */
 140 struct GNUNET_TRANSPORT_HelloGetHandle *
 141 GNUNET_TRANSPORT_hello_get (const struct GNUNET_CONFIGURATION_Handle *cfg,
 142                             enum GNUNET_TRANSPORT_AddressClass ac,
 143                             GNUNET_TRANSPORT_HelloUpdateCallback rec,
 144                             void *rec_cls);
 145
 146
 147 /**
 148  * Stop receiving updates about changes to our HELLO message.
 149  *
 150  * @param ghh handle to cancel
 151  */
 152 void
 153 GNUNET_TRANSPORT_hello_get_cancel (struct GNUNET_TRANSPORT_HelloGetHandle *ghh);
 154
 155
 156 /**
 157  * Function with addresses found in a HELLO.
 158  *
 159  * @param cls closure
 160  * @param peer identity of the peer
 161  * @param address the address (UTF-8, 0-terminated)
 162  * @param nt network type of the address
 163  * @param expiration when does this address expire?
 164  */
 165 typedef void
 166 (*GNUNET_TRANSPORT_AddressCallback) (void *cls,
 167                                      const struct GNUNET_PeerIdentity *peer,
 168                                      const char *address,
 169                                      enum GNUNET_NetworkType nt,
 170                                      struct GNUNET_TIME_Absolute expiration);
 171
 172
 173 /**
 174  * Parse a HELLO message that we have received into its
 175  * constituent addresses.
 176  *
 177  * @param hello message to parse
 178  * @param cb function to call on each address found
 179  * @param cb_cls closure for @a cb
 180  * @return #GNUNET_OK if hello was well-formed, #GNUNET_SYSERR if not
 181  */
 182 int
 183 GNUNET_TRANSPORT_hello_parse (const struct GNUNET_MessageHeader *hello,
 184                               GNUNET_TRANSPORT_AddressCallback cb,
 185                               void *cb_cls);
 186
 187
 188 #if 0                           /* keep Emacsens' auto-indent happy */
 189 {
 190 #endif
 191 #ifdef __cplusplus
 192 }
 193 #endif
 194
 195 /* ifndef GNUNET_TRANSPORT_HELLO_SERVICE_H */
 196 #endif
 197
 198 /** @} */  /* end of group */
 199
 200 /* end of gnunet_transport_hello_service.h */