gnunet_testbed_service.h

Go to the documentation of this file.

/*
      This file is part of GNUnet
      Copyright (C) 2008--2013 GNUnet e.V.

      GNUnet is free software: you can redistribute it and/or modify it
      under the terms of the GNU Affero General Public License as published
      by the Free Software Foundation, either version 3 of the License,
      or (at your option) any later version.

      GNUnet is distributed in the hope that it will be useful, but
      WITHOUT ANY WARRANTY; without even the implied warranty of
      MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
      Affero General Public License for more details.

      You should have received a copy of the GNU Affero General Public License
      along with this program.  If not, see <http://www.gnu.org/licenses/>.

     SPDX-License-Identifier: AGPL3.0-or-later
 */

#ifndef GNUNET_TESTBED_SERVICE_H
#define GNUNET_TESTBED_SERVICE_H

#include "gnunet_util_lib.h"
#include "gnunet_testing_lib.h"

#ifdef __cplusplus
extern "C"
{
#if 0                           /* keep Emacsens' auto-indent happy */
}
#endif
#endif


struct GNUNET_TESTBED_Host;

struct GNUNET_TESTBED_Peer;

struct GNUNET_TESTBED_Operation;

struct GNUNET_TESTBED_Controller;


struct GNUNET_TESTBED_Host *
GNUNET_TESTBED_host_create (const char *hostname,
                            const char *username,
                            const struct GNUNET_CONFIGURATION_Handle *cfg,
                            uint16_t port);


struct GNUNET_TESTBED_Host *
GNUNET_TESTBED_host_create_with_id (uint32_t id,
                                    const char *hostname,
                                    const char *username,
                                    const struct GNUNET_CONFIGURATION_Handle
                                    *cfg,
                                    uint16_t port);


unsigned int
GNUNET_TESTBED_hosts_load_from_file (const char *filename,
                                     const struct GNUNET_CONFIGURATION_Handle
                                     *cfg,
                                     struct GNUNET_TESTBED_Host ***hosts);


unsigned int
GNUNET_TESTBED_hosts_load_from_loadleveler (const struct
                                            GNUNET_CONFIGURATION_Handle *cfg,
                                            struct GNUNET_TESTBED_Host
                                            ***hosts);

void
GNUNET_TESTBED_host_destroy (struct GNUNET_TESTBED_Host *host);


struct GNUNET_TESTBED_HostHabitableCheckHandle;


typedef void
(*GNUNET_TESTBED_HostHabitableCallback) (void *cls,
                                         const struct GNUNET_TESTBED_Host *host,
                                         int status);


struct GNUNET_TESTBED_HostHabitableCheckHandle *
GNUNET_TESTBED_is_host_habitable (const struct GNUNET_TESTBED_Host *host,
                                  const struct GNUNET_CONFIGURATION_Handle
                                  *config,
                                  GNUNET_TESTBED_HostHabitableCallback cb,
                                  void *cb_cls);


void
GNUNET_TESTBED_is_host_habitable_cancel (struct
                                         GNUNET_TESTBED_HostHabitableCheckHandle
                                         *handle);

const char *
GNUNET_TESTBED_host_get_hostname (const struct GNUNET_TESTBED_Host *host);


enum GNUNET_TESTBED_EventType
{
  GNUNET_TESTBED_ET_PEER_START = 0,

  GNUNET_TESTBED_ET_PEER_STOP = 1,

  GNUNET_TESTBED_ET_CONNECT = 2,

  GNUNET_TESTBED_ET_DISCONNECT = 3,

  GNUNET_TESTBED_ET_OPERATION_FINISHED = 4,
};


enum GNUNET_TESTBED_PeerInformationType
{
  GNUNET_TESTBED_PIT_GENERIC = 0,

  GNUNET_TESTBED_PIT_CONFIGURATION,

  GNUNET_TESTBED_PIT_IDENTITY
};


struct GNUNET_TESTBED_EventInformation
{
  enum GNUNET_TESTBED_EventType type;

  struct GNUNET_TESTBED_Operation *op;

  void *op_cls;

  union
  {
    struct
    {
      struct GNUNET_TESTBED_Host *host;

      struct GNUNET_TESTBED_Peer *peer;
    } peer_start;

