- documented
[strongswan.git] / Source / charon / configuration_manager.h
index 07cdef5..2228688 100644 (file)
 /**
  * @brief Manages all configuration aspects of the daemon.
  * 
+ * Currently the configuration manager class does not store specific configurations.
+ * It is expected, that in future different configurations are stored in a linked list 
+ * or a hash map and are managed by this class.
+ * 
  */
 typedef struct configuration_manager_s configuration_manager_t;
 
 struct configuration_manager_s { 
        
        /**
-        * Gets the remote host informations for a specific configuration name
+        * Gets the remote host information for a specific configuration name.
+        * 
+        * A host information consist of IP address and UDP port.
         * 
         * @param this  calling object
         * @param name  name of the configuration
-        * @param host  remote host informations are stored at this location
+        * @param host  remote host information gets stored at this location
         * 
         * @return              
+        *                              - OUT_OF_RES
         *                              - NOT_FOUND
         *                              - SUCCESS
-        *                              - OUT_OF_RES
         */
        status_t (*get_remote_host) (configuration_manager_t *this, char *name, host_t **host);
-       
+
+       /**
+        * Gets the local host information for a specific configuration name
+        * 
+        * A host information consist of IP address and UDP port.
+        * 
+        * @param this  calling object
+        * @param name  name of the configuration
+        * @param host  local host information gets stored at this location
+        * 
+        * @return              
+        *                              - OUT_OF_RES
+        *                              - NOT_FOUND (not yet implemented)
+        *                              - SUCCESS
+        */
        status_t (*get_local_host) (configuration_manager_t *this, char *name, host_t **host);
        
+       /**
+        * Returns the DH group number to use when initiating a connection.
+        * 
+        * To make sure that different group numbers are supported in case 
+        * a group number is not supported by other peer, a priority has to get defined.
+        * 
+        * 
+        * @param this                          calling object
+        * @param name                          name of the configuration
+        * @param dh_group_number       the DH group number gets stored at this location
+        * @param priority                      priority to use for selection of DH group number.
+        *                                                      Highest priority is 1. All higher values have lower
+        *                                                      priority.
+        * 
+        * @return              
+        *                                                      - FAILED (not yet implemented)
+        *                                                      - NOT_FOUND (not yet implemented)
+        *                                                      - SUCCESS
+        */
        status_t (*get_dh_group_number) (configuration_manager_t *this, char *name, u_int16_t *dh_group_number, u_int16_t priority);
        
+       /**
+        * Returns the proposals which should be used to initiate a connection with a specific
+        * host.
+        * 
+        * The proposals of type proposal_substructure_t * are returned over the given iterator 
+        * and have to be destroyed by the caller.
+        * 
+        * 
+        * @param this                          calling object
+        * @param host                          host information used to find the correct proposals
+        * @param list                          iterator where the proposals are written to
+        * 
+        * @return              
+        *                                                      - OUT_OF_RES
+        *                                                      - NOT_FOUND (not yet implemented)
+        *                                                      - SUCCESS
+        */
        status_t (*get_proposals_for_host) (configuration_manager_t *this, host_t *host, linked_list_iterator_t *list);
        
+       /**
+        * Checks the suggested proposals passed as iterator in and selects one proposal to be sent as selection
+        * of this proposals.
+        * 
+        * Currently there is no check implemented. The first suggested proposal is cloned and then as selected returned.
+        * 
+        * 
+        * @param this                          calling object
+        * @param host                          host information used to find the correct proposals
+        * @param in                                    iterator with suggested proposals of type proposal_substructure_t *
+        * @param out                           The selected proposals of type proposal_substructure_t * are written to this iterator
+        * 
+        * @return              
+        *                                                      - OUT_OF_RES
+        *                                                      - FAILED
+        *                                                      - NOT_FOUND (not yet implemented)
+        *                                                      - SUCCESS
+        */
        status_t (*select_proposals_for_host) (configuration_manager_t *this, host_t *host, linked_list_iterator_t *in, linked_list_iterator_t *out);
        
+       /**
+        * Returns the transforms of type crypter_t, signer_t and prf_t as specified in given proposal.
+        * 
+        * 
+        * @param this                          calling object
+        * @param host                          host information
+        * @param proposals                     iterator with selected proposals
+        * @param[out] crypter          The created transform object of type crypter_t is stored at this location
+        * @param[out] signer           The created transform object of type signer_t is stored at this location
+        * @param[out] prf                      The created transform object of type prf_t is stored at this location
+        * 
+        * @return              
+        *                                                      - OUT_OF_RES
+        *                                                      - FAILED
+        *                                                      - NOT_FOUND (not yet implemented)
+        *                                                      - SUCCESS
+        */
        status_t (*get_transforms_for_host_and_proposals) (configuration_manager_t *this, host_t *host, linked_list_iterator_t *proposals,crypter_t **crypter,signer_t **signer, prf_t **prf);
        
+       /**
+        * Checks if a given dh_group number is allowed for a specific host
+        * 
+        * 
+        * @param this                          calling object
+        * @param host                          host information
+        * @param group                         DH group number to check if allowed
+        * @param[out] allowed          will be set to TRUE if group number is allowed, FALSE otherwise
+        * 
+        * @return              
+        *                                                      - FAILED
+        *                                                      - NOT_FOUND (not yet implemented)
+        *                                                      - SUCCESS
+        */
        status_t (*is_dh_group_allowed_for_host) (configuration_manager_t *this, host_t *host, diffie_hellman_group_t group, bool *allowed);
        
+       /**
+        * Destroys configuration manager
+        * 
+        * 
+        * @param this                          calling object
+        * @return              
+        *                                                      - SUCCESS
+        */
        status_t (*destroy) (configuration_manager_t *this);
 };