fixed bad cast which resulted in a crash on "ipsec update"
[strongswan.git] / src / charon / control / interface_manager.h
index 57121c8..3ee1f0e 100644 (file)
@@ -26,7 +26,7 @@
 #include <bus/bus.h>
 
 /**
- * callback to log things triggered by interface_manager
+ * callback to log things triggered by interface_manager.
  *
  * @param param                        echoed parameter supplied when function invoked
  * @param signal               type of signal
 typedef bool(*interface_manager_cb_t)(void* param, signal_t signal, level_t level,
                                                           ike_sa_t* ike_sa, char* format, va_list args);
 
+/**
+ * @brief Empty callback function for interface_manager_t functions.
+ *
+ * If you wan't to do a syncrhonous call, but don't need a callback, pass
+ * this function to the interface_managers methods.
+ */
+bool interface_manager_cb_empty(void *param, signal_t signal, level_t level,
+                                                               ike_sa_t *ike_sa, char *format, va_list args);
+
 typedef struct interface_manager_t interface_manager_t;
 
 /**
- * @brief The interface_manager controls the daemon.
+ * @brief The interface_manager loads control interfaces and has helper methods.
  *
+ * One job of the interface manager is to load pluggable control interface
+ * modules, implemented as interface_t.
+ * @verbatim
+
+   +---------+      +------------+         +--------------+     |
+   |         |      |            |<----- +--------------+ |     |
+   | daemon  |<-----| interface- |     +--------------+ |-+  <==|==> IPC
+   |  core   |      | manager    |<----|  interfaces  |-+       |
+   |         |<-----|            |     +--------------+         |
+   |         |      |            |                              |
+   +---------+      +------------+                              |
+
+   @endverbatim
+ * The manager does not really use the interfaces, instead, the interface
+ * use the manager to fullfill their tasks (initiating, terminating, ...). 
  * The interface_manager starts actions by creating jobs. It then tries to
  * evaluate the result of the operation by listening on the bus.
+ *
+ * Passing NULL as callback to the managers function calls them asynchronously.
+ * If a callback is specified, they are called synchronoulsy. There is a default
+ * callback "interface_manager_cb_empty" if you wan't to call a function
+ * synchronously, but don't need a callback.
  * 
  * @b Constructors:
  * - interface_manager_create()
@@ -56,8 +85,23 @@ typedef struct interface_manager_t interface_manager_t;
 struct interface_manager_t {
 
        /**
+        * @brief Create an iterator for all IKE_SAs.
+        *
+        * The iterator blocks the IKE_SA manager until it gets destroyed. Do
+        * not call another interface/manager method while the iterator is alive.
+        *
+        * @param this                  calling object
+        * @return                              iterator, locks IKE_SA manager until destroyed
+        */
+       iterator_t* (*create_ike_sa_iterator)(interface_manager_t *this);
+
+       /**
         * @brief Initiate a CHILD_SA, and if required, an IKE_SA.
         *
+        * The inititate() function is synchronous and thus blocks until the
+        * IKE_SA is established or failed. Because of this, the initiate() function
+        * contains a thread cancellation point.
+        *
         * @param this                  calling object
         * @param peer_cfg              peer_cfg to use for IKE_SA setup
         * @param child_cfg             child_cfg to set up CHILD_SA from
@@ -71,6 +115,74 @@ struct interface_manager_t {
        status_t (*initiate)(interface_manager_t *this,
                                                 peer_cfg_t *peer_cfg, child_cfg_t *child_cfg,
                                                 interface_manager_cb_t callback, void *param);
+
+       /**
+        * @brief Terminate an IKE_SA and all of its CHILD_SAs.
+        *
+        * The terminate() function is synchronous and thus blocks until the
+        * IKE_SA is properly deleted, or the delete timed out. 
+        * The terminate() function contains a thread cancellation point.
+        *
+        * @param this                  calling object
+        * @param unique_id             unique id of the IKE_SA to terminate.
+        * @param cb                    logging callback
+        * @param param                 parameter to include in each call of cb
+        * @return
+        *                                              - SUCCESS, if CHILD_SA terminated
+        *                                              - NOT_FOUND, if no such CHILD_SA found
+        *                                              - NEED_MORE, if callback returned FALSE
+        */
+       status_t (*terminate_ike)(interface_manager_t *this, u_int32_t unique_id, 
+                                                         interface_manager_cb_t callback, void *param);
+       
+       /**
+        * @brief Terminate a CHILD_SA.
+        *
+        * @param this                  calling object
+        * @param reqid                 reqid of the CHILD_SA to terminate
+        * @param cb                    logging callback
+        * @param param                 parameter to include in each call of cb
+        * @return
+        *                                              - SUCCESS, if CHILD_SA terminated
+        *                                              - NOT_FOUND, if no such CHILD_SA found
+        *                                              - NEED_MORE, if callback returned FALSE
+        */
+       status_t (*terminate_child)(interface_manager_t *this, u_int32_t reqid, 
+                                                               interface_manager_cb_t callback, void *param);
+       
+       /**
+        * @brief Route a CHILD_SA (install triggering policies).
+        *
+        * @param this                  calling object
+        * @param peer_cfg              peer_cfg to use for IKE_SA setup, if triggered
+        * @param child_cfg             child_cfg to route
+        * @param cb                    logging callback
+        * @param param                 parameter to include in each call of cb
+        * @return
+        *                                              - SUCCESS, if CHILD_SA routed
+        *                                              - FAILED, if routing failed
+        *                                              - NEED_MORE, if callback returned FALSE
+        */
+       status_t (*route)(interface_manager_t *this,
+                                         peer_cfg_t *peer_cfg, child_cfg_t *child_cfg,
+                                         interface_manager_cb_t callback, void *param);
+       
+       /**
+        * @brief Unroute a routed CHILD_SA (uninstall triggering policies).
+        *
+        * Only the route is removed, not the CHILD_SAs the route triggered.
+        *
+        * @param this                  calling object
+        * @param reqid                 reqid of the CHILD_SA to unroute
+        * @param cb                    logging callback
+        * @param param                 parameter to include in each call of cb
+        * @return
+        *                                              - SUCCESS, if CHILD_SA terminated
+        *                                              - NOT_FOUND, if no such CHILD_SA routed
+        *                                              - NEED_MORE, if callback returned FALSE
+        */
+       status_t (*unroute)(interface_manager_t *this, u_int32_t reqid, 
+                                               interface_manager_cb_t callback, void *param);
        
        /**
         * @brief Destroy a interface_manager_t instance.
@@ -82,7 +194,7 @@ struct interface_manager_t {
 
 
 /**
- * @brief Create a interface_manager instance and loads all interface modules.
+ * @brief Creates a interface_manager instance and loads all interface modules.
  * 
  * @return                     interface_manager_t object
  *