    struct
    {
      struct GNUNET_TESTBED_Peer *peer;
    } peer_stop;

    struct
    {
      struct GNUNET_TESTBED_Peer *peer1;

      struct GNUNET_TESTBED_Peer *peer2;
    } peer_connect;

    struct
    {
      struct GNUNET_TESTBED_Peer *peer1;

      struct GNUNET_TESTBED_Peer *peer2;
    } peer_disconnect;

    struct
    {
      const char *emsg;

      void *generic;
    } operation_finished;
  } details;
};


typedef void
(*GNUNET_TESTBED_ControllerCallback)(void *cls,
                                     const struct
                                     GNUNET_TESTBED_EventInformation *event);


struct GNUNET_TESTBED_ControllerProc;


typedef void
(*GNUNET_TESTBED_ControllerStatusCallback) (void *cls,
                                            const struct
                                            GNUNET_CONFIGURATION_Handle *cfg,
                                            int status);


struct GNUNET_TESTBED_ControllerProc *
GNUNET_TESTBED_controller_start (const char *trusted_ip,
                                 struct GNUNET_TESTBED_Host *host,
                                 GNUNET_TESTBED_ControllerStatusCallback cb,
                                 void *cls);


void
GNUNET_TESTBED_controller_stop (struct GNUNET_TESTBED_ControllerProc *cproc);


struct GNUNET_TESTBED_Controller *
GNUNET_TESTBED_controller_connect (struct GNUNET_TESTBED_Host *host,
                                   uint64_t event_mask,
                                   GNUNET_TESTBED_ControllerCallback cc,
                                   void *cc_cls);


void
GNUNET_TESTBED_controller_disconnect (struct GNUNET_TESTBED_Controller *c);


struct GNUNET_TESTBED_HostRegistrationHandle;


typedef void
(*GNUNET_TESTBED_HostRegistrationCompletion) (void *cls,
                                              const char *emsg);


struct GNUNET_TESTBED_HostRegistrationHandle *
GNUNET_TESTBED_register_host (struct GNUNET_TESTBED_Controller *controller,
                              struct GNUNET_TESTBED_Host *host,
                              GNUNET_TESTBED_HostRegistrationCompletion cc,
                              void *cc_cls);


void
GNUNET_TESTBED_cancel_registration (struct GNUNET_TESTBED_HostRegistrationHandle
                                    *handle);


typedef void
(*GNUNET_TESTBED_OperationCompletionCallback) (void *cls,
                                               struct GNUNET_TESTBED_Operation *
                                               op,
                                               const char *emsg);


struct GNUNET_TESTBED_Operation *
GNUNET_TESTBED_controller_link (void *op_cls,
                                struct GNUNET_TESTBED_Controller *master,
                                struct GNUNET_TESTBED_Host *delegated_host,
                                struct GNUNET_TESTBED_Host *slave_host,
                                int is_subordinate);


struct GNUNET_TESTBED_Operation *
GNUNET_TESTBED_get_slave_config (void *op_cls,
                                 struct GNUNET_TESTBED_Controller *master,
                                 struct GNUNET_TESTBED_Host *slave_host);


typedef void
(*GNUNET_TESTBED_PeerCreateCallback) (void *cls,
                                      struct GNUNET_TESTBED_Peer *peer,
                                      const char *emsg);


struct GNUNET_TESTBED_Operation *
GNUNET_TESTBED_peer_create (struct GNUNET_TESTBED_Controller *controller,
                            struct GNUNET_TESTBED_Host *host,
                            const struct GNUNET_CONFIGURATION_Handle *cfg,
                            GNUNET_TESTBED_PeerCreateCallback cb,
                            void *cls);


typedef void
(*GNUNET_TESTBED_PeerChurnCallback) (void *cls,
                                     const char *emsg);


struct GNUNET_TESTBED_Operation *
GNUNET_TESTBED_peer_start (void *op_cls,
                           struct GNUNET_TESTBED_Peer *peer,
                           GNUNET_TESTBED_PeerChurnCallback pcc,
                           void *pcc_cls);


struct GNUNET_TESTBED_Operation *
GNUNET_TESTBED_peer_stop (void *op_cls,
                          struct GNUNET_TESTBED_Peer *peer,
                          GNUNET_TESTBED_PeerChurnCallback pcc,
                          void *pcc_cls);


