diff --git a/Source/charon/parser.c b/Source/charon/parser.c index 0e01259af..3755a6e3f 100644 --- a/Source/charon/parser.c +++ b/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; diff --git a/Source/charon/parser.h b/Source/charon/parser.h index 893917b8f..8a13f9984 100644 --- a/Source/charon/parser.h +++ b/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); - }; @@ -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); diff --git a/Source/charon/tests/parser_test.c b/Source/charon/tests/parser_test.c index c6adf29c5..ad19d0363 100644 --- a/Source/charon/tests/parser_test.c +++ b/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");