implemented and tested functionality to create sa_payload from
[strongswan.git] / Source / charon / encoding / payloads / sa_payload.h
index 7eada84..ad450b3 100644 (file)
@@ -1,10 +1,7 @@
 /**
  * @file sa_payload.h
  * 
- * @brief Declaration of the class sa_payload_t. 
- * 
- * An object of this type represents an IKEv2 SA-Payload and contains proposal 
- * substructures.
+ * @brief Interface of sa_payload_t.
  * 
  */
 
 #include <encoding/payloads/payload.h>
 #include <encoding/payloads/proposal_substructure.h>
 #include <utils/linked_list.h>
+#include <config/init_config.h>
 
 /**
- * Critical flag must not be set
+ * Critical flag must not be set.
+ * 
+ * @ingroup payloads
  */
 #define SA_PAYLOAD_CRITICAL_FLAG FALSE;
 
 /**
- * SA_PAYLOAD length in bytes without any proposal substructure
+ * SA_PAYLOAD length in bytes without any proposal substructure.
+ * 
+ * @ingroup payloads
  */
 #define SA_PAYLOAD_HEADER_LENGTH 4
 
 typedef struct sa_payload_t sa_payload_t;
 
 /**
- * Object representing an IKEv2-SA Payload
+ * Class representing an IKEv2-SA Payload.
  * 
  * The SA Payload format is described in RFC section 3.3.
  * 
+ * @ingroup payloads
  */
 struct sa_payload_t {
        /**
-        * implements payload_t interface
+        * The payload_t interface.
         */
        payload_t payload_interface;
        
@@ -65,13 +68,10 @@ struct sa_payload_t {
         *                      by calling get_length()!
         *
         * @param this                  calling sa_payload_t object
-        * @param iterator              the created iterator is stored at the pointed pointer
         * @param[in] forward   iterator direction (TRUE: front to end)
-        * @return              
-        *                                              - SUCCESS or
-        *                                              - OUT_OF_RES if iterator could not be created
+        * @return                              created iterator_t object
         */
-       status_t (*create_proposal_substructure_iterator) (sa_payload_t *this,iterator_t **iterator, bool forward);
+       iterator_t *(*create_proposal_substructure_iterator) (sa_payload_t *this, bool forward);
        
        /**
         * @brief Adds a proposal_substructure_t object to this object.
@@ -81,30 +81,51 @@ struct sa_payload_t {
         *
         * @param this          calling sa_payload_t object
         * @param proposal  proposal_substructure_t object to add
-        * @return                      - SUCCESS if succeeded
-        *                                      - FAILED otherwise
         */
-       status_t (*add_proposal_substructure) (sa_payload_t *this,proposal_substructure_t *proposal);
+       void (*add_proposal_substructure) (sa_payload_t *this,proposal_substructure_t *proposal);
+       
+       /**
+        * Creates an array of ike_proposal_t's in this SA payload.
+        * 
+        * An IKE proposal consist of transform of type ENCRYPTION_ALGORITHM,
+        * PSEUDO_RANDOM_FUNCTION, INTEGRITY_ALGORITHM and DIFFIE_HELLMAN_GROUP
+        * 
+        * @param proposals                     the pointer to the first entry of ike_proposal_t's is set
+        * @param proposal_count        the number of found proposals is written at this location
+        * @return
+        *                                                      - SUCCESS if an IKE proposal could be found
+        *                                                      - NOT_FOUND if no IKE proposal could be found
+        *                                                      - FAILED if a proposal does not contain all needed transforms
+        *                                                        for a IKE_PROPOSAL 
+        */
+       status_t (*get_ike_proposals) (sa_payload_t *this, ike_proposal_t **proposals, size_t *proposal_count); 
 
        /**
         * @brief Destroys an sa_payload_t object.
         *
         * @param this  sa_payload_t object to destroy
-        * @return              
-        *                              SUCCESS in any case
         */
-       status_t (*destroy) (sa_payload_t *this);
+       void (*destroy) (sa_payload_t *this);
 };
 
 /**
  * @brief Creates an empty sa_payload_t object
  * 
- * @return                     
- *                                     - created sa_payload_t object, or
- *                                     - NULL if failed
+ * @return                     created sa_payload_t object
+ * 
+ * @ingroup payloads
  */
 sa_payload_t *sa_payload_create();
 
+/**
+ * @brief Creates a sa_payload_t object from array of ike_proposal_t's.
+ * 
+ * @return                                     created sa_payload_t object
+ * @param proposals                    pointer to first proposal in array of type ike_proposal_t
+ * @param proposal_count       number of ike_proposal_t's in array
+ * 
+ * @ingroup payloads
+ */
+sa_payload_t *sa_payload_create_from_ike_proposals(ike_proposal_t *proposals, size_t proposal_count);
 
 #endif /*SA_PAYLOAD_H_*/