src/include/gnunet_transport_communication_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 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
  16 /**
  17  * @author Christian Grothoff
  18  *
  19  * @file
  20  * API of the transport service towards the communicator processes.
  21  *
  22  * @defgroup transport TRANSPORT service
  23  * Low-level communication with other peers
  24  *
  25  * @see [Documentation](https://gnunet.org/transport-service)
  26  *
  27  * @{
  28  */
  29
  30 #ifndef GNUNET_TRANSPORT_COMMUNICATION_SERVICE_H
  31 #define GNUNET_TRANSPORT_COMMUNICATION_SERVICE_H
  32
  33 #ifdef __cplusplus
  34 extern "C"
  35 {
  36 #if 0                           /* keep Emacsens' auto-indent happy */
  37 }
  38 #endif
  39 #endif
  40
  41 #include "gnunet_util_lib.h"
  42
  43 /**
  44  * Version number of the transport communication API.
  45  */
  46 #define GNUNET_TRANSPORT_COMMUNICATION_VERSION 0x00000000
  47
  48
  49 /**
  50  * Function called by the transport service to initialize a
  51  * message queue given address information about another peer.
  52  *
  53  * @param cls closure
  54  * @param peer identity of the other peer
  55  * @param address where to send the message, human-readable
  56  *        communicator-specific format, 0-terminated, UTF-8
  57  * @return NULL if the provided address is invalid, otherwise an MQ to
  58  *         send messages to that peer
  59  */
  60 typedef struct GNUNET_MQ_Handle *
  61 (*GNUNET_TRANSPORT_CommunicatorMqInit) (void *cls,
  62                                         const struct GNUNET_PeerIdentity *peer,
  63                                         const void *address);
  64
  65
  66 /**
  67  * Opaque handle to the transport service for communicators.
  68  */
  69 struct GNUNET_TRANSPORT_CommunicatorHandle;
  70
  71
  72 /**
  73  * Connect to the transport service.
  74  *
  75  * @param cfg configuration to use
  76  * @param name name of the communicator that is connecting
  77  * @param mtu maximum message size supported by communicator, 0 if
  78  *            sending is not supported
  79  * @param mq_init function to call to initialize a message queue given
  80  *                the address of another peer, can be NULL if the
  81  *                communicator only supports receiving messages
  82  * @param mq_init_cls closure for @a mq_init
  83  * @return NULL on error
  84  */
  85 struct GNUNET_TRANSPORT_CommunicatorHandle *
  86 GNUNET_TRANSPORT_communicator_connect (const struct GNUNET_CONFIGURATION_Handle *cfg,
  87                                        const char *name,
  88                                        size_t mtu,
  89                                        GNUNET_TRANSPORT_CommunicatorMqInit mq_init,
  90                                        void *mq_init_cls);
  91
  92
  93 /**
  94  * Disconnect from the transport service.
  95  *
  96  * @param ch handle returned from connect
  97  */
  98 void
  99 GNUNET_TRANSPORT_communicator_disconnect (struct GNUNET_TRANSPORT_CommunicatorHandle *ch);
 100
 101
 102 /* ************************* Receiving *************************** */
 103
 104 /**
 105  * Function called to notify communicator that we have received
 106  * and processed the message.
 107  *
 108  * @param cls closure
 109  * @param success #GNUNET_SYSERR on failure (try to disconnect/reset connection)
 110  *                #GNUNET_OK on success
 111  */
 112 typedef void
 113 (*GNUNET_TRANSPORT_MessageCompletedCallback) (void *cls,
 114                                               int success);
 115
 116
 117 /**
 118  * Notify transport service that the communicator has received
 119  * a message.
 120  *
 121  * @param handle connection to transport service
 122  * @param sender presumed sender of the message (details to be checked
 123  *        by higher layers)
 124  * @param msg the message
 125  * @param cb function to call once handling the message is done, NULL if
 126  *         flow control is not supported by this communicator
 127  * @param cb_cls closure for @a cb
 128  * @return #GNUNET_OK if all is well, #GNUNET_NO if the message was
 129  *         immediately dropped due to memory limitations (communicator
 130  *         should try to apply back pressure),
 131  *         #GNUNET_SYSERR if the message is ill formed and communicator
 132  *         should try to reset stream
 133  */
 134 int
 135 GNUNET_TRANSPORT_communicator_receive (struct GNUNET_TRANSPORT_CommunicatorHandle *handle,
 136                                        const struct GNUNET_PeerIdentity *sender,
 137                                        const struct GNUNET_MessageHeader *msg,
 138                                        GNUNET_TRANSPORT_MessageCompletedCallback cb,
 139                                        void *cb_cls);
 140
 141
 142 /* ************************* Discovery *************************** */
 143
 144
 145 /**
 146  * Notify transport service that an MQ became available due to an
 147  * "inbound" connection or because the communicator discovered the
 148  * presence of another peer.
 149  *
 150  * @param handle connection to transport service
 151  * @param peer peer with which we can now communicate
 152  * @param address address in human-readable format, 0-terminated, UTF-8
 153  * @param nt which network type does the @a address belong to?
 154  * @param mq message queue of the @a peer
 155  */
 156 void
 157 GNUNET_TRANSPORT_communicator_mq_add (struct GNUNET_TRANSPORT_CommunicatorHandle *handle,
 158                                       const struct GNUNET_PeerIdentity *peer,
 159                                       const char *address,
 160                                       enum GNUNET_ATS_Network_Type nt,
 161                                       struct GNUNET_MQ_Handle *mq);
 162
 163
 164 /**
 165  * Notify transport service that an MQ became unavailable due to a
 166  * disconnect or timeout.
 167  *
 168  * @param handle connection to transport service
 169  * @param peer peer with which we can no longer communicate via the given mq
 170  * @param address address in human-readable format, 0-terminated, UTF-8
 171  * @param nt which network type does the @a address belong to?
 172  * @param mq message queue of the @a peer
 173  */
 174 void
 175 GNUNET_TRANSPORT_communicator_mq_remove (struct GNUNET_TRANSPORT_CommunicatorHandle *handle,
 176                                          const struct GNUNET_PeerIdentity *peer,
 177                                          const char *address,
 178                                          enum GNUNET_ATS_Network_Type nt,
 179                                          struct GNUNET_MQ_Handle *mq);
 180
 181
 182 /**
 183  * Notify transport service about an address that this communicator
 184  * provides for this peer.
 185  *
 186  * @param handle connection to transport service
 187  * @param address our address in human-readable format, 0-terminated, UTF-8
 188  * @param nt which network type does the address belong to?
 189  * @param expiration when does the communicator forsee this address expiring?
 190  */
 191 void
 192 GNUNET_TRANSPORT_communicator_address_add (struct GNUNET_TRANSPORT_CommunicatorHandle *handle,
 193                                            const char *address,
 194                                            enum GNUNET_ATS_Network_Type nt,
 195                                            struct GNUNET_TIME_Absolute expiration);
 196
 197
 198 /**
 199  * Notify transport service about an address that this communicator
 200  * no longer provides for this peer.
 201  *
 202  * @param handle connection to transport service
 203  * @param address our former address in human-readable format,
 204  *        0-terminated, in UTF-8
 205  */
 206 void
 207 GNUNET_TRANSPORT_communicator_address_remove (struct GNUNET_TRANSPORT_CommunicatorHandle *handle,
 208                                               const char *address);
 209
 210
 211 #if 0                           /* keep Emacsens' auto-indent happy */
 212 {
 213 #endif
 214 #ifdef __cplusplus
 215 }
 216 #endif
 217
 218 /* ifndef GNUNET_TRANSPORT_COMMUNICATOR_SERVICE_H */
 219 #endif
 220
 221 /** @} */  /* end of group */
 222
 223 /* end of gnunet_transport_communicator_service.h */