- code documentation cleaned
authorJan Hutter <jhutter@hsr.ch>
Fri, 25 Nov 2005 08:55:25 +0000 (08:55 -0000)
committerJan Hutter <jhutter@hsr.ch>
Fri, 25 Nov 2005 08:55:25 +0000 (08:55 -0000)
Source/charon/utils/allocator.h
Source/charon/utils/iterator.h
Source/charon/utils/logger.h
Source/charon/utils/randomizer.c
Source/charon/utils/randomizer.h

index b011121..f27610a 100644 (file)
        /**
         * Macro to reallocate some memory.
         * 
-        * See #allocator_s.reallocate for description.
+        * See #allocator_t.reallocate for description.
         * 
         * @ingroup utils
         */
        /**
         * Macro to clone some memory.
         * 
-        * See #allocator_s.*clone_bytes  for description.
+        * See #allocator_t.*clone_bytes  for description.
         * 
         * @ingroup utils
         */
        /**
         * Macro to free some memory.
         * 
-        * See #allocator_s.free for description.
+        * See #allocator_t.free_pointer for description.
         *
         * @ingroup utils
         */
index 8a2a3c3..31964e0 100644 (file)
@@ -49,7 +49,7 @@ struct iterator_t {
         * Returns the current value at the iterator position.
         * 
         * @param this                  calling object
-        * @param [out]value    value is set to the current value at iterator position
+        * @param[out] value    value is set to the current value at iterator position
         * @return
         *                                              - SUCCESS
         *                                              - FAILED if list is empty
@@ -62,7 +62,7 @@ struct iterator_t {
         * The iterator position is not changed after inserting
         * 
         * @param this                  calling iterator
-        * @param [in]item              value to insert in list
+        * @param[in] item              value to insert in list
         * @return 
         *                                              - SUCCESS
         *                                              - FAILED
@@ -75,7 +75,7 @@ struct iterator_t {
         * The iterator position is not changed after inserting.
         * 
         * @param this                  calling iterator
-        * @param [in]item              value to insert in list
+        * @param[in] item              value to insert in list
         * @return
         *                                              - SUCCESS 
         *                                              - FAILED
index 0b6c492..35b80c2 100644 (file)
@@ -164,6 +164,7 @@ struct logger_t {
  *
  * @param logger_name  name for the logger_t object
  * @param log_level            or'ed set of log_levels to assign to the new logger_t object
+ * @param log_thread_id        TRUE if thread id should also be logged
  * @param output                       FILE * if log has to go on a file output, NULL for syslog
  * @return                             
  *                                             - logger_t object 
index f15507a..88c9e82 100644 (file)
@@ -1,7 +1,7 @@
 /**
  * @file randomizer.c
  * 
- * @brief Class used to get random and pseudo random values
+ * @brief Implementation of randomizer_t.
  * 
  */
 
 
 #include <utils/allocator.h>
 
-/**
- * Default random device used when no device is given.
- */
-#define DEFAULT_RANDOM_DEVICE "/dev/random"
+typedef struct private_randomizer_t private_randomizer_t;
 
 /**
- * Pseudo random device used when no device is given.
+ * Private data of an randomizer_t object
  */
-#define DEFAULT_PSEUDO_RANDOM_DEVICE "/dev/urandom"
-
-typedef struct private_randomizer_t private_randomizer_t;
-
 struct private_randomizer_t {
        /**
-        * public interface
+        * Public interface.
         */
        randomizer_t public;
        
        /**
-        * @brief Reads a specific number of bytes from random or pseudo random device
+        * @brief Reads a specific number of bytes from random or pseudo random device.
         * 
+        * @param this                                  calling object
         * @param pseudo_random                 TRUE, if pseudo random bytes should be read,
         *                                                              FALSE for true random bytes
-        * @param bytes                                 Number of bytes to read
-        * @param[out] buffer                   Pointer to buffer where to write the data in.
+        * @param bytes                                 number of bytes to read
+        * @param[out] buffer                   pointer to buffer where to write the data in.
         *                                                              Size of buffer has to be at least bytes.
         * @return
         *                                                              - SUCCESS
-        *                                                              - FAILED
+        *                                                              - FAILED if random device could not be opened
         */
        status_t (*get_bytes_from_device) (private_randomizer_t *this,bool pseudo_random, size_t bytes, u_int8_t *buffer);
                
        /**
-        * Random device name
+        * Random device name.
         */
        char *random_dev_name;
        
        /**
-        * Pseudo random device name
+        * Pseudo random device name.
         */
        char *pseudo_random_dev_name;
 };
 
 
 /**
- * Implements private_randomizer_t's get_bytes_from_device function.
- * See #private_randomizer_t.get_bytes_from_device for description.
+ * Implementation of private_randomizer_t.get_bytes_from_device.
  */
 static status_t get_bytes_from_device(private_randomizer_t *this,bool pseudo_random, size_t bytes, u_int8_t *buffer)
 {
@@ -114,16 +107,15 @@ static status_t get_bytes_from_device(private_randomizer_t *this,bool pseudo_ran
 }
 
 /**
- * Implements randomizer_t's get_random_bytes function.
- * See #randomizer_t.get_random_bytes for description.
+ * Implementation of randomizer_t.get_random_bytes.
  */
 static status_t get_random_bytes(private_randomizer_t *this,size_t bytes, u_int8_t *buffer)
 {
        return (this->get_bytes_from_device(this, FALSE, bytes, buffer));
 }
+
 /**
- * Implements randomizer_t's allocate_random_bytes function.
- * See #randomizer_t.allocate_random_bytes for description.
+ * Implementation of randomizer_t.allocate_random_bytes.
  */
 static status_t allocate_random_bytes(private_randomizer_t *this, size_t bytes, chunk_t *chunk)
 {
@@ -137,8 +129,7 @@ static status_t allocate_random_bytes(private_randomizer_t *this, size_t bytes,
 }
 
 /**
- * Implements randomizer_t's get_pseudo_random_bytes function.
- * See #randomizer_t.get_pseudo_random_bytes for description.
+ * Implementation of randomizer_t.get_pseudo_random_bytes.
  */
 static status_t get_pseudo_random_bytes(private_randomizer_t *this,size_t bytes, u_int8_t *buffer)
 {
@@ -147,8 +138,7 @@ static status_t get_pseudo_random_bytes(private_randomizer_t *this,size_t bytes,
 
 
 /**
- * Implements randomizer_t's allocate_random_bytes function.
- * See #randomizer_t.allocate_random_bytes for description.
+ * Implementation of randomizer_t.allocate_pseudo_random_bytes.
  */
 static status_t allocate_pseudo_random_bytes(private_randomizer_t *this, size_t bytes, chunk_t *chunk)
 {
@@ -163,8 +153,7 @@ static status_t allocate_pseudo_random_bytes(private_randomizer_t *this, size_t
 
 
 /**
- * Implements randomizer_t's destroy function.
- * See #randomizer_t.destroy for description.
+ * Implementation of randomizer_t.destroy.
  */
 static status_t destroy(private_randomizer_t *this)
 {
index b9f8890..a18a377 100644 (file)
@@ -1,7 +1,7 @@
 /**
  * @file randomizer.h
  * 
- * @brief Class used to get random and pseudo random values
+ * @brief Interface of randomizer_t.
  * 
  */
 
 typedef struct randomizer_t randomizer_t;
 
 /**
- * @brief Object representing an randomizer
+ * @brief Class used to get random and pseudo random values.
+ *
+ * This class is thread save as file system read calls are thread save.
  * 
- * This class is thread save as file system read calls are thread save...
+ * @ingroup utils
  */
 struct randomizer_t {
        
@@ -38,25 +40,25 @@ struct randomizer_t {
         * @brief Reads a specific number of bytes from random device.
         * 
         * @param this                                  calling randomizer_t object
-        * @param bytes                                 Number of bytes to read
-        * @param[out] buffer                   Pointer to buffer where to write the data in.
+        * @param bytes                                 number of bytes to read
+        * @param[out] buffer                   pointer to buffer where to write the data in.
         *                                                              Size of buffer has to be at least bytes.
         * @return
         *                                                              - SUCCESS
-        *                                                              - FAILED
+        *                                                              - FAILED if random device could not be opened
         */
        status_t (*get_random_bytes) (randomizer_t *this,size_t bytes, u_int8_t *buffer);
        
        /**
-        * @brief Allocates space and writes in random bytes
+        * @brief Allocates space and writes in random bytes.
         * 
         * @param this                                  calling randomizer_t object
-        * @param bytes                                 Number of bytes to allocate
-        * @param[out] chunk                    chunk which will hold the allocated random bytes
+        * @param bytes                                 number of bytes to allocate
+        * @param[out] chunk                            chunk which will hold the allocated random bytes
         * @return
         *                                                              - SUCCESS
         *                                                              - OUT_OF_RES
-        *                                                              - FAILED
+        *                                                              - FAILED if random device could not be opened
         */     
        status_t (*allocate_random_bytes) (randomizer_t *this, size_t bytes, chunk_t *chunk);
        
@@ -64,25 +66,25 @@ struct randomizer_t {
         * @brief Reads a specific number of bytes from pseudo random device.
         * 
         * @param this                                  calling randomizer_t object
-        * @param bytes                                 Number of bytes to read
-        * @param[out] buffer                   Pointer to buffer where to write the data in.
-        *                                                              Size of buffer has to be at least bytes.
+        * @param bytes                                 number of bytes to read
+        * @param[out] buffer                   pointer to buffer where to write the data in.
+        *                                                              size of buffer has to be at least bytes.
         * @return
         *                                                              - SUCCESS
-        *                                                              - FAILED
+        *                                                              - FAILED if random device could not be opened
         */
        status_t (*get_pseudo_random_bytes) (randomizer_t *this,size_t bytes, u_int8_t *buffer);
        
        /**
-        * @brief Allocates space and writes in pseudo random bytes
+        * @brief Allocates space and writes in pseudo random bytes.
         * 
         * @param this                                  calling randomizer_t object
-        * @param bytes                                 Number of bytes to allocate
+        * @param bytes                                 number of bytes to allocate
         * @param[out] chunk                            chunk which will hold the allocated random bytes
         * @return
         *                                                              - SUCCESS
         *                                                              - OUT_OF_RES
-        *                                                              - FAILED
+        *                                                              - FAILED if random device could not be opened
         */     
        status_t (*allocate_pseudo_random_bytes) (randomizer_t *this, size_t bytes, chunk_t *chunk);
 
@@ -90,29 +92,32 @@ struct randomizer_t {
         * @brief Destroys a randomizer_t object.
         *
         * @param this  randomizer_t object to destroy
-        * @return              
-        *                              SUCCESS in any case
+        * @return              SUCCESS in any case
         */
        status_t (*destroy) (randomizer_t *this);
 };
 
 /**
- * @brief Create an randomizer_t object
+ * @brief Creates a randomizer_t object
  * 
  * @return                     
  *                                     - created randomizer_t, or
  *                                     - NULL if failed
+ * 
+ * @ingroup utils
  */
 randomizer_t *randomizer_create();
 
 /**
- * @brief Create an randomizer_t object with specific random device names
+ * @brief Creates an randomizer_t object with specific random device names.
  * 
- * @param random_dev_name      Device name for random values, etc /dev/random
- * @param prandom_dev_name     Device name for pseudo random values, etc /dev/urandom
+ * @param random_dev_name      device name for random values, etc /dev/random
+ * @param prandom_dev_name     device name for pseudo random values, etc /dev/urandom
  * @return                                     
- *                                                     - created randomizer_t, or
- *                                                     - NULL if failed
+ *                                                     - created randomizer_t
+ *                                                     - NULL if out of ressources
+ * 
+ * @ingroup utils
  */
 randomizer_t *randomizer_create_on_devices(char * random_dev_name,char * prandom_dev_name);