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 want 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 enumerator 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          * @param timeout               timeout in ms to wait for callbacks, 0 to disable
  87          * @return
  88          *                                              - SUCCESS, if CHILD_SA established
  89          *                                              - FAILED, if setup failed
  90          *                                              - NEED_MORE, if callback returned FALSE
  91          *                                              - OUT_OF_RES if timed out
  92          */
  93         status_t (*initiate)(controller_t *this,
  94                                                  peer_cfg_t *peer_cfg, child_cfg_t *child_cfg,
  95                                                  controller_cb_t callback, void *param, u_int timeout);
  96
  97         /**
  98          * Terminate an IKE_SA and all of its CHILD_SAs.
  99          *
 100          * The terminate() function is synchronous and thus blocks until the
 101          * IKE_SA is properly deleted, or the delete timed out.
 102          * The terminate() function contains a thread cancellation point.
 103          *
 104          * @param unique_id             unique id of the IKE_SA to terminate.
 105          * @param cb                    logging callback
 106          * @param param                 parameter to include in each call of cb
 107          * @param timeout               timeout in ms to wait for callbacks, 0 to disable
 108          * @return
 109          *                                              - SUCCESS, if CHILD_SA terminated
 110          *                                              - NOT_FOUND, if no such CHILD_SA found
 111          *                                              - NEED_MORE, if callback returned FALSE
 112          *                                              - OUT_OF_RES if timed out
 113          */
 114         status_t (*terminate_ike)(controller_t *this, u_int32_t unique_id,
 115                                                           controller_cb_t callback, void *param,
 116                                                           u_int timeout);
 117
 118         /**
 119          * Terminate a CHILD_SA.
 120          *
 121          * @param reqid                 reqid of the CHILD_SA to terminate
 122          * @param cb                    logging callback
 123          * @param param                 parameter to include in each call of cb
 124          * @param timeout               timeout in ms to wait for callbacks, 0 to disable
 125          * @return
 126          *                                              - SUCCESS, if CHILD_SA terminated
 127          *                                              - NOT_FOUND, if no such CHILD_SA found
 128          *                                              - NEED_MORE, if callback returned FALSE
 129          *                                              - OUT_OF_RES if timed out
 130          */
 131         status_t (*terminate_child)(controller_t *this, u_int32_t reqid,
 132                                                                 controller_cb_t callback, void *param,
 133                                                                 u_int timeout);
 134
 135         /**
 136          * Destroy a controller_t instance.
 137          */
 138         void (*destroy) (controller_t *this);
 139 };
 140
 141
 142 /**
 143  * Creates a controller instance.
 144  *
 145  * @return                      controller_t object
 146  */
 147 controller_t *controller_create(void);
 148
 149 #endif /** CONTROLLER_H_ @}*/