- documented

- fixed argument order for parse_payload

Source/charon/parser.c

@@ -28,7 +28,11 @@
 #include "parser.h"
 #include "logger.h"
 
-
+/**
+ * @private data stored in a context
+ * 
+ * contains pointers and counters to store current state
+ */
 typedef struct private_parser_context_s private_parser_context_t;
 
 struct private_parser_context_s {
@@ -60,6 +64,9 @@ struct private_parser_context_s {
 	
 };
 
+/**
+ * implementation of parser_context_t.destroy
+ */
 static status_t parser_context_destroy(private_parser_context_t *this)
 {
 	allocator_free(this);
@@ -67,28 +74,9 @@ static status_t parser_context_destroy(private_parser_context_t *this)
 	return SUCCESS;	
 }
 
-static private_parser_context_t *parser_context_create(chunk_t input)
-{
-	private_parser_context_t *this = allocator_alloc_thing(private_parser_context_t);
-	if (this == NULL)
-	{
-		return NULL;	
-	}
-	
-	this->public.destroy = (status_t(*)(parser_context_t*)) parser_context_destroy;
-	
-	this->input = input.ptr;
-	this->byte_pos = input.ptr;
-	this->bit_pos = 0;
-	this->input_roof = input.ptr + input.len;
-	
-	return this;
-}
-
-
 
 /**
- * Private data of a parser_t object
+ * @brief Private data of a parser_t object
  */
 typedef struct private_parser_s private_parser_t;
 
@@ -107,18 +95,33 @@ struct private_parser_s {
 	 * logger object
 	 */
 	logger_t *logger;
-
-	
 };
 
+/**
+ * implementation of parser_t.create_context
+ */
 static private_parser_context_t *create_context(private_parser_t *this, chunk_t data)
 {
-	private_parser_context_t *context = parser_context_create(data);
+	private_parser_context_t *context = allocator_alloc_thing(private_parser_context_t);
+	if (this == NULL)
+	{
+		return NULL;	
+	}
+	
+	context->public.destroy = (status_t(*)(parser_context_t*)) parser_context_destroy;
+	
+	context->input = data.ptr;
+	context->byte_pos = data.ptr;
+	context->bit_pos = 0;
+	context->input_roof = data.ptr + data.len;
 	
 	return context;
 }
 
-static status_t parse_payload(private_parser_t *this, private_parser_context_t *context, payload_type_t payload_type, void **data_struct)
+/**
+ * implementation of parser_context_t.parse_payload
+ */
+static status_t parse_payload(private_parser_t *this, payload_type_t payload_type, void **data_struct, private_parser_context_t *context)
 {
 	payload_info_t *payload_info = NULL;
 	
@@ -371,6 +374,9 @@ static status_t parse_payload(private_parser_t *this, private_parser_context_t *
 	return NOT_SUPPORTED;
 }
 
+/**
+ * implementation of parser_t.destroy
+ */
 static status_t destroy(private_parser_t *this)
 {
 	this->logger->destroy(this->logger);
@@ -379,6 +385,9 @@ static status_t destroy(private_parser_t *this)
 	return SUCCESS;
 }
 
+/*
+ * see header file
+ */
 parser_t *parser_create(payload_info_t **payload_infos)
 {
 	private_parser_t *this = allocator_alloc_thing(private_parser_t);
@@ -395,7 +404,7 @@ parser_t *parser_create(payload_info_t **payload_infos)
 		return NULL;
 	}
 	this->public.create_context = (parser_context_t*(*)(parser_t*,chunk_t)) create_context;
-	this->public.parse_payload = (status_t(*)(parser_t*,parser_context_t*,payload_type_t,void**)) parse_payload;
+	this->public.parse_payload = (status_t(*)(parser_t*,payload_type_t,void**,parser_context_t*)) parse_payload;
 	this->public.destroy = (status_t(*)(parser_t*)) destroy;
 	
 	this->payload_infos = payload_infos;	

Source/charon/parser.h

@@ -26,13 +26,22 @@
 #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);
-	
 };
 
 
@@ -44,22 +53,34 @@ 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 parser			parser Object
-	 * @param payload_type	definition of payload including encoding_rule
+	 * @param chunk				chunk of data to parse in this session
-	 * @param data			chunk of data to parse
+	 * @return 					the parsing_context, or NULL if failed
-	 * @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
 	 */
+
 	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);

Source/charon/tests/parser_test.c

@@ -64,7 +64,7 @@ void test_parser_with_header_payload(tester_t *tester)
 	parser_context = parser->create_context(parser, test_chunk);
 	tester->assert_true(tester,(parser_context != NULL), "parser_context create check");
 
-	status = parser->parse_payload(parser, parser_context, HEADER, (void**)&header_data);
+	status = parser->parse_payload(parser, HEADER, (void**)&header_data, parser_context);
 	tester->assert_true(tester,(status == SUCCESS),"parse_payload call check");
 	
 	tester->assert_true(tester,(header_data->initiator_spi == 1),"parsed initiator_spi value");