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 /**
 664  * Queues a message in send queue for sending to the service
 665  *
 666  * @param client the client to whom the queued message has to be sent
 667  * @param msg the message to queue
 668  */
 669 void
 670 GST_queue_message (struct GNUNET_SERVER_Client *client,
 671                    struct GNUNET_MessageHeader *msg);
 672
 673
 674 /**
 675  * Function to destroy a peer
 676  *
 677  * @param peer the peer structure to destroy
 678  */
 679 void
 680 GST_destroy_peer (struct Peer *peer);
 681
 682
 683 /**
 684  * Finds the route with directly connected host as destination through which
 685  * the destination host can be reached
 686  *
 687  * @param host_id the id of the destination host
 688  * @return the route with directly connected destination host; NULL if no route
 689  *           is found
 690  */
 691 struct Route *
 692 GST_find_dest_route (uint32_t host_id);
 693
 694
 695 /**
 696  * Handler for GNUNET_MESSAGE_TYPE_TESTBED_OLCONNECT messages
 697  *
 698  * @param cls NULL
 699  * @param client identification of the client
 700  * @param message the actual message
 701  */
 702 void
 703 GST_handle_overlay_connect (void *cls, struct GNUNET_SERVER_Client *client,
 704                             const struct GNUNET_MessageHeader *message);
 705
 706
 707 /**
 708  * Adds a host registration's request to a slave's registration queue
 709  *
 710  * @param slave the slave controller at which the given host has to be
 711  *          registered
 712  * @param cb the host registration completion callback
 713  * @param cb_cls the closure for the host registration completion callback
 714  * @param host the host which has to be registered
 715  */
 716 void
 717 GST_queue_host_registration (struct Slave *slave,
 718                              GNUNET_TESTBED_HostRegistrationCompletion cb,
 719                              void *cb_cls, struct GNUNET_TESTBED_Host *host);
 720
 721
 722 /**
 723  * Callback to relay the reply msg of a forwarded operation back to the client
 724  *
 725  * @param cls ForwardedOperationContext
 726  * @param msg the message to relay
 727  */
 728 void
 729 GST_forwarded_operation_reply_relay (void *cls,
 730                                      const struct GNUNET_MessageHeader *msg);
 731
 732
 733 /**
 734  * Task to free resources when forwarded operation has been timedout
 735  *
 736  * @param cls the ForwardedOperationContext
 737  * @param tc the task context from scheduler
 738  */
 739 void
 740 GST_forwarded_operation_timeout (void *cls,
 741                                  const struct GNUNET_SCHEDULER_TaskContext *tc);
 742
 743
 744 /**
 745  * Send operation failure message to client
 746  *
 747  * @param client the client to which the failure message has to be sent to
 748  * @param operation_id the id of the failed operation
 749  * @param emsg the error message; can be NULL
 750  */
 751 void
 752 GST_send_operation_fail_msg (struct GNUNET_SERVER_Client *client,
 753                              uint64_t operation_id, const char *emsg);
 754
 755
 756 /**
 757  * Handler for GNUNET_MESSAGE_TYPE_TESTBED_REQUESTCONNECT messages
 758  *
 759  * @param cls NULL
 760  * @param client identification of the client
 761  * @param message the actual message
 762  */
 763 void
 764 GST_handle_remote_overlay_connect (void *cls,
 765                                    struct GNUNET_SERVER_Client *client,
 766                                    const struct GNUNET_MessageHeader *message);
 767
 768
 769 /**
 770  * Processes a forwarded overlay connect context in the queue of the given RegisteredHostContext
 771  *
 772  * @param rhc the RegisteredHostContext
 773  */
 774 void
 775 GST_process_next_focc (struct RegisteredHostContext *rhc);
 776
 777
 778 /**
 779  * Cleans up ForwardedOverlayConnectContext
 780  *
 781  * @param focc the ForwardedOverlayConnectContext to cleanup
 782  */
 783 void
 784 GST_cleanup_focc (struct ForwardedOverlayConnectContext *focc);
 785
 786
 787 /**
 788  * Clears all pending overlay connect contexts in queue
 789  */
 790 void
 791 GST_free_occq ();
 792
 793
 794 /**
 795  * Clears all pending remote overlay connect contexts in queue
 796  */
 797 void
 798 GST_free_roccq ();
 799
 800
 801 /**
 802  * Initializes the cache
 803  *
 804  * @param size the size of the cache
 805  */
 806 void
 807 GST_cache_init (unsigned int size);
 808
 809
 810 /**
 811  * Clear cache
 812  */
 813 void
 814 GST_cache_clear ();
 815
 816
 817 /**
 818  * Looks up in the hello cache and returns the HELLO of the given peer
 819  *
 820  * @param peer_id the index of the peer whose HELLO has to be looked up
 821  * @return the HELLO message; NULL if not found
 822  */
 823 const struct GNUNET_MessageHeader *
 824 GST_cache_lookup_hello (const unsigned int peer_id);
 825
 826
 827 /**
 828  * Caches the HELLO of the given peer. Updates the HELLO if it was already
 829  * cached before
 830  *
 831  * @param id the peer identity of the peer whose HELLO has to be cached
 832  * @param hello the HELLO message
 833  */
 834 void
 835 GST_cache_add_hello (const unsigned int peer_id,
 836                      const struct GNUNET_MessageHeader *hello);
 837
 838
 839 /**
 840  * Functions of this type are called when the needed handle is available for
 841  * usage. These functions are to be registered with either of the functions
 842  * GST_cache_get_handle_transport() or GST_cache_get_handle_core(). The
 843  * corresponding handles will be set and if they are not, then it signals an
 844  * error while opening the handles.
 845  *
 846  * @param cls the closure passed to GST_cache_get_handle_transport() or
 847  *          GST_cache_get_handle_core()
 848  * @param ch the handle to CORE. Can be NULL if it is not requested
 849  * @param th the handle to TRANSPORT. Can be NULL if it is not requested
 850  * @param peer_id the identity of the peer. Will be NULL if ch is NULL. In other
 851  *          cases, its value being NULL means that CORE connection has failed.
 852  */
 853 typedef void (*GST_cache_handle_ready_cb) (void *cls,
 854                                            struct GNUNET_CORE_Handle * ch,
 855                                            struct GNUNET_TRANSPORT_Handle * th,
 856                                            const struct GNUNET_PeerIdentity *
 857                                            peer_id);
 858
 859
 860 /**
 861  * Callback to notify when the target peer given to
 862  * GST_cache_get_handle_transport() is connected. Note that this callback may
 863  * not be called if the target peer is already connected. Use
 864  * GNUNET_TRANSPORT_check_neighbour_connected() to check if the target peer is
 865  * already connected or not. This callback will be called only once or never (in
 866  * case the target cannot be connected).
 867  *
 868  * @param cls the closure given to GST_cache_get_handle_done() for this callback
 869  * @param target the peer identity of the target peer. The pointer should be
 870  *          valid until GST_cache_get_handle_done() is called.
 871  */
 872 typedef void (*GST_cache_peer_connect_notify) (void *cls,
 873                                                const struct GNUNET_PeerIdentity
 874                                                * target);
 875
 876
 877 /**
 878  * Get a transport handle with the given configuration. If the handle is already
 879  * cached before, it will be retured in the given callback; the peer_id is used to lookup in the
 880  * cache. If not a new operation is started to open the transport handle and
 881  * will be given in the callback when it is available.
 882  *
 883  * @param peer_id the index of the peer
 884  * @param cfg the configuration with which the transport handle has to be
 885  *          created if it was not present in the cache
 886  * @param cb the callback to notify when the transport handle is available
 887  * @param cb_cls the closure for the above callback
 888  * @param target the peer identify of the peer whose connection to our TRANSPORT
 889  *          subsystem will be notified through the connect_notify_cb. Can be NULL
 890  * @param connect_notify_cb the callback to call when the given target peer is
 891  *          connected. This callback will only be called once or never again (in
 892  *          case the target peer cannot be connected). Can be NULL
 893  * @param connect_notify_cb_cls the closure for the above callback
 894  * @return the handle which can be used cancel or mark that the handle is no
 895  *           longer being used
 896  */
 897 struct GSTCacheGetHandle *
 898 GST_cache_get_handle_transport (unsigned int peer_id,
 899                                 const struct GNUNET_CONFIGURATION_Handle *cfg,
 900                                 GST_cache_handle_ready_cb cb, void *cb_cls,
 901                                 const struct GNUNET_PeerIdentity *target,
 902                                 GST_cache_peer_connect_notify connect_notify_cb,
 903                                 void *connect_notify_cb_cls);
 904
 905
 906 /**
 907  * Get a CORE handle with the given configuration. If the handle is already
 908  * cached before, it will be retured in the given callback; the peer_id is used
 909  * to lookup in the cache. If the handle is not cached before, a new operation
 910  * is started to open the CORE handle and will be given in the callback when it
 911  * is available along with the peer identity
 912  *
 913  * @param peer_id the index of the peer
 914  * @param cfg the configuration with which the transport handle has to be
 915  *          created if it was not present in the cache
 916  * @param cb the callback to notify when the transport handle is available
 917  * @param cb_cls the closure for the above callback
 918  * @param target the peer identify of the peer whose connection to our CORE
 919  *          subsystem will be notified through the connect_notify_cb. Can be NULL
 920  * @param connect_notify_cb the callback to call when the given target peer is
 921  *          connected. This callback will only be called once or never again (in
 922  *          case the target peer cannot be connected). Can be NULL
 923  * @param connect_notify_cb_cls the closure for the above callback
 924  * @return the handle which can be used cancel or mark that the handle is no
 925  *           longer being used
 926  */
 927 struct GSTCacheGetHandle *
 928 GST_cache_get_handle_core (unsigned int peer_id,
 929                            const struct GNUNET_CONFIGURATION_Handle *cfg,
 930                            GST_cache_handle_ready_cb cb, void *cb_cls,
 931                            const struct GNUNET_PeerIdentity *target,
 932                            GST_cache_peer_connect_notify connect_notify_cb,
 933                            void *connect_notify_cb_cls);
 934
 935
 936 /**
 937  * Mark the GetCacheHandle as being done if a handle has been provided already
 938  * or as being cancelled if the callback for the handle hasn't been called.
 939  *
 940  * @param cgh the CacheGetHandle handle
 941  */
 942 void
 943 GST_cache_get_handle_done (struct GSTCacheGetHandle *cgh);
 944
 945 /* End of gnunet-service-testbed.h */