struct GNUNET_TESTBED_PeerInformation
{
  enum GNUNET_TESTBED_PeerInformationType pit;

  union
  {
    struct GNUNET_CONFIGURATION_Handle *cfg;

    struct GNUNET_PeerIdentity *id;
  } result;
};


typedef void
(*GNUNET_TESTBED_PeerInfoCallback) (void *cb_cls,
                                    struct GNUNET_TESTBED_Operation *op,
                                    const struct
                                    GNUNET_TESTBED_PeerInformation *pinfo,
                                    const char *emsg);


struct GNUNET_TESTBED_Operation *
GNUNET_TESTBED_peer_get_information (struct GNUNET_TESTBED_Peer *peer,
                                     enum GNUNET_TESTBED_PeerInformationType
                                     pit,
                                     GNUNET_TESTBED_PeerInfoCallback cb,
                                     void *cb_cls);


struct GNUNET_TESTBED_Operation *
GNUNET_TESTBED_peer_update_configuration (struct GNUNET_TESTBED_Peer *peer,
                                          const struct
                                          GNUNET_CONFIGURATION_Handle *cfg);


struct GNUNET_TESTBED_Operation *
GNUNET_TESTBED_peer_destroy (struct GNUNET_TESTBED_Peer *peer);


struct GNUNET_TESTBED_Operation *
GNUNET_TESTBED_peer_manage_service (void *op_cls,
                                    struct GNUNET_TESTBED_Peer *peer,
                                    const char *service_name,
                                    GNUNET_TESTBED_OperationCompletionCallback
                                    cb,
                                    void *cb_cls,
                                    unsigned int start);


struct GNUNET_TESTBED_Operation *
GNUNET_TESTBED_shutdown_peers (struct GNUNET_TESTBED_Controller *c,
                               void *op_cls,
                               GNUNET_TESTBED_OperationCompletionCallback cb,
                               void *cb_cls);


enum GNUNET_TESTBED_ConnectOption
{
  GNUNET_TESTBED_CO_NONE = 0,

  GNUNET_TESTBED_CO_ALLOW = 1,

};


struct GNUNET_TESTBED_Operation *
GNUNET_TESTBED_underlay_configure_link_va (void *op_cls,
                                           struct GNUNET_TESTBED_Peer *p1,
                                           struct GNUNET_TESTBED_Peer *p2,
                                           enum GNUNET_TESTBED_ConnectOption co,
                                           va_list ap);


struct GNUNET_TESTBED_Operation *
GNUNET_TESTBED_underlay_configure_link (void *op_cls,
                                        struct GNUNET_TESTBED_Peer *p1,
                                        struct GNUNET_TESTBED_Peer *p2,
                                        enum GNUNET_TESTBED_ConnectOption co,
                                        ...);


enum GNUNET_TESTBED_TopologyOption
{
  GNUNET_TESTBED_TOPOLOGY_CLIQUE,

  GNUNET_TESTBED_TOPOLOGY_SMALL_WORLD,

  GNUNET_TESTBED_TOPOLOGY_SMALL_WORLD_RING,

  GNUNET_TESTBED_TOPOLOGY_RING,

  GNUNET_TESTBED_TOPOLOGY_STAR,

  GNUNET_TESTBED_TOPOLOGY_2D_TORUS,

  GNUNET_TESTBED_TOPOLOGY_ERDOS_RENYI,

  GNUNET_TESTBED_TOPOLOGY_INTERNAT,

  GNUNET_TESTBED_TOPOLOGY_SCALE_FREE,

  GNUNET_TESTBED_TOPOLOGY_LINE,

  GNUNET_TESTBED_TOPOLOGY_FROM_FILE,

  GNUNET_TESTBED_TOPOLOGY_NONE,

  GNUNET_TESTBED_TOPOLOGY_OPTION_END,

  /* The following are not topologies but influence how the topology has to be
     setup. These options should follow the topology specific options (if
     required by the chosen topology). Note that these should be given before
     GNUNET_TESTBED_TOPOLOGY_OPTION_END */

  GNUNET_TESTBED_TOPOLOGY_RETRY_CNT
};


