src/charon/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  * $Id$
  16  */
  17
  18 /**
  19  * @defgroup controller_i controller
  20  * @{ @ingroup control
  21  */
  22
  23 #ifndef CONTROLLER_H_
  24 #define CONTROLLER_H_
  25
  26 #include <bus/bus.h>
  27
  28 /**
  29  * callback to log things triggered by controller.
  30  *
  31  * @param param                 echoed parameter supplied when function invoked
  32  * @param signal                type of signal
  33  * @param level                 verbosity level if log
  34  * @param ike_sa                associated IKE_SA, if any
  35  * @param format                printf like format string
  36  * @param args                  list of arguments to use for format
  37  * @return                              FALSE to return from invoked function
  38  */
  39 typedef bool(*controller_cb_t)(void* param, signal_t signal, level_t level,
  40                                                            ike_sa_t* ike_sa, char* format, va_list args);
  41
  42 /**
  43  * Empty callback function for controller_t functions.
  44  *
  45  * If you wan't to do a syncrhonous call, but don't need a callback, pass
  46  * this function to the controllers methods.
  47  */
  48 bool controller_cb_empty(void *param, signal_t signal, level_t level,
  49                                                                 ike_sa_t *ike_sa, char *format, va_list args);
  50
  51 typedef struct controller_t controller_t;
  52
  53 /**
  54  * The controller provides a simple interface to run actions.
  55  *
  56  * The controller starts actions by creating jobs. It then tries to
  57  * evaluate the result of the operation by listening on the bus.
  58  *
  59  * Passing NULL as callback to the managers function calls them asynchronously.
  60  * If a callback is specified, they are called synchronoulsy. There is a default
  61  * callback "controller_cb_empty" if you wan't to call a function
  62  * synchronously, but don't need a callback.
  63  */
  64 struct controller_t {
  65
  66         /**
  67          * Create an enumerator for all IKE_SAs.
  68          *
  69          * The enumerator blocks the IKE_SA manager until it gets destroyed. Do
  70          * not call another interface/manager method while the iterator is alive.
  71          *
  72          * @return                              enumerator, locks IKE_SA manager until destroyed
  73          */
  74         enumerator_t* (*create_ike_sa_enumerator)(controller_t *this);
  75
  76         /**
  77          * Initiate a CHILD_SA, and if required, an IKE_SA.
  78          *
  79          * The inititate() function is synchronous and thus blocks until the
  80          * IKE_SA is established or failed. Because of this, the initiate() function
  81          * contains a thread cancellation point.
  82          *
  83          * @param peer_cfg              peer_cfg to use for IKE_SA setup
  84          * @param child_cfg             child_cfg to set up CHILD_SA from
  85          * @param cb                    logging callback
  86          * @param param                 parameter to include in each call of cb
  87          * @return
  88          *                                              - SUCCESS, if CHILD_SA established
  89          *                                              - FAILED, if setup failed
  90          *                                              - NEED_MORE, if callback returned FALSE
  91          */
  92         status_t (*initiate)(controller_t *this,
  93                                                  peer_cfg_t *peer_cfg, child_cfg_t *child_cfg,
  94                                                  controller_cb_t callback, void *param);
  95
  96         /**
  97          * Terminate an IKE_SA and all of its CHILD_SAs.
  98          *
  99          * The terminate() function is synchronous and thus blocks until the
 100          * IKE_SA is properly deleted, or the delete timed out.
 101          * The terminate() function contains a thread cancellation point.
 102          *
 103          * @param unique_id             unique id of the IKE_SA to terminate.
 104          * @param cb                    logging callback
 105          * @param param                 parameter to include in each call of cb
 106          * @return
 107          *                                              - SUCCESS, if CHILD_SA terminated
 108          *                                              - NOT_FOUND, if no such CHILD_SA found
 109          *                                              - NEED_MORE, if callback returned FALSE
 110          */
 111         status_t (*terminate_ike)(controller_t *this, u_int32_t unique_id,
 112                                                           controller_cb_t callback, void *param);
 113
 114         /**
 115          * Terminate a CHILD_SA.
 116          *
 117          * @param reqid                 reqid of the CHILD_SA to terminate
 118          * @param cb                    logging callback
 119          * @param param                 parameter to include in each call of cb
 120          * @return
 121          *                                              - SUCCESS, if CHILD_SA terminated
 122          *                                              - NOT_FOUND, if no such CHILD_SA found
 123          *                                              - NEED_MORE, if callback returned FALSE
 124          */
 125         status_t (*terminate_child)(controller_t *this, u_int32_t reqid,
 126                                                                 controller_cb_t callback, void *param);
 127
 128         /**
 129          * Route a CHILD_SA (install triggering policies).
 130          *
 131          * @param peer_cfg              peer_cfg to use for IKE_SA setup, if triggered
 132          * @param child_cfg             child_cfg to route
 133          * @param cb                    logging callback
 134          * @param param                 parameter to include in each call of cb
 135          * @return
 136          *                                              - SUCCESS, if CHILD_SA routed
 137          *                                              - FAILED, if routing failed
 138          *                                              - NEED_MORE, if callback returned FALSE
 139          */
 140         status_t (*route)(controller_t *this,
 141                                           peer_cfg_t *peer_cfg, child_cfg_t *child_cfg,
 142                                           controller_cb_t callback, void *param);
 143
 144         /**
 145          * Unroute a routed CHILD_SA (uninstall triggering policies).
 146          *
 147          * Only the route is removed, not the CHILD_SAs the route triggered.
 148          *
 149          * @param reqid                 reqid of the CHILD_SA to unroute
 150          * @param cb                    logging callback
 151          * @param param                 parameter to include in each call of cb
 152          * @return
 153          *                                              - SUCCESS, if CHILD_SA terminated
 154          *                                              - NOT_FOUND, if no such CHILD_SA routed
 155          *                                              - NEED_MORE, if callback returned FALSE
 156          */
 157         status_t (*unroute)(controller_t *this, u_int32_t reqid,
 158                                                 controller_cb_t callback, void *param);
 159
 160         /**
 161          * Destroy a controller_t instance.
 162          */
 163         void (*destroy) (controller_t *this);
 164 };
 165
 166
 167 /**
 168  * Creates a controller instance.
 169  *
 170  * @return                      controller_t object
 171  */
 172 controller_t *controller_create(void);
 173
 174 #endif /* CONTROLLER_H_ @} */