- documented
[strongswan.git] / Source / charon / parser.h
index 893917b..8a13f99 100644 (file)
 #include "types.h"
 #include "encodings.h"
 
-
+/**
+ * @brief The parser context stores state information for a parsing session.
+ */
 typedef struct parser_context_s parser_context_t;
 
 struct parser_context_s {
-
+       /**
+        * @brief destructor of parsing_context
+        * 
+        * called it when finished a parsing session
+        * 
+        * @param this          the parser_context_t to destroy
+        * @return
+        *                                      - SUCCESS in any case
+        */
        status_t (*destroy) (parser_context_t *this);
-       
 };
 
 
@@ -42,24 +51,36 @@ struct parser_context_s {
 typedef struct parser_s parser_t;
 
 struct parser_s {
-
+       
        /**
-        * @brief parses a chunk and generates a usable data struct
+        * @brief generates a context for parsing
         *
-        * Remember: Header and substructures are also seen as payloads
+        * a context is used for a parsing session. It safes the state, such as
+        * parsing position, available size, ...
         *
-        * @param parser                parser Object
-        * @param payload_type  definition of payload including encoding_rule
-        * @param data                  chunk of data to parse
-        * @param[out]                  allocated structure with parsed data
-        * @return                      
-        *                                              - SUCCESSFUL if succeeded,
-        *                                              - NOT_SUPPORTED if payload_type is not supported
-        *                                              - OUT_OF_RES if out of ressources
-        *                                              - PARSE_ERROR if corrupted data found
+        * @param parser                        parser Object
+        * @param chunk                         chunk of data to parse in this session
+        * @return                                      the parsing_context, or NULL if failed
         */
+
        parser_context_t *(*create_context) (parser_t *this, chunk_t data);
-       status_t (*parse_payload) (parser_t *this, parser_context_t* context, payload_type_t payload_type, void **data_struct);
+       
+       /**
+        * @brief parses the next payload in the current context
+        * 
+        * @warning caller is responsible for freeing allocated data_struct
+        *
+        * @param parser                        parser Object
+        * @param payload_type          payload to parse
+        * @param[out] data_struct      pointer where parsed data will be allocated
+        * @param context                       the parsing context, describing the current parsing session
+        * @return                      
+        *                                                      - SUCCESSFUL if succeeded,
+        *                                                      - NOT_SUPPORTED if payload_type is not supported
+        *                                                      - OUT_OF_RES if out of ressources
+        *                                                      - PARSE_ERROR if corrupted data found
+        */
+       status_t (*parse_payload) (parser_t *this, payload_type_t payload_type, void **data_struct, parser_context_t* context);
        
        /**
         * @brief Destroys a parser object
@@ -72,7 +93,12 @@ struct parser_s {
 };
 
 /**
- * Constructor to create a parser
+ * @brief Constructor to create a parser
+ * 
+ * The parser uses a set of payload_infos to know how to
+ * parse different payloads.
+ * 
+ * @param payload_infos                        list of payload_info_t 
  *
  */
 parser_t *parser_create(payload_info_t **payload_infos);