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
   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 /**
  22  * @author Christian Grothoff
  23  *
  24  * @file
  25  * obtain information about our current address
  26  *
  27  * @defgroup transport  Transport service
  28  * address information
  29  *
  30  * @see [Documentation](https://gnunet.org/transport-service)
  31  *
  32  * @{
  33  */
  34 #ifndef GNUNET_TRANSPORT_HELLO_SERVICE_H
  35 #define GNUNET_TRANSPORT_HELLO_SERVICE_H
  36
  37 #ifdef __cplusplus
  38 extern "C"
  39 {
  40 #if 0                           /* keep Emacsens' auto-indent happy */
  41 }
  42 #endif
  43 #endif
  44
  45 #include "gnunet_util_lib.h"
  46 #include "gnunet_ats_service.h"
  47
  48 /**
  49  * Version number of the transport API.
  50  */
  51 #define GNUNET_TRANSPORT_HELLO_VERSION 0x00000000
  52
  53
  54 /**
  55  * Function called whenever there is an update to the
  56  * HELLO of this peer.
  57  *
  58  * @param cls closure
  59  * @param hello our updated HELLO
  60  */
  61 typedef void
  62 (*GNUNET_TRANSPORT_HelloUpdateCallback) (void *cls,
  63                                          const struct GNUNET_MessageHeader *hello);
  64
  65
  66 /**
  67  * Handle to cancel a #GNUNET_TRANSPORT_hello_get() operation.
  68  */
  69 struct GNUNET_TRANSPORT_GetHelloHandle;
  70
  71
  72 /**
  73  * Obtain updates on changes to the HELLO message for this peer. The callback
  74  * given in this function is never called synchronously.
  75  *
  76  * @param cfg configuration to use
  77  * @param nt which network type should the addresses from the HELLO belong to?
  78  * @param rec function to call with the HELLO
  79  * @param rec_cls closure for @a rec
  80  * @return handle to cancel the operation
  81  */
  82 struct GNUNET_TRANSPORT_GetHelloHandle *
  83 GNUNET_TRANSPORT_hello_get (struct GNUNET_CONFIGURATION_Handle *cfg,
  84                             enum GNUNET_ATS_Network_Type nt,
  85                             GNUNET_TRANSPORT_HelloUpdateCallback rec,
  86                             void *rec_cls);
  87
  88
  89 /**
  90  * Stop receiving updates about changes to our HELLO message.
  91  *
  92  * @param ghh handle to cancel
  93  */
  94 void
  95 GNUNET_TRANSPORT_hello_get_cancel (struct GNUNET_TRANSPORT_GetHelloHandle *ghh);
  96
  97
  98 /**
  99  * Function with addresses found in a HELLO.
 100  *
 101  * @param cls closure
 102  * @param peer identity of the peer
 103  * @param address the address (UTF-8, 0-terminated)
 104  * @param nt network type of the address
 105  * @param expiration when does this address expire?
 106  */
 107 typedef void
 108 (*GNUNET_TRANSPORT_AddressCallback) (void *cls,
 109                                      const struct GNUNET_PeerIdentity *peer,
 110                                      const char *address,
 111                                      enum GNUNET_ATS_Network_Type nt,
 112                                      struct GNUNET_TIME_Absolute expiration);
 113
 114
 115 /**
 116  * Parse a HELLO message that we have received into its
 117  * constituent addresses.
 118  *
 119  * @param hello message to parse
 120  * @param cb function to call on each address found
 121  * @param cb_cls closure for @a cb
 122  * @return #GNUNET_OK if hello was well-formed, #GNUNET_SYSERR if not
 123  */
 124 int
 125 GNUNET_TRANSPORT_hello_parse (const struct GNUNET_MessageHeader *hello,
 126                               GNUNET_TRANSPORT_AddressCallback cb,
 127                               void *cb_cls);
 128
 129
 130 #if 0                           /* keep Emacsens' auto-indent happy */
 131 {
 132 #endif
 133 #ifdef __cplusplus
 134 }
 135 #endif
 136
 137 /* ifndef GNUNET_TRANSPORT_HELLO_SERVICE_H */
 138 #endif
 139
 140 /** @} */  /* end of group */
 141
 142 /* end of gnunet_transport_hello_service.h */