- source code documentation improved
authorJan Hutter <jhutter@hsr.ch>
Thu, 10 Nov 2005 09:54:09 +0000 (09:54 -0000)
committerJan Hutter <jhutter@hsr.ch>
Thu, 10 Nov 2005 09:54:09 +0000 (09:54 -0000)
Source/charon/generator.c
Source/charon/generator.h

index 7bfaa00..450e58d 100644 (file)
 
 
 /**
- * Uused for geneartor operations
+ * Used for generator operations internaly to store a generator context.
  */
 typedef struct generator_infos_s generator_infos_t;
 
 struct generator_infos_s {
 
        /**
-        * Buffer used to generate to
+        * Buffer used to generate the data into.
         */
        u_int8_t *buffer;
 
        /**
-        * current write position in buffer (one byte alligned)
+        * Current write position in buffer (one byte aligned).
         */
        u_int8_t *out_position;
 
        /**
-        * position of last byte in buffer
+        * Position of last byte in buffer.
         */
        u_int8_t *roof_position;
 
        /**
-        * Current bit writing to
+        * Current bit writing to in current byte (between 0 and 7).
         */
        size_t current_bit;
 
        /**
-        * Associated data struct to read informations from
+        * Associated data struct to read informations from.
         */
         void * data_struct;
+
        /**
-        * @brief Destroys a generator_infos_t object
+        * @brief Destroys a generator_infos_t object and its containing buffer
         *
         * @param generator_infos_t generator_infos_t object
-        * @return SUCCESSFUL if succeeded, FAILED otherwise
+        * @return                                      always SUCCESSFUL
         */
        status_t (*destroy) (generator_infos_t *this);
 
        /**
-        * Checks if enough space is available in buffer and if not,
-        * the buffer size is increased until at least the asked amount of space
-        * is available
+        * Makes sure enough space is available in buffer to store amount of bits.
+     *
+        * If buffer is to small to hold the specific amount of bits it 
+        * is increased using reallocation function of allocator.
         *
-        * @param bits number of bits to make at leas available in buffer
-        * @param generator_infos_t generator_infos_t object
-        * @return SUCCESSFUL if succeeded, OUT_OF_RES otherwise
+        * @param generator_infos_t calling generator_infos_t object
+        * @param bits                          number of bits to make available in buffer
+        * @return 
+        *                                                      - SUCCESSFUL if succeeded
+        *                                                      - OUT_OF_RES otherwise
         */
        status_t (*make_space_available) (generator_infos_t *this,size_t bits);
 
+       /**
+        * Writes a specific amount of byte into the buffer.
+        * 
+        * If buffer is to small to hold the specific amount of bytes it 
+        * is increased.
+        *
+        * @param generator_infos_t calling generator_infos_t object
+        * @param bytes                                 pointer to bytes to write
+        * @param number_of_bytes       number of bytes to write into buffer
+        * @return 
+        *                                                      - SUCCESSFUL if succeeded
+        *                                                      - OUT_OF_RES otherwise
+        */
        status_t (*write_bytes_to_buffer) (generator_infos_t *this,void * bytes,size_t number_of_bytes);
 
+       /**
+        * Writes the current buffer content into a chunk_t
+        * 
+        * Memory of specific chunk_t gets allocated.
+        *
+        * @param generator_infos_t calling generator_infos_t object
+        * @param data                          pointer of chunk_t to write to
+        * @return 
+        *                                                      - SUCCESSFUL if succeeded
+        *                                                      - OUT_OF_RES otherwise
+        */
        status_t (*write_chunk) (generator_infos_t *this,chunk_t *data);
 };
 
 /**
- * implements generator_infos_t's increase_buffer function
+ * Implements generator_infos_t's increase_buffer function.
+ * See #generator_infos_s.increase_buffer.
  */
 static status_t generator_info_make_space_available (generator_infos_t *this, size_t bits)
 {
@@ -112,6 +141,10 @@ static status_t generator_info_make_space_available (generator_infos_t *this, si
        return SUCCESS;
 }
 
+/**
+ * Implements generator_infos_t's write_bytes_to_buffer function.
+ * See #generator_infos_s.write_bytes_to_buffer.
+ */
 static status_t generator_info_write_bytes_to_buffer (generator_infos_t *this,void * bytes,size_t number_of_bytes)
 {
        u_int8_t *read_position = (u_int8_t *) bytes;
@@ -134,6 +167,10 @@ static status_t generator_info_write_bytes_to_buffer (generator_infos_t *this,vo
        return status;
 }
 
+/**
+ * Implements generator_infos_t's write_chunk function.
+ * See #generator_infos_s.write_chunk.
+ */
 static status_t generator_infos_write_chunk (generator_infos_t *this,chunk_t *data)
 {
        size_t data_length = this->out_position - this->buffer;
@@ -151,12 +188,12 @@ static status_t generator_infos_write_chunk (generator_infos_t *this,chunk_t *da
 }
 
 
+/**
+ * Implements generator_infos_t's destroy function.
+ * See #generator_infos_s.destroy.
+ */
 static status_t generator_infos_destroy (generator_infos_t *this)
 {
-       if (this == NULL)
-       {
-               return FAILED;
-       }
        allocator_free(this->buffer);
        allocator_free(this);
        return SUCCESS;
@@ -164,9 +201,12 @@ static status_t generator_infos_destroy (generator_infos_t *this)
 
 /**
  * Creates a generator_infos_t object holding necessary informations
- * for generating (buffer, data_struct, etc)
+ * for generating (buffer, data_struct, etc).
  *
- * @param data_struct where to read the data out
+ * @param data_struct  data struct where the specific payload informations are stored
+ * @return                             
+ *                                             - pointer to created generator_infos_t object
+ *                                             - NULL if memory allocation failed
  */
 generator_infos_t * generator_infos_create(void *data_struct)
 {
@@ -202,36 +242,45 @@ generator_infos_t * generator_infos_create(void *data_struct)
 
 
 /**
- * Private data of a generator_t object
+ * Private part of a generator_t object
  */
 typedef struct private_generator_s private_generator_t;
 
 struct private_generator_s {
        /**
-        * Public part of a generator object
+        * Public part of a generator_t object
         */
         generator_t public;
 
        /* private functions and fields */
 
        /**
-        * Generates a chunk_t with specific encoding rules
+        * Generates a chunk_t with specific encoding rules.
         *
-        * items are bytewhise written
+        * Iems are bytewhise written.
         *
-        * @param this private_generator_t object
-        * @param data_struct data_struct to read data from
-        * @param encoding_rules pointer to first encoding_rule of encoding rules array
-        * @param encoding_rules_count number of encoding rules in encoding rules array
-        * @param data pointer to chunk where to write the data in
+        * @param this                                  private_generator_t object
+        * @param data_struct                   data_struct to read data from
+        * @param encoding_rules                pointer to first encoding_rule 
+        *                                                              of encoding rules array
+        * @param encoding_rules_count  number of encoding rules 
+        *                                                              in encoding rules array
+        * @param data                                  pointer to chunk_t where to write the data in
         *
-        * @return SUCCESS if succeeded,
-        *                 OUT_OF_RES if out of ressources
+        * @return                                              - SUCCESS if succeeded
+        *                                                              - OUT_OF_RES if out of ressources
         */
        status_t (*generate) (private_generator_t *this,void * data_struct,encoding_rule_t *encoding_rules, size_t encoding_rules_count, chunk_t *data);
 
        /**
-        * TODO
+        * Generates a U_INT-Field type
+        *
+        * @param this                                  private_generator_t object
+        * @param int_type                              type of U_INT field (U_INT_4, U_INT_8, etc.)
+        * @param offset                                offset of value in data struct
+        * @param generator_infos               generator_infos_t object where the context is written or read from
+        * @return                                              - SUCCESS if succeeded
+        *                                                              - OUT_OF_RES if out of ressources
         */
        status_t (*generate_u_int_type) (private_generator_t *this,encoding_type_t int_type,u_int32_t offset, generator_infos_t *generator_infos);
 
@@ -243,7 +292,8 @@ struct private_generator_s {
 };
 
 /**
- * implements private_generator_t's double_buffer function
+ * Implements private_generator_t's generate_u_int_type function.
+ * See #private_generator_s.generate_u_int_type.
  */
 static status_t generate_u_int_type (private_generator_t *this,encoding_type_t int_type,u_int32_t offset,generator_infos_t *generator_infos)
 {
@@ -352,7 +402,8 @@ static status_t generate_u_int_type (private_generator_t *this,encoding_type_t i
 }
 
 /**
- * implements private_generator_t's generate function
+ * Implements private_generator_t's generate function.
+ * See #private_generator_s.generate.
  */
 static status_t generate (private_generator_t *this,void * data_struct,encoding_rule_t *encoding_rules, size_t encoding_rules_count, chunk_t *data)
 {
@@ -444,6 +495,10 @@ static status_t generate (private_generator_t *this,void * data_struct,encoding_
        return status;
 }
 
+/**
+ * Implements generator_t's generate_payload function.
+ * See #generator_s.generate_payload.
+ */
 static status_t generate_payload (private_generator_t *this,payload_type_t payload_type,void * data_struct, chunk_t *data)
 {
        int i;
@@ -461,15 +516,11 @@ static status_t generate_payload (private_generator_t *this,payload_type_t paylo
 }
 
 /**
- * Implementation of generator_t's destroy function
+ * Implements generator_t's destroy function.
+ * See #generator_s.destroy.
  */
 static status_t destroy(private_generator_t *this)
 {
-       if (this == NULL)
-       {
-               return FAILED;
-       }
-
        allocator_free(this);
        return SUCCESS;
 }
index 2574a0f..cfd47ae 100644 (file)
 #define GENERATOR_DATA_BUFFER_INCREASE_VALUE 1000
 
 /**
- * @brief A generator_t object which generates payloads of specific type
+ *A generator_t object which generates payloads of specific type.
  */
 typedef struct generator_s generator_t;
 
 struct generator_s {
 
        /**
-        * @brief Generates a specific payload from given data struct
+        * @brief Generates a specific payload from given data struct.
         *
-        * Remember: Header and substructures are also seen as payloads
+        * Remember: Header and substructures are also handled as payloads.
         *
-        * @param generator generator object
-        * @param payload_type payload type to generate using the given data struct
-        * @param[in] data_struct Data struct where the needed data for generating are stored
-        * @param[out] output pointer to a chunk_t where the data are generated to
-        * @return SUCCESSFUL if succeeded,
-        *                 NOT_SUPPORTED if payload_type is not supported
-        *                 OUT_OF_RES if out of ressources
+        * @param generator                     generator_t object
+        * @param payload_type          payload type to generate using the given data struct
+        * @param[in] data_struct       data struct where the needed data for generating are stored
+        * @param[out] output           pointer to a chunk_t where the data are generated to
+        * @return 
+        *                                                      - SUCCESSFUL if succeeded
+        *                                                      - NOT_SUPPORTED if payload_type is not supported
+        *                                                      - OUT_OF_RES if out of ressources
         */
        status_t (*generate_payload) (generator_t *this,payload_type_t payload_type,void * data_struct, chunk_t *data);
 
        /**
-        * @brief Destroys a generator object
+        * @brief Destroys a generator_t object.
         *
-        * @param generator generator object
-        * @return SUCCESSFUL if succeeded, FAILED otherwise
+        * @param generator generator_t object
+        * 
+        * @return                      always success
         */
        status_t (*destroy) (generator_t *this);
 };
@@ -71,8 +73,9 @@ struct generator_s {
 /**
  * Constructor to create a generator
  *
- * @param payload_infos        pointer to the payload_info_t-array containing
- * all the payload informations needed to automatic generate a specific payload
+ * @param payload_infos                pointer to the payload_info_t-array containing
+ *                                                     all the payload informations needed to 
+ *                                                     automatic generate a specific payload
  */
 generator_t * generator_create(payload_info_t ** payload_infos);