Give processor_t more control over the lifecycle of a job
[strongswan.git] / src / libcharon / control / controller.h
index 31b69c7..26614af 100644 (file)
 #include <bus/bus.h>
 
 /**
- * callback to log things triggered by controller.
+ * Callback to log things triggered by controller.
  *
- * @param param                        echoed parameter supplied when function invoked
+ * @param param                        parameter supplied when controller method was called
  * @param group                        debugging group
- * @param level                        verbosity level if log
+ * @param level                        verbosity level
  * @param ike_sa               associated IKE_SA, if any
- * @param format               printf like format string
- * @param args                 list of arguments to use for format
- * @return                             FALSE to return from invoked function
+ * @param message              log message
+ * @return                             FALSE to return from called controller method
  */
-typedef bool(*controller_cb_t)(void* param, debug_t group, level_t level,
-                                                          ike_sa_t* ike_sa, char* format, va_list args);
+typedef bool (*controller_cb_t)(void* param, debug_t group, level_t level,
+                                                               ike_sa_t* ike_sa, char* message);
 
 /**
- * Empty callback function for controller_t functions.
+ * Empty callback function for controller_t methods.
  *
  * If you want to do a synchronous call, but don't need a callback, pass
- * this function to the controllers methods.
+ * this function to the controller methods.
  */
 bool controller_cb_empty(void *param, debug_t group, level_t level,
-                                                ike_sa_t *ike_sa, char *format, va_list args);
+                                                ike_sa_t *ike_sa, char *message);
 
 typedef struct controller_t controller_t;
 
@@ -56,7 +55,7 @@ typedef struct controller_t controller_t;
  *
  * Passing NULL as callback to the managers function calls them asynchronously.
  * If a callback is specified, they are called synchronously. There is a default
- * callback "controller_cb_empty" if you wan't to call a function
+ * callback "controller_cb_empty" if you want to call a function
  * synchronously, but don't need a callback.
  */
 struct controller_t {
@@ -65,63 +64,73 @@ struct controller_t {
         * Create an enumerator for all IKE_SAs.
         *
         * The enumerator blocks the IKE_SA manager until it gets destroyed. Do
-        * not call another interface/manager method while the iterator is alive.
+        * not call another interface/manager method while the enumerator is alive.
         *
+        * @param wait                  TRUE to wait for checked out SAs, FALSE to skip
         * @return                              enumerator, locks IKE_SA manager until destroyed
         */
-       enumerator_t* (*create_ike_sa_enumerator)(controller_t *this);
+       enumerator_t* (*create_ike_sa_enumerator)(controller_t *this, bool wait);
 
        /**
         * Initiate a CHILD_SA, and if required, an IKE_SA.
         *
-        * The initiate() 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.
+        * If a callback is provided the function is synchronous and thus blocks
+        * until the IKE_SA is established or failed.
         *
         * @param peer_cfg              peer_cfg to use for IKE_SA setup
         * @param child_cfg             child_cfg to set up CHILD_SA from
         * @param cb                    logging callback
         * @param param                 parameter to include in each call of cb
+        * @param timeout               timeout in ms to wait for callbacks, 0 to disable
         * @return
         *                                              - SUCCESS, if CHILD_SA established
         *                                              - FAILED, if setup failed
         *                                              - NEED_MORE, if callback returned FALSE
+        *                                              - OUT_OF_RES if timed out
         */
        status_t (*initiate)(controller_t *this,
                                                 peer_cfg_t *peer_cfg, child_cfg_t *child_cfg,
-                                                controller_cb_t callback, void *param);
+                                                controller_cb_t callback, void *param, u_int timeout);
 
        /**
         * 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.
+        * If a callback is provided the function is synchronous and thus blocks
+        * until the IKE_SA is properly deleted, or the call timed out.
         *
         * @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
+        * @param timeout               timeout in ms to wait for callbacks, 0 to disable
         * @return
         *                                              - SUCCESS, if CHILD_SA terminated
         *                                              - NOT_FOUND, if no such CHILD_SA found
         *                                              - NEED_MORE, if callback returned FALSE
+        *                                              - OUT_OF_RES if timed out
         */
        status_t (*terminate_ike)(controller_t *this, u_int32_t unique_id,
-                                                         controller_cb_t callback, void *param);
+                                                         controller_cb_t callback, void *param,
+                                                         u_int timeout);
 
        /**
         * Terminate a CHILD_SA.
         *
+        * If a callback is provided the function is synchronous and thus blocks
+        * until the CHILD_SA is properly deleted, or the call timed out.
+        *
         * @param reqid                 reqid of the CHILD_SA to terminate
         * @param cb                    logging callback
         * @param param                 parameter to include in each call of cb
+        * @param timeout               timeout in ms to wait for callbacks, 0 to disable
         * @return
         *                                              - SUCCESS, if CHILD_SA terminated
         *                                              - NOT_FOUND, if no such CHILD_SA found
         *                                              - NEED_MORE, if callback returned FALSE
+        *                                              - OUT_OF_RES if timed out
         */
        status_t (*terminate_child)(controller_t *this, u_int32_t reqid,
-                                                               controller_cb_t callback, void *param);
+                                                               controller_cb_t callback, void *param,
+                                                               u_int timeout);
 
        /**
         * Destroy a controller_t instance.
@@ -129,12 +138,11 @@ struct controller_t {
        void (*destroy) (controller_t *this);
 };
 
-
 /**
  * Creates a controller instance.
  *
  * @return                     controller_t object
  */
-controller_t *controller_create(void);
+controller_t *controller_create();
 
 #endif /** CONTROLLER_H_ @}*/