src/testbed/gnunet-service-testbed.h

   1 /*
   2   This file is part of GNUnet.
   3   (C) 2012 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 2, 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 /**
  22  * @file testbed/gnunet-service-testbed.h
  23  * @brief data structures shared amongst components of TESTBED service
  24  * @author Sree Harsha Totakura
  25  */
  26
  27 #include "platform.h"
  28 #include "gnunet_util_lib.h"
  29 #include "gnunet_testbed_service.h"
  30 #include "gnunet_transport_service.h"
  31 #include "gnunet_core_service.h"
  32
  33 #include "testbed.h"
  34 #include "testbed_api.h"
  35 #include "testbed_api_operations.h"
  36 #include "testbed_api_hosts.h"
  37 #include "gnunet_testing_lib.h"
  38
  39
  40 /**
  41  * Generic logging
  42  */
  43 #define LOG(kind,...)                           \
  44   GNUNET_log (kind, __VA_ARGS__)
  45
  46 /**
  47  * Debug logging
  48  */
  49 #define LOG_DEBUG(...)                          \
  50   LOG (GNUNET_ERROR_TYPE_DEBUG, __VA_ARGS__)
  51
  52 /**
  53  * By how much should the arrays lists grow
  54  */
  55 #define LIST_GROW_STEP 10
  56
  57
  58 /**
  59  * A routing entry
  60  */
  61 struct Route
  62 {
  63   /**
  64    * destination host
  65    */
  66   uint32_t dest;
  67
  68   /**
  69    * The destination host is reachable thru
  70    */
  71   uint32_t thru;
  72 };
  73
  74
  75 /**
  76  * Context information for operations forwarded to subcontrollers
  77  */
  78 struct ForwardedOperationContext
  79 {
  80   /**
  81    * The next pointer for DLL
  82    */
  83   struct ForwardedOperationContext *next;
  84
  85   /**
  86    * The prev pointer for DLL
  87    */
  88   struct ForwardedOperationContext *prev;
  89
  90   /**
  91    * The generated operation context
  92    */
  93   struct OperationContext *opc;
  94
  95   /**
  96    * The client to which we have to reply
  97    */
  98   struct GNUNET_SERVER_Client *client;
  99
 100   /**
 101    * Closure pointer
 102    */
 103   void *cls;
 104
 105   /**
 106    * Task ID for the timeout task
 107    */
 108   GNUNET_SCHEDULER_TaskIdentifier timeout_task;
 109
 110   /**
 111    * The id of the operation that has been forwarded
 112    */
 113   uint64_t operation_id;
 114
 115   /**
 116    * The type of the operation which is forwarded
 117    */
 118   enum OperationType type;
 119
 120 };
 121
 122
 123 /**
 124  * A DLL of host registrations to be made
 125  */
 126 struct HostRegistration
 127 {
 128   /**
 129    * next registration in the DLL
 130    */
 131   struct HostRegistration *next;
 132
 133   /**
 134    * previous registration in the DLL
 135    */
 136   struct HostRegistration *prev;
 137
 138   /**
 139    * The callback to call after this registration's status is available
 140    */
 141   GNUNET_TESTBED_HostRegistrationCompletion cb;
 142
 143   /**
 144    * The closure for the above callback
 145    */
 146   void *cb_cls;
 147
 148   /**
 149    * The host that has to be registered
 150    */
 151   struct GNUNET_TESTBED_Host *host;
 152 };
 153
 154
 155 /**
 156  * Context information used while linking controllers
 157  */
 158 struct LinkControllersContext
 159 {
 160   /**
 161    * The client which initiated the link controller operation
 162    */
 163   struct GNUNET_SERVER_Client *client;
 164
 165   /**
 166    * The ID of the operation
 167    */
 168   uint64_t operation_id;
 169
 170 };
 171
 172
 173 /**
 174  * Structure representing a connected(directly-linked) controller
 175  */
 176 struct Slave
 177 {
 178   /**
 179    * The controller process handle if we had started the controller
 180    */
 181   struct GNUNET_TESTBED_ControllerProc *controller_proc;
 182
 183   /**
 184    * The controller handle
 185    */
 186   struct GNUNET_TESTBED_Controller *controller;
 187
 188   /**
 189    * handle to lcc which is associated with this slave startup. Should be set to
 190    * NULL when the slave has successfully started up
 191    */
 192   struct LinkControllersContext *lcc;
 193
 194   /**
 195    * Head of the host registration DLL
 196    */
 197   struct HostRegistration *hr_dll_head;
 198
 199   /**
 200    * Tail of the host registration DLL
 201    */
 202   struct HostRegistration *hr_dll_tail;
 203
 204   /**
 205    * The current host registration handle
 206    */
 207   struct GNUNET_TESTBED_HostRegistrationHandle *rhandle;
 208
 209   /**
 210    * Hashmap to hold Registered host contexts
 211    */
 212   struct GNUNET_CONTAINER_MultiHashMap *reghost_map;
 213
 214   /**
 215    * The id of the host this controller is running on
 216    */
 217   uint32_t host_id;
 218
 219 };
 220
 221
 222 /**
 223  * A peer
 224  */
 225
 226 struct Peer
 227 {
 228
 229   union
 230   {
 231     struct
 232     {
 233       /**
 234        * The peer handle from testing API
 235        */
 236       struct GNUNET_TESTING_Peer *peer;
 237
 238       /**
 239        * The modified (by GNUNET_TESTING_peer_configure) configuration this
 240        * peer is configured with
 241        */
 242       struct GNUNET_CONFIGURATION_Handle *cfg;
 243
 244       /**
 245        * Is the peer running
 246        */
 247       int is_running;
 248
 249     } local;
 250
 251     struct
 252     {
 253       /**
 254        * The slave this peer is started through
 255        */
 256       struct Slave *slave;
 257
 258       /**
 259        * The id of the remote host this peer is running on
 260        */
 261       uint32_t remote_host_id;
 262
 263     } remote;
 264
 265   } details;
 266
 267   /**
 268    * Is this peer locally created?
 269    */
 270   int is_remote;
 271
 272   /**
 273    * Our local reference id for this peer
 274    */
 275   uint32_t id;
 276
 277   /**
 278    * References to peers are using in forwarded overlay contexts and remote
 279    * overlay connect contexts. A peer can only be destroyed after all such
 280    * contexts are destroyed. For this, we maintain a reference counter. When we
 281    * use a peer in any such context, we increment this counter. We decrement it
 282    * when we are destroying these contexts
 283    */
 284   uint32_t reference_cnt;
 285
 286   /**
 287    * While destroying a peer, due to the fact that there could be references to
 288    * this peer, we delay the peer destroy to a further time. We do this by using
 289    * this flag to destroy the peer while destroying a context in which this peer
 290    * has been used. When the flag is set to 1 and reference_cnt = 0 we destroy
 291    * the peer
 292    */
 293   uint32_t destroy_flag;
 294
 295 };
 296
 297
 298 /**
 299  * The main context information associated with the client which started us
 300  */
 301 struct Context
 302 {
 303   /**
 304    * The client handle associated with this context
 305    */
 306   struct GNUNET_SERVER_Client *client;
 307
 308   /**
 309    * The network address of the master controller
 310    */
 311   char *master_ip;
 312
 313   /**
 314    * The TESTING system handle for starting peers locally
 315    */
 316   struct GNUNET_TESTING_System *system;
 317
 318   /**
 319    * Our host id according to this context
 320    */
 321   uint32_t host_id;
 322 };
 323
 324
 325 /**
 326  * The structure for identifying a shared service
 327  */
 328 struct SharedService
 329 {
 330   /**
 331    * The name of the shared service
 332    */
 333   char *name;
 334
 335   /**
 336    * Number of shared peers per instance of the shared service
 337    */
 338   uint32_t num_shared;
 339
 340   /**
 341    * Number of peers currently sharing the service
 342    */
 343   uint32_t num_sharing;
 344 };
 345
 346
 347 /**
 348  * Context information to used during operations which forward the overlay
 349  * connect message
 350  */
 351 struct ForwardedOverlayConnectContext
 352 {
 353   /**
 354    * next ForwardedOverlayConnectContext in the DLL
 355    */
 356   struct ForwardedOverlayConnectContext *next;
 357
 358   /**
 359    * previous ForwardedOverlayConnectContext in the DLL
 360    */
 361   struct ForwardedOverlayConnectContext *prev;
 362
 363   /**
 364    * A copy of the original overlay connect message
 365    */
 366   struct GNUNET_MessageHeader *orig_msg;
 367
 368   /**
 369    * The id of the operation which created this context information
 370    */
 371   uint64_t operation_id;
 372
 373   /**
 374    * the id of peer 1
 375    */
 376   uint32_t peer1;
 377
 378   /**
 379    * The id of peer 2
 380    */
 381   uint32_t peer2;
 382
 383   /**
 384    * Id of the host where peer2 is running
 385    */
 386   uint32_t peer2_host_id;
 387 };
 388
 389
 390 /**
 391  * The type for data structures which commonly arrive at the slave_event_callback
 392  */
 393 enum ClosureType
 394 {
 395   /**
 396    * Type for RegisteredHostContext closures
 397    */
 398   CLOSURE_TYPE_RHC = 1,
 399
 400   /**
 401    * Type for LinkControllersForwardingContext closures
 402    */
 403   CLOSURE_TYPE_LCF
 404 };
 405
 406
 407 /**
 408  * This context information will be created for each host that is registered at
 409  * slave controllers during overlay connects.
 410  */
 411 struct RegisteredHostContext
 412 {
 413   /**
 414    * The type of this data structure. Set this to CLOSURE_TYPE_RHC
 415    */
 416   enum ClosureType type;
 417
 418   /**
 419    * The host which is being registered
 420    */
 421   struct GNUNET_TESTBED_Host *reg_host;
 422
 423   /**
 424    * The host of the controller which has to connect to the above rhost
 425    */
 426   struct GNUNET_TESTBED_Host *host;
 427
 428   /**
 429    * The gateway to which this operation is forwarded to
 430    */
 431   struct Slave *gateway;
 432
 433   /**
 434    * The gateway through which peer2's controller can be reached
 435    */
 436   struct Slave *gateway2;
 437
 438   /**
 439    * Handle for sub-operations
 440    */
 441   struct GNUNET_TESTBED_Operation *sub_op;
 442
 443   /**
 444    * The client which initiated the link controller operation
 445    */
 446   struct GNUNET_SERVER_Client *client;
 447
 448   /**
 449    * Head of the ForwardedOverlayConnectContext DLL
 450    */
 451   struct ForwardedOverlayConnectContext *focc_dll_head;
 452
 453   /**
 454    * Tail of the ForwardedOverlayConnectContext DLL
 455    */
 456   struct ForwardedOverlayConnectContext *focc_dll_tail;
 457
 458   /**
 459    * Enumeration of states for this context
 460    */
 461   enum RHCState
 462   {
 463
 464     /**
 465      * The initial state
 466      */
 467     RHC_INIT = 0,
 468
 469     /**
 470      * State where we attempt to get peer2's controller configuration
 471      */
 472     RHC_GET_CFG,
 473
 474     /**
 475      * State where we attempt to link the controller of peer 1 to the controller
 476      * of peer2
 477      */
 478     RHC_LINK,
 479
 480     /**
 481      * State where we attempt to do the overlay connection again
 482      */
 483     RHC_OL_CONNECT
 484   } state;
 485
 486 };
 487
 488
 489 /**
 490  * States of LCFContext
 491  */
 492 enum LCFContextState
 493 {
 494   /**
 495    * The Context has been initialized; Nothing has been done on it
 496    */
 497   INIT,
 498
 499   /**
 500    * Delegated host has been registered at the forwarding controller
 501    */
 502   DELEGATED_HOST_REGISTERED,
 503
 504   /**
 505    * The slave host has been registred at the forwarding controller
 506    */
 507   SLAVE_HOST_REGISTERED,
 508
 509   /**
 510    * The context has been finished (may have error)
 511    */
 512   FINISHED
 513 };
 514
 515
 516 /**
 517  * Link controllers request forwarding context
 518  */
 519 struct LCFContext
 520 {
 521   /**
 522    * The type of this data structure. Set this to CLOSURE_TYPE_LCF
 523    */
 524   enum ClosureType type;
 525
 526   /**
 527    * The gateway which will pass the link message to delegated host
 528    */
 529   struct Slave *gateway;
 530
 531   /**
 532    * The client which has asked to perform this operation
 533    */
 534   struct GNUNET_SERVER_Client *client;
 535
 536   /**
 537    * Handle for operations which are forwarded while linking controllers
 538    */
 539   struct GNUNET_TESTBED_Operation *op;
 540
 541   /**
 542    * The configuration which has to be either used as a template while starting
 543    * the delegated controller or for connecting to the delegated controller
 544    */
 545   struct GNUNET_CONFIGURATION_Handle *cfg;
 546
 547   /**
 548    * The timeout task
 549    */
 550   GNUNET_SCHEDULER_TaskIdentifier timeout_task;
 551
 552   /**
 553    * The id of the operation which created this context
 554    */
 555   uint64_t operation_id;
 556
 557   /**
 558    * should the slave controller start the delegated controller?
 559    */
 560   int is_subordinate;
 561
 562   /**
 563    * The state of this context
 564    */
 565   enum LCFContextState state;
 566
 567   /**
 568    * The delegated host
 569    */
 570   uint32_t delegated_host_id;
 571
 572   /**
 573    * The slave host
 574    */
 575   uint32_t slave_host_id;
 576
 577 };
 578
 579
 580 /**
 581  * Structure of a queue entry in LCFContext request queue
 582  */
 583 struct LCFContextQueue
 584 {
 585   /**
 586    * The LCFContext
 587    */
 588   struct LCFContext *lcf;
 589
 590   /**
 591    * Head prt for DLL
 592    */
 593   struct LCFContextQueue *next;
 594
 595   /**
 596    * Tail ptr for DLL
 597    */
 598   struct LCFContextQueue *prev;
 599 };
 600
 601
 602 /**
 603  * Our configuration
 604  */
 605 struct GNUNET_CONFIGURATION_Handle *our_config;
 606
 607 /**
 608  * The master context; generated with the first INIT message
 609  */
 610 extern struct Context *GST_context;
 611
 612 /**
 613  * DLL head for forwarded operation contexts
 614  */
 615 extern struct ForwardedOperationContext *fopcq_head;
 616
 617 /**
 618  * DLL tail for forwarded operation contexts
 619  */
 620 extern struct ForwardedOperationContext *fopcq_tail;
 621
 622 /**
 623  * A list of peers we know about
 624  */
 625 extern struct Peer **GST_peer_list;
 626
 627 /**
 628  * Array of hosts
 629  */
 630 extern struct GNUNET_TESTBED_Host **GST_host_list;
 631
 632 /**
 633  * A list of directly linked neighbours
 634  */
 635 extern struct Slave **GST_slave_list;
 636
 637 /**
 638  * Operation queue for open file descriptors
 639  */
 640 extern struct OperationQueue *GST_opq_openfds;
 641
 642 /**
 643  * Timeout for operations which may take some time
 644  */
 645 const extern struct GNUNET_TIME_Relative GST_timeout;
 646
 647 /**
 648  * The size of the peer list
 649  */
 650 extern unsigned int GST_peer_list_size;
 651
 652 /**
 653  * The size of the host list
 654  */
 655 extern unsigned int GST_host_list_size;
 656
 657 /**
 658  * The size of directly linked neighbours list
 659  */
 660 extern unsigned int GST_slave_list_size;
 661
 662 /**
 663  * The directory where to store load statistics data
 664  */
 665 extern char *GST_stats_dir;
 666
 667
 668 /**
 669  * Queues a message in send queue for sending to the service
 670  *
 671  * @param client the client to whom the queued message has to be sent
 672  * @param msg the message to queue
 673  */
 674 void
 675 GST_queue_message (struct GNUNET_SERVER_Client *client,
 676                    struct GNUNET_MessageHeader *msg);
 677
 678
 679 /**
 680  * Function to destroy a peer
 681  *
 682  * @param peer the peer structure to destroy
 683  */
 684 void
 685 GST_destroy_peer (struct Peer *peer);
 686
 687
 688 /**
 689  * Finds the route with directly connected host as destination through which
 690  * the destination host can be reached
 691  *
 692  * @param host_id the id of the destination host
 693  * @return the route with directly connected destination host; NULL if no route
 694  *           is found
 695  */
 696 struct Route *
 697 GST_find_dest_route (uint32_t host_id);
 698
 699
 700 /**
 701  * Handler for GNUNET_MESSAGE_TYPE_TESTBED_OLCONNECT messages
 702  *
 703  * @param cls NULL
 704  * @param client identification of the client
 705  * @param message the actual message
 706  */
 707 void
 708 GST_handle_overlay_connect (void *cls, struct GNUNET_SERVER_Client *client,
 709                             const struct GNUNET_MessageHeader *message);
 710
 711
 712 /**
 713  * Adds a host registration's request to a slave's registration queue
 714  *
 715  * @param slave the slave controller at which the given host has to be
 716  *          registered
 717  * @param cb the host registration completion callback
 718  * @param cb_cls the closure for the host registration completion callback
 719  * @param host the host which has to be registered
 720  */
 721 void
 722 GST_queue_host_registration (struct Slave *slave,
 723                              GNUNET_TESTBED_HostRegistrationCompletion cb,
 724                              void *cb_cls, struct GNUNET_TESTBED_Host *host);
 725
 726
 727 /**
 728  * Callback to relay the reply msg of a forwarded operation back to the client
 729  *
 730  * @param cls ForwardedOperationContext
 731  * @param msg the message to relay
 732  */
 733 void
 734 GST_forwarded_operation_reply_relay (void *cls,
 735                                      const struct GNUNET_MessageHeader *msg);
 736
 737
 738 /**
 739  * Task to free resources when forwarded operation has been timedout
 740  *
 741  * @param cls the ForwardedOperationContext
 742  * @param tc the task context from scheduler
 743  */
 744 void
 745 GST_forwarded_operation_timeout (void *cls,
 746                                  const struct GNUNET_SCHEDULER_TaskContext *tc);
 747
 748
 749 /**
 750  * Send operation failure message to client
 751  *
 752  * @param client the client to which the failure message has to be sent to
 753  * @param operation_id the id of the failed operation
 754  * @param emsg the error message; can be NULL
 755  */
 756 void
 757 GST_send_operation_fail_msg (struct GNUNET_SERVER_Client *client,
 758                              uint64_t operation_id, const char *emsg);
 759
 760
 761 /**
 762  * Handler for GNUNET_MESSAGE_TYPE_TESTBED_REQUESTCONNECT messages
 763  *
 764  * @param cls NULL
 765  * @param client identification of the client
 766  * @param message the actual message
 767  */
 768 void
 769 GST_handle_remote_overlay_connect (void *cls,
 770                                    struct GNUNET_SERVER_Client *client,
 771                                    const struct GNUNET_MessageHeader *message);
 772
 773
 774 /**
 775  * Processes a forwarded overlay connect context in the queue of the given RegisteredHostContext
 776  *
 777  * @param rhc the RegisteredHostContext
 778  */
 779 void
 780 GST_process_next_focc (struct RegisteredHostContext *rhc);
 781
 782
 783 /**
 784  * Cleans up ForwardedOverlayConnectContext
 785  *
 786  * @param focc the ForwardedOverlayConnectContext to cleanup
 787  */
 788 void
 789 GST_cleanup_focc (struct ForwardedOverlayConnectContext *focc);
 790
 791
 792 /**
 793  * Clears all pending overlay connect contexts in queue
 794  */
 795 void
 796 GST_free_occq ();
 797
 798
 799 /**
 800  * Clears all pending remote overlay connect contexts in queue
 801  */
 802 void
 803 GST_free_roccq ();
 804
 805
 806 /**
 807  * Initializes the cache
 808  *
 809  * @param size the size of the cache
 810  */
 811 void
 812 GST_cache_init (unsigned int size);
 813
 814
 815 /**
 816  * Clear cache
 817  */
 818 void
 819 GST_cache_clear ();
 820
 821
 822 /**
 823  * Looks up in the hello cache and returns the HELLO of the given peer
 824  *
 825  * @param peer_id the index of the peer whose HELLO has to be looked up
 826  * @return the HELLO message; NULL if not found
 827  */
 828 const struct GNUNET_MessageHeader *
 829 GST_cache_lookup_hello (const unsigned int peer_id);
 830
 831
 832 /**
 833  * Caches the HELLO of the given peer. Updates the HELLO if it was already
 834  * cached before
 835  *
 836  * @param peer_id the peer identity of the peer whose HELLO has to be cached
 837  * @param hello the HELLO message
 838  */
 839 void
 840 GST_cache_add_hello (const unsigned int peer_id,
 841                      const struct GNUNET_MessageHeader *hello);
 842
 843
 844 /**
 845  * Functions of this type are called when the needed handle is available for
 846  * usage. These functions are to be registered with either of the functions
 847  * GST_cache_get_handle_transport() or GST_cache_get_handle_core(). The
 848  * corresponding handles will be set and if they are not, then it signals an
 849  * error while opening the handles.
 850  *
 851  * @param cls the closure passed to GST_cache_get_handle_transport() or
 852  *          GST_cache_get_handle_core()
 853  * @param ch the handle to CORE. Can be NULL if it is not requested
 854  * @param th the handle to TRANSPORT. Can be NULL if it is not requested
 855  * @param peer_id the identity of the peer. Will be NULL if ch is NULL. In other
 856  *          cases, its value being NULL means that CORE connection has failed.
 857  */
 858 typedef void (*GST_cache_handle_ready_cb) (void *cls,
 859                                            struct GNUNET_CORE_Handle * ch,
 860                                            struct GNUNET_TRANSPORT_Handle * th,
 861                                            const struct GNUNET_PeerIdentity *
 862                                            peer_id);
 863
 864
 865 /**
 866  * Callback to notify when the target peer given to
 867  * GST_cache_get_handle_transport() is connected. Note that this callback may
 868  * not be called if the target peer is already connected. Use
 869  * GNUNET_TRANSPORT_check_neighbour_connected() to check if the target peer is
 870  * already connected or not. This callback will be called only once or never (in
 871  * case the target cannot be connected).
 872  *
 873  * @param cls the closure given to GST_cache_get_handle_done() for this callback
 874  * @param target the peer identity of the target peer. The pointer should be
 875  *          valid until GST_cache_get_handle_done() is called.
 876  */
 877 typedef void (*GST_cache_peer_connect_notify) (void *cls,
 878                                                const struct GNUNET_PeerIdentity
 879                                                * target);
 880
 881
 882 /**
 883  * Get a transport handle with the given configuration. If the handle is already
 884  * cached before, it will be retured in the given callback; the peer_id is used to lookup in the
 885  * cache. If not a new operation is started to open the transport handle and
 886  * will be given in the callback when it is available.
 887  *
 888  * @param peer_id the index of the peer
 889  * @param cfg the configuration with which the transport handle has to be
 890  *          created if it was not present in the cache
 891  * @param cb the callback to notify when the transport handle is available
 892  * @param cb_cls the closure for the above callback
 893  * @param target the peer identify of the peer whose connection to our TRANSPORT
 894  *          subsystem will be notified through the connect_notify_cb. Can be NULL
 895  * @param connect_notify_cb the callback to call when the given target peer is
 896  *          connected. This callback will only be called once or never again (in
 897  *          case the target peer cannot be connected). Can be NULL
 898  * @param connect_notify_cb_cls the closure for the above callback
 899  * @return the handle which can be used cancel or mark that the handle is no
 900  *           longer being used
 901  */
 902 struct GSTCacheGetHandle *
 903 GST_cache_get_handle_transport (unsigned int peer_id,
 904                                 const struct GNUNET_CONFIGURATION_Handle *cfg,
 905                                 GST_cache_handle_ready_cb cb, void *cb_cls,
 906                                 const struct GNUNET_PeerIdentity *target,
 907                                 GST_cache_peer_connect_notify connect_notify_cb,
 908                                 void *connect_notify_cb_cls);
 909
 910
 911 /**
 912  * Get a CORE handle with the given configuration. If the handle is already
 913  * cached before, it will be retured in the given callback; the peer_id is used
 914  * to lookup in the cache. If the handle is not cached before, a new operation
 915  * is started to open the CORE handle and will be given in the callback when it
 916  * is available along with the peer identity
 917  *
 918  * @param peer_id the index of the peer
 919  * @param cfg the configuration with which the transport handle has to be
 920  *          created if it was not present in the cache
 921  * @param cb the callback to notify when the transport handle is available
 922  * @param cb_cls the closure for the above callback
 923  * @param target the peer identify of the peer whose connection to our CORE
 924  *          subsystem will be notified through the connect_notify_cb. Can be NULL
 925  * @param connect_notify_cb the callback to call when the given target peer is
 926  *          connected. This callback will only be called once or never again (in
 927  *          case the target peer cannot be connected). Can be NULL
 928  * @param connect_notify_cb_cls the closure for the above callback
 929  * @return the handle which can be used cancel or mark that the handle is no
 930  *           longer being used
 931  */
 932 struct GSTCacheGetHandle *
 933 GST_cache_get_handle_core (unsigned int peer_id,
 934                            const struct GNUNET_CONFIGURATION_Handle *cfg,
 935                            GST_cache_handle_ready_cb cb, void *cb_cls,
 936                            const struct GNUNET_PeerIdentity *target,
 937                            GST_cache_peer_connect_notify connect_notify_cb,
 938                            void *connect_notify_cb_cls);
 939
 940
 941 /**
 942  * Mark the GetCacheHandle as being done if a handle has been provided already
 943  * or as being cancelled if the callback for the handle hasn't been called.
 944  *
 945  * @param cgh the CacheGetHandle handle
 946  */
 947 void
 948 GST_cache_get_handle_done (struct GSTCacheGetHandle *cgh);
 949
 950 /* End of gnunet-service-testbed.h */