struct GNUNET_TESTBED_Operation *
GNUNET_TESTBED_underlay_configure_topology_va (void *op_cls,
                                               unsigned int num_peers,
                                               struct GNUNET_TESTBED_Peer **
                                               peers,
                                               enum
                                               GNUNET_TESTBED_TopologyOption
                                               topo,
                                               va_list ap);


struct GNUNET_TESTBED_Operation *
GNUNET_TESTBED_underlay_configure_topology (void *op_cls,
                                            unsigned int num_peers,
                                            struct GNUNET_TESTBED_Peer **peers,
                                            enum GNUNET_TESTBED_TopologyOption
                                            topo,
                                            ...);


struct GNUNET_TESTBED_Operation *
GNUNET_TESTBED_overlay_connect (void *op_cls,
                                GNUNET_TESTBED_OperationCompletionCallback cb,
                                void *cb_cls,
                                struct GNUNET_TESTBED_Peer *p1,
                                struct GNUNET_TESTBED_Peer *p2);


typedef void (*GNUNET_TESTBED_TopologyCompletionCallback) (void *cls,
                                                           unsigned int
                                                           nsuccess,
                                                           unsigned int
                                                           nfailures);


struct GNUNET_TESTBED_Operation *
GNUNET_TESTBED_overlay_configure_topology_va (void *op_cls,
                                              unsigned int num_peers,
                                              struct GNUNET_TESTBED_Peer **peers,
                                              unsigned int *max_connections,
                                              GNUNET_TESTBED_TopologyCompletionCallback
                                              comp_cb,
                                              void *comp_cb_cls,
                                              enum GNUNET_TESTBED_TopologyOption
                                              topo,
                                              va_list va);


struct GNUNET_TESTBED_Operation *
GNUNET_TESTBED_overlay_configure_topology (void *op_cls,
                                           unsigned int num_peers,
                                           struct GNUNET_TESTBED_Peer **peers,
                                           unsigned int *max_connections,
                                           GNUNET_TESTBED_TopologyCompletionCallback
                                           comp_cb,
                                           void *comp_cb_cls,
                                           enum GNUNET_TESTBED_TopologyOption
                                           topo,
                                           ...);


void
GNUNET_TESTBED_overlay_write_topology_to_file (struct
                                               GNUNET_TESTBED_Controller *
                                               controller,
                                               const char *filename);


typedef void *
(*GNUNET_TESTBED_ConnectAdapter)(void *cls,
                                 const struct GNUNET_CONFIGURATION_Handle *cfg);


typedef void
(*GNUNET_TESTBED_DisconnectAdapter)(void *cls,
                                    void *op_result);


typedef void
(*GNUNET_TESTBED_ServiceConnectCompletionCallback) (void *cls,
                                                    struct
                                                    GNUNET_TESTBED_Operation *op,
                                                    void *ca_result,
                                                    const char *emsg);


struct GNUNET_TESTBED_Operation *
GNUNET_TESTBED_service_connect (void *op_cls,
                                struct GNUNET_TESTBED_Peer *peer,
                                const char *service_name,
                                GNUNET_TESTBED_ServiceConnectCompletionCallback
                                cb,
                                void *cb_cls,
                                GNUNET_TESTBED_ConnectAdapter ca,
                                GNUNET_TESTBED_DisconnectAdapter da,
                                void *cada_cls);


void
GNUNET_TESTBED_operation_done (struct GNUNET_TESTBED_Operation *operation);


typedef int
(*GNUNET_TESTBED_StatisticsIterator) (void *cls,
                                      const struct GNUNET_TESTBED_Peer *peer,
                                      const char *subsystem,
                                      const char *name,
                                      uint64_t value,
                                      int is_persistent);


struct GNUNET_TESTBED_Operation *
GNUNET_TESTBED_get_statistics (unsigned int num_peers,
                               struct GNUNET_TESTBED_Peer **peers,
                               const char *subsystem, const char *name,
                               GNUNET_TESTBED_StatisticsIterator proc,
                               GNUNET_TESTBED_OperationCompletionCallback cont,
                               void *cls);


uint32_t
GNUNET_TESTBED_get_index (const struct GNUNET_TESTBED_Peer *peer);


struct GNUNET_TESTBED_RunHandle;


