- described constructors
[strongswan.git] / Source / charon / utils / randomizer.h
index ae2bb53..509b7d5 100644 (file)
@@ -1,7 +1,7 @@
 /**
  * @file randomizer.h
  * 
- * @brief Class used to get random and pseudo random values
+ * @brief Interface of randomizer_t.
  * 
  */
 
 #ifndef RANDOMIZER_H_
 #define RANDOMIZER_H_
 
-#include "../types.h"
+#include <types.h>
+
 
 /**
- * Object representing an randomizer
- * 
- * This class is thread save as file system read calls are thread save...
+ * Default random device used when no device is given.
+ */
+#define DEFAULT_RANDOM_DEVICE "/dev/random"
+
+/**
+ * Pseudo random device used when no device is given.
  */
-typedef struct randomizer_s randomizer_t;
+#define DEFAULT_PSEUDO_RANDOM_DEVICE "/dev/urandom"
+
+typedef struct randomizer_t randomizer_t;
 
-struct randomizer_s {
+/**
+ * @brief Class used to get random and pseudo random values.
+ *
+ * This class is thread save as file system read calls are thread save.
+ * 
+ * @b Constructors:
+ *  - randomizer_create()
+ *  - randomizer_create_on_devices()
+ * 
+ * @ingroup utils
+ */
+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
         */
-       status_t (*get_random_bytes) (randomizer_t *this,size_t bytes, u_int8_t *buffer);
+       void (*get_random_bytes) (randomizer_t *this,size_t bytes, u_int8_t *buffer);
+       
+       /**
+        * @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
+        */     
+       void (*allocate_random_bytes) (randomizer_t *this, size_t bytes, chunk_t *chunk);
        
        /**
         * @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.
-        * @return
-        *                                                              - SUCCESS
-        *                                                              - FAILED
+        * @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.
         */
-       status_t (*get_pseudo_random_bytes) (randomizer_t *this,size_t bytes, u_int8_t *buffer);
-
+       void (*get_pseudo_random_bytes) (randomizer_t *this,size_t bytes, u_int8_t *buffer);
+       
+       /**
+        * @brief Allocates space and writes in pseudo 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
+        */     
+       void (*allocate_pseudo_random_bytes) (randomizer_t *this, size_t bytes, chunk_t *chunk);
 
        /**
         * @brief Destroys a randomizer_t object.
         *
         * @param this  randomizer_t object to destroy
-        * @return              
-        *                              SUCCESS in any case
         */
-       status_t (*destroy) (randomizer_t *this);
+       void (*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
+ * @return                                     randomizer_t object
  * 
- * @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
+ * @ingroup utils
  */
 randomizer_t *randomizer_create_on_devices(char * random_dev_name,char * prandom_dev_name);