src/libcharon/control/controller.h

   1 /*
   2  * Copyright (C) 2007 Martin Willi
   3  * Hochschule fuer Technik Rapperswil
   4  *
   5  * This program is free software; you can redistribute it and/or modify it
   6  * under the terms of the GNU General Public License as published by the
   7  * Free Software Foundation; either version 2 of the License, or (at your
   8  * option) any later version.  See <http://www.fsf.org/copyleft/gpl.txt>.
   9  *
  10  * This program is distributed in the hope that it will be useful, but
  11  * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
  12  * or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  13  * for more details.
  14  */
  15
  16 /**
  17  * @defgroup controller_i controller
  18  * @{ @ingroup control
  19  */
  20
  21 #ifndef CONTROLLER_H_
  22 #define CONTROLLER_H_
  23
  24 #include <bus/bus.h>
  25
  26 /**
  27  * callback to log things triggered by controller.
  28  *
  29  * @param param                 echoed parameter supplied when function invoked
  30  * @param group                 debugging group
  31  * @param level                 verbosity level if log
  32  * @param ike_sa                associated IKE_SA, if any
  33  * @param format                printf like format string
  34  * @param args                  list of arguments to use for format
  35  * @return                              FALSE to return from invoked function
  36  */
  37 typedef bool(*controller_cb_t)(void* param, debug_t group, level_t level,
  38                                                            ike_sa_t* ike_sa, char* format, va_list args);
  39
  40 /**
  41  * Empty callback function for controller_t functions.
  42  *
  43  * If you want to do a synchronous call, but don't need a callback, pass
  44  * this function to the controllers methods.
  45  */
  46 bool controller_cb_empty(void *param, debug_t group, level_t level,
  47                                                  ike_sa_t *ike_sa, char *format, va_list args);
  48
  49 typedef struct controller_t controller_t;
  50
  51 /**
  52  * The controller provides a simple interface to run actions.
  53  *
  54  * The controller starts actions by creating jobs. It then tries to
  55  * evaluate the result of the operation by listening on the bus.
  56  *
  57  * Passing NULL as callback to the managers function calls them asynchronously.
  58  * If a callback is specified, they are called synchronously. There is a default
  59  * callback "controller_cb_empty" if you wan't to call a function
  60  * synchronously, but don't need a callback.
  61  */
  62 struct controller_t {
  63
  64         /**
  65          * Create an enumerator for all IKE_SAs.
  66          *
  67          * The enumerator blocks the IKE_SA manager until it gets destroyed. Do
  68          * not call another interface/manager method while the iterator is alive.
  69          *
  70          * @param wait                  TRUE to wait for checked out SAs, FALSE to skip
  71          * @return                              enumerator, locks IKE_SA manager until destroyed
  72          */
  73         enumerator_t* (*create_ike_sa_enumerator)(controller_t *this, bool wait);
  74
  75         /**
  76          * Initiate a CHILD_SA, and if required, an IKE_SA.
  77          *
  78          * The initiate() function is synchronous and thus blocks until the
  79          * IKE_SA is established or failed. Because of this, the initiate() function
  80          * contains a thread cancellation point.
  81          *
  82          * @param peer_cfg              peer_cfg to use for IKE_SA setup
  83          * @param child_cfg             child_cfg to set up CHILD_SA from
  84          * @param cb                    logging callback
  85          * @param param                 parameter to include in each call of cb
  86          * @return
  87          *                                              - SUCCESS, if CHILD_SA established
  88          *                                              - FAILED, if setup failed
  89          *                                              - NEED_MORE, if callback returned FALSE
  90          */
  91         status_t (*initiate)(controller_t *this,
  92                                                  peer_cfg_t *peer_cfg, child_cfg_t *child_cfg,
  93                                                  controller_cb_t callback, void *param);
  94
  95         /**
  96          * Terminate an IKE_SA and all of its CHILD_SAs.
  97          *
  98          * The terminate() function is synchronous and thus blocks until the
  99          * IKE_SA is properly deleted, or the delete timed out.
 100          * The terminate() function contains a thread cancellation point.
 101          *
 102          * @param unique_id             unique id of the IKE_SA to terminate.
 103          * @param cb                    logging callback
 104          * @param param                 parameter to include in each call of cb
 105          * @return
 106          *                                              - SUCCESS, if CHILD_SA terminated
 107          *                                              - NOT_FOUND, if no such CHILD_SA found
 108          *                                              - NEED_MORE, if callback returned FALSE
 109          */
 110         status_t (*terminate_ike)(controller_t *this, u_int32_t unique_id,
 111                                                           controller_cb_t callback, void *param);
 112
 113         /**
 114          * Terminate a CHILD_SA.
 115          *
 116          * @param reqid                 reqid of the CHILD_SA to terminate
 117          * @param cb                    logging callback
 118          * @param param                 parameter to include in each call of cb
 119          * @return
 120          *                                              - SUCCESS, if CHILD_SA terminated
 121          *                                              - NOT_FOUND, if no such CHILD_SA found
 122          *                                              - NEED_MORE, if callback returned FALSE
 123          */
 124         status_t (*terminate_child)(controller_t *this, u_int32_t reqid,
 125                                                                 controller_cb_t callback, void *param);
 126
 127         /**
 128          * Destroy a controller_t instance.
 129          */
 130         void (*destroy) (controller_t *this);
 131 };
 132
 133
 134 /**
 135  * Creates a controller instance.
 136  *
 137  * @return                      controller_t object
 138  */
 139 controller_t *controller_create(void);
 140
 141 #endif /** CONTROLLER_H_ @}*/