typedef void
(*GNUNET_TESTBED_TestMaster)(void *cls,
                             struct GNUNET_TESTBED_RunHandle *h,
                             unsigned int num_peers,
                             struct GNUNET_TESTBED_Peer **peers,
                             unsigned int links_succeeded,
                             unsigned int links_failed);


void
GNUNET_TESTBED_run (const char *host_filename,
                    const struct GNUNET_CONFIGURATION_Handle *cfg,
                    unsigned int num_peers,
                    uint64_t event_mask,
                    GNUNET_TESTBED_ControllerCallback cc,
                    void *cc_cls,
                    GNUNET_TESTBED_TestMaster test_master,
                    void *test_master_cls);


int
GNUNET_TESTBED_test_run (const char *testname,
                         const char *cfg_filename,
                         unsigned int num_peers,
                         uint64_t event_mask,
                         GNUNET_TESTBED_ControllerCallback cc,
                         void *cc_cls,
                         GNUNET_TESTBED_TestMaster test_master,
                         void *test_master_cls);


struct GNUNET_TESTBED_Controller *
GNUNET_TESTBED_run_get_controller_handle (struct GNUNET_TESTBED_RunHandle *h);


struct GNUNET_TESTBED_Barrier;


enum GNUNET_TESTBED_BarrierStatus
{
  GNUNET_TESTBED_BARRIERSTATUS_INITIALISED = 1,

  GNUNET_TESTBED_BARRIERSTATUS_CROSSED,

  GNUNET_TESTBED_BARRIERSTATUS_ERROR,
};


typedef void
(*GNUNET_TESTBED_barrier_status_cb) (void *cls,
                                     const char *name,
                                     struct GNUNET_TESTBED_Barrier *barrier,
                                     enum GNUNET_TESTBED_BarrierStatus status,
                                     const char *emsg);


struct GNUNET_TESTBED_Barrier *
GNUNET_TESTBED_barrier_init (struct GNUNET_TESTBED_Controller *controller,
                             const char *name,
                             unsigned int quorum,
                             GNUNET_TESTBED_barrier_status_cb cb,
                             void *cb_cls);


void
GNUNET_TESTBED_barrier_cancel (struct GNUNET_TESTBED_Barrier *barrier);


struct GNUNET_TESTBED_BarrierWaitHandle;


typedef void
(*GNUNET_TESTBED_barrier_wait_cb) (void *cls,
                                   const char *name,
                                   int status);


struct GNUNET_TESTBED_BarrierWaitHandle *
GNUNET_TESTBED_barrier_wait (const char *name,
                             GNUNET_TESTBED_barrier_wait_cb cb,
                             void *cls);


void
GNUNET_TESTBED_barrier_wait_cancel (struct GNUNET_TESTBED_BarrierWaitHandle *h);


struct GNUNET_TESTBED_UnderlayLinkModel;


enum GNUNET_TESTBED_UnderlayLinkModelType
{
  GNUNET_TESTBED_UNDERLAYLINKMODELTYPE_BLACKLIST,

  GNUNET_TESTBED_UNDERLAYLINKMODELTYPE_WHITELIST
};


struct GNUNET_TESTBED_UnderlayLinkModel *
GNUNET_TESTBED_underlaylinkmodel_create (struct GNUNET_TESTBED_Peer *peer,
                                         enum
                                         GNUNET_TESTBED_UnderlayLinkModelType
                                         type);


void
GNUNET_TESTBED_underlaylinkmodel_add_peer (struct
                                           GNUNET_TESTBED_UnderlayLinkModel *
                                           model,
                                           struct GNUNET_TESTBED_Peer *peer);


void
GNUNET_TESTBED_underlaylinkmodel_set_link (struct
                                           GNUNET_TESTBED_UnderlayLinkModel *
                                           model,
                                           struct GNUNET_TESTBED_Peer *peer,
                                           uint32_t latency,
                                           uint32_t loss,
                                           uint32_t bandwidth);


void
GNUNET_TESTBED_underlaylinkmodel_commit (struct
                                         GNUNET_TESTBED_UnderlayLinkModel *model);


void
GNUNET_TESTBED_underlaylinkmodel_free (struct
                                       GNUNET_TESTBED_UnderlayLinkModel *model);


#if 0                           /* keep Emacsens' auto-indent happy */
{
#endif


#ifdef __cplusplus
}
#endif

#endif
  /* end of group */