- finish functionality of ike_sa_manager

- tested

Source/charon/ike_sa_manager.h

@@ -34,31 +34,81 @@
  * the manager, and checked back in after usage. 
  * The manager also handles deletion of SAs.
  * 
+ * @todo checking of double-checkouts from the same threads would be nice.
+ * This could be by comparing thread-ids via pthread_self()...
+ * 
  */
 typedef struct ike_sa_manager_s ike_sa_manager_t;
 struct ike_sa_manager_s {
-
-	status_t (*checkout_ike_sa) (ike_sa_manager_t*, ike_sa_id_t *sa_id, ike_sa_t **ike_sa);
-	status_t (*checkin_ike_sa) (ike_sa_manager_t*, ike_sa_t *ike_sa);
-	status_t (*delete_ike_sa_by_id) (ike_sa_manager_t*, ike_sa_id_t *ike_sa_id);
-	status_t (*delete_ike_sa_by_sa) (ike_sa_manager_t*, ike_sa_t *ike_sa);
+	/**
+	 * @brief Checkout an IKE_SA, create it when necesarry
+	 * 
+	 * Checks out a SA by its ID. An SA will be created, when:
+	 * - Responder SPI is not set (when received an IKE_SA_INIT from initiator)
+	 * - Both SPIs are not set (for initiating IKE_SA_INIT)
+	 * Management of SPIs is the managers job, he will set it.
+	 * This function blocks until SA is available for checkout.
+	 * 
+	 * @warning checking out two times without checking in will
+	 * result in a deadlock!
+	 * 
+	 * @param ike_sa_manager 	the manager object
+	 * @param ike_sa_id[in/out]	the SA identifier, will be updated
+	 * @param ike_sa[out] 		checked out SA
+	 * @returns 				SUCCESS if checkout successful
+	 * 							NOT_FOUND when no such SA is available
+	 */
+	status_t (*checkout) (ike_sa_manager_t* ike_sa_manager, ike_sa_id_t *sa_id, ike_sa_t **ike_sa);
+	/**
+	 * @brief Checkin the SA after usage
+	 * 
+	 * @warning the pointer MUST NOT be used after checkin! The SA must be checked
+	 * out again!
+	 *  
+	 * @param ike_sa_manager 	the manager object
+	 * @param ike_sa_id[in/out]	the SA identifier, will be updated
+	 * @param ike_sa[out]		checked out SA
+	 * @returns 				SUCCESS if checked in
+	 * 							NOT_FOUND when not found (shouldn't happen!)
+	 */
+	status_t (*checkin) (ike_sa_manager_t* ike_sa_manager, ike_sa_t *ike_sa);
+	/**
+	 * @brief delete a SA, wich was not checked out
+	 * 
+	 * @warning do not use this when the SA is already checked out, this will
+	 * deadlock!
+	 *  
+	 * @param ike_sa_manager 	the manager object
+	 * @param ike_sa_id[in/out]	the SA identifier
+	 * @returns 				SUCCESS if found
+	 * 							NOT_FOUND when no such SA is available
+	 */
+	status_t (*delete) (ike_sa_manager_t* ike_sa_manager, ike_sa_id_t *ike_sa_id);
+	/**
+	 * @brief delete a checked out SA
+	 *  
+	 * @param ike_sa_manager 	the manager object
+	 * @param ike_sa			SA to delete
+	 * @returns 				SUCCESS if found
+	 * 							NOT_FOUND when no such SA is available
+	 */
+	status_t (*checkin_and_delete) (ike_sa_manager_t* ike_sa_manager, ike_sa_t *ike_sa);
 	
 	/**
-	 * @brief Destroys a linked_list object
+	 * @brief Destroys the manager with all associated SAs
 	 * 
-	 * @warning all items are removed before deleting the list. The
-	 *          associated values are NOT destroyed. 
-	 * 			Destroying an list which is not empty may cause
-	 * 			memory leaks!
+	 * Threads will be driven out, so all SAs can be deleted cleanly
 	 * 
-	 * @param linked_list calling object
+	 * @param ike_sa_manager the manager object
 	 * @returns SUCCESS if succeeded, FAILED otherwise
 	 */
-	status_t (*destroy) (ike_sa_manager_t *isam);
+	status_t (*destroy) (ike_sa_manager_t *ike_sa_manager);
 };
 
 /**
- * @brief Create the IKE_SA-Manager
+ * @brief Create a manager
+ * 
+ * @returns the manager
  */
 ike_sa_manager_t *ike_sa_manager_create();