transport-testing-communicator.h (13296B)
1 /* 2 This file is part of GNUnet. 3 Copyright (C) 2019 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 SPDX-License-Identifier: AGPL3.0-or-later 19 */ 20 21 /** 22 * @file transport/transport-testing-communicator.h 23 * @brief functions and structures related to testing-tng 24 * @author Christian Grothoff 25 * @author Julius Bünger 26 */ 27 #include "platform.h" 28 #include "gnunet_util_lib.h" 29 #include "gnunet_pils_service.h" 30 #include "gnunet_transport_communication_service.h" 31 #include "transport.h" 32 33 /** 34 * @brief Queue of a communicator and some context 35 */ 36 struct GNUNET_TRANSPORT_TESTING_TransportCommunicatorQueue; 37 38 39 /** 40 * @brief Handle/Context to a single transmission 41 */ 42 struct GNUNET_TRANSPORT_TESTING_TransportCommunicatorTransmission; 43 44 /** 45 * @brief Function signature for callbacks that are called when new 46 * backchannel message arrived 47 * 48 * @param cls Closure 49 * @param msg Backchannel message 50 * @param pid Target peer 51 */ 52 typedef struct GNUNET_TRANSPORT_TESTING_TransportCommunicatorHandle * 53 (*GNUNET_TRANSPORT_TESTING_BackchannelCallback)(void *cls, 54 struct GNUNET_MessageHeader *msg 55 , 56 struct GNUNET_PeerIdentity *pid) 57 ; 58 59 60 /** 61 * @brief Function signature for callbacks that are called once the peer 62 * identity of the peer this communicator belongs to is known. 63 * 64 * The peer identity is derived at runtime by PILS, so it is not known 65 * when the communicator is started. It may also change later on, in 66 * which case this callback is invoked again. 67 * 68 * @param cls Closure 69 * @param tc_h Communicator handle 70 * @param peer_id the (new) peer identity of this peer 71 */ 72 typedef void 73 (*GNUNET_TRANSPORT_TESTING_PeerIdCallback)(void *cls, 74 struct 75 GNUNET_TRANSPORT_TESTING_TransportCommunicatorHandle 76 *tc_h, 77 const struct GNUNET_PeerIdentity * 78 peer_id); 79 80 81 /** 82 * @brief Function signature for callbacks that are called when new 83 * communicators become available 84 * 85 * @param cls Closure 86 * @param tc_h Communicator handle 87 * @param cc Characteristics of communicator 88 * @param address_prefix Prefix of the address 89 */ 90 typedef void 91 (*GNUNET_TRANSPORT_TESTING_CommunicatorAvailableCallback)(void *cls, 92 struct 93 GNUNET_TRANSPORT_TESTING_TransportCommunicatorHandle 94 *tc_h, 95 enum 96 GNUNET_TRANSPORT_CommunicatorCharacteristics 97 cc, 98 char *address_prefix); 99 100 101 /** 102 * @brief Receive information about the address of a communicator. 103 * 104 * @param cls Closure 105 * @param tc_h Communicator handle 106 * @param address Address represented as string 107 * @param expiration Expiration 108 * @param aid Aid 109 * @param nt Network Type 110 */ 111 typedef void 112 (*GNUNET_TRANSPORT_TESTING_AddAddressCallback)(void *cls, 113 struct 114 GNUNET_TRANSPORT_TESTING_TransportCommunicatorHandle 115 *tc_h, 116 const char *address, 117 struct GNUNET_TIME_Relative 118 expiration, 119 uint32_t aid, 120 enum GNUNET_NetworkType nt); 121 122 123 /** 124 * @brief Get informed about the success of a queue request. 125 * 126 * @param cls Closure 127 * @param tc_h Communicator handle 128 * @param will_try #GNUNET_YES if communicator will try to create queue 129 */ 130 typedef void 131 (*GNUNET_TRANSPORT_TESTING_QueueCreateReplyCallback)(void *cls, 132 struct 133 GNUNET_TRANSPORT_TESTING_TransportCommunicatorHandle 134 *tc_h, 135 int will_try); 136 137 138 /** 139 * @brief Handle opening of queue 140 * 141 * @param cls Closure 142 * @param tc_h Communicator handle 143 * @param tc_queue Handle to newly opened queue 144 */ 145 typedef void 146 (*GNUNET_TRANSPORT_TESTING_AddQueueCallback)(void *cls, 147 struct 148 GNUNET_TRANSPORT_TESTING_TransportCommunicatorHandle 149 *tc_h, 150 struct 151 GNUNET_TRANSPORT_TESTING_TransportCommunicatorQueue 152 *tc_queue, 153 size_t mtu); 154 155 156 /** 157 * @brief Handle an incoming message 158 * 159 * @param cls Closure 160 * @param tc_h Handle to the receiving communicator 161 * @param msg Received message 162 */ 163 typedef void 164 (*GNUNET_TRANSPORT_TESTING_IncomingMessageCallback)(void *cls, 165 struct 166 GNUNET_TRANSPORT_TESTING_TransportCommunicatorHandle 167 *tc_h, 168 const char*payload, 169 size_t payload_len); 170 171 /** 172 * @brief Handle to a transport communicator 173 */ 174 struct GNUNET_TRANSPORT_TESTING_TransportCommunicatorHandle 175 { 176 /** 177 * Clients 178 */ 179 struct MyClient *client_head; 180 struct MyClient *client_tail; 181 182 /** 183 * @brief Handle to the client 184 */ 185 struct GNUNET_MQ_Handle *c_mq; 186 187 /** 188 * @brief Handle to the configuration 189 */ 190 struct GNUNET_CONFIGURATION_Handle *cfg; 191 192 /** 193 * @brief File name of configuration file 194 */ 195 char *cfg_filename; 196 197 /** 198 * @brief Our peer identity, as reported by PILS. 199 * 200 * Only valid once @e have_peer_id is #GNUNET_YES. 201 */ 202 struct GNUNET_PeerIdentity peer_id; 203 204 /** 205 * @brief #GNUNET_YES once PILS told us our @e peer_id 206 */ 207 int have_peer_id; 208 209 /** 210 * @brief Handle to the PILS service of this peer 211 */ 212 struct GNUNET_PILS_Handle *pils; 213 214 /** 215 * @brief PILS service process 216 */ 217 struct GNUNET_Process *pils_proc; 218 219 /** 220 * @brief Handle to the transport service 221 */ 222 struct GNUNET_SERVICE_Handle *tsh; 223 224 /** 225 * @brief Task that will be run on shutdown to stop and clean transport 226 * service 227 */ 228 struct GNUNET_SCHEDULER_Task *ts_shutdown_task; 229 230 231 /** 232 * @brief Process of the communicator 233 */ 234 struct GNUNET_Process *c_proc; 235 236 /** 237 * NAT process 238 */ 239 struct GNUNET_Process *nat_proc; 240 241 /** 242 * resolver service process 243 */ 244 struct GNUNET_Process *resolver_proc; 245 246 /** 247 * statistics service process 248 */ 249 struct GNUNET_Process *stat_proc; 250 251 /** 252 * peerstore service process 253 */ 254 struct GNUNET_Process *ps_proc; 255 256 /** 257 * @brief Task that will be run on shutdown to stop and clean communicator 258 */ 259 struct GNUNET_SCHEDULER_Task *c_shutdown_task; 260 261 /** 262 * @brief Characteristics of the communicator 263 */ 264 enum GNUNET_TRANSPORT_CommunicatorCharacteristics c_characteristics; 265 266 /** 267 * @brief Specifies supported addresses 268 */ 269 char *c_addr_prefix; 270 271 /** 272 * @brief Specifies supported addresses 273 */ 274 char *c_address; 275 276 /** 277 * @brief Head of the DLL of queues associated with this communicator 278 */ 279 struct GNUNET_TRANSPORT_TESTING_TransportCommunicatorQueue *queue_head; 280 281 /** 282 * @brief Tail of the DLL of queues associated with this communicator 283 */ 284 struct GNUNET_TRANSPORT_TESTING_TransportCommunicatorQueue *queue_tail; 285 286 /* Callbacks + Closures */ 287 /** 288 * @brief Callback called when PILS assigned us a peer identity 289 */ 290 GNUNET_TRANSPORT_TESTING_PeerIdCallback peer_id_cb; 291 292 /** 293 * @brief Callback called when a new communicator connects 294 */ 295 GNUNET_TRANSPORT_TESTING_CommunicatorAvailableCallback 296 communicator_available_cb; 297 298 /** 299 * @brief Callback called when a new communicator connects 300 */ 301 GNUNET_TRANSPORT_TESTING_AddAddressCallback add_address_cb; 302 303 /** 304 * @brief Callback called when a new communicator connects 305 */ 306 GNUNET_TRANSPORT_TESTING_QueueCreateReplyCallback queue_create_reply_cb; 307 308 /** 309 * @brief Callback called when a new communicator connects 310 */ 311 GNUNET_TRANSPORT_TESTING_AddQueueCallback add_queue_cb; 312 313 /** 314 * @brief Callback called when a new communicator connects 315 */ 316 GNUNET_TRANSPORT_TESTING_IncomingMessageCallback incoming_msg_cb; 317 318 /** 319 * @brief Backchannel callback 320 */ 321 GNUNET_TRANSPORT_TESTING_BackchannelCallback bc_cb; 322 323 /** 324 * Our service handle 325 */ 326 struct GNUNET_SERVICE_Handle *sh; 327 328 /** 329 * @brief Closure to the callback 330 */ 331 void *cb_cls; 332 333 /** 334 * Callback to call when message ack received. 335 */ 336 GNUNET_SCHEDULER_TaskCallback cont; 337 338 /** 339 * Closure for cont 340 */ 341 void *cont_cls; 342 343 /** 344 * Backchannel supported 345 */ 346 int bc_enabled; 347 }; 348 349 /** 350 * @brief Start communicator part of transport service and communicator 351 * 352 * Also starts the PILS service of that peer. The peer identity is not 353 * known when this function returns; it is reported via @a peer_id_cb. 354 * 355 * @param service_name Name of the service 356 * @param cfg Configuration handle 357 * @param peer_id_cb Callback handling the peer identity assigned by PILS 358 * @param communicator_available Callback that is called when a new 359 * communicator becomes available 360 * @param add_address_cb Callback handling new addresses 361 * @param queue_create_reply_cb Callback handling success of queue requests 362 * @param add_queue_cb Callback handling freshly created queues 363 * @param incoming_message_cb Callback handling incoming messages 364 * @param cb_cls Closure to @p communicator_available 365 * 366 * @return Handle to the communicator duo 367 */ 368 struct GNUNET_TRANSPORT_TESTING_TransportCommunicatorHandle * 369 GNUNET_TRANSPORT_TESTING_transport_communicator_service_start ( 370 const char *service_name, 371 const char *binary_name, 372 const char *cfg_filename, 373 GNUNET_TRANSPORT_TESTING_PeerIdCallback peer_id_cb, 374 GNUNET_TRANSPORT_TESTING_CommunicatorAvailableCallback 375 communicator_available_cb, 376 GNUNET_TRANSPORT_TESTING_AddAddressCallback add_address_cb, 377 GNUNET_TRANSPORT_TESTING_QueueCreateReplyCallback queue_create_reply_cb, 378 GNUNET_TRANSPORT_TESTING_AddQueueCallback add_queue_cb, 379 GNUNET_TRANSPORT_TESTING_IncomingMessageCallback incoming_message_cb, 380 GNUNET_TRANSPORT_TESTING_BackchannelCallback bc_cb, 381 void *cb_cls); 382 383 384 void 385 GNUNET_TRANSPORT_TESTING_transport_communicator_service_stop ( 386 struct GNUNET_TRANSPORT_TESTING_TransportCommunicatorHandle *tc_h); 387 388 389 /** 390 * @brief Instruct communicator to open a queue 391 * 392 * @param tc_h Handle to communicator which shall open queue 393 * @param peer_id Towards which peer 394 * @param address For which address 395 */ 396 void 397 GNUNET_TRANSPORT_TESTING_transport_communicator_open_queue (struct 398 GNUNET_TRANSPORT_TESTING_TransportCommunicatorHandle 399 *tc_h, 400 const struct 401 GNUNET_PeerIdentity 402 *peer_id, 403 const char *address) 404 ; 405 406 407 /** 408 * @brief Instruct communicator to send data 409 * 410 * @param tc_queue The queue to use for sending 411 * @param cont function to call when done sending 412 * @param cont_cls closure for @a cont 413 * @param payload Data to send 414 * @param payload_size Size of the @a payload 415 */ 416 void 417 GNUNET_TRANSPORT_TESTING_transport_communicator_send (struct 418 GNUNET_TRANSPORT_TESTING_TransportCommunicatorHandle 419 *tc_h, 420 GNUNET_SCHEDULER_TaskCallback 421 cont, 422 void *cont_cls, 423 const void *payload, 424 size_t payload_size);