resource/c_common/ocrandom/include/ocrandom.h

   1 //******************************************************************
   2 //
   3 // Copyright 2014 Intel Mobile Communications GmbH All Rights Reserved.
   4 //
   5 //-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
   6 //
   7 // Licensed under the Apache License, Version 2.0 (the "License");
   8 // you may not use this file except in compliance with the License.
   9 // You may obtain a copy of the License at
  10 //
  11 //      http://www.apache.org/licenses/LICENSE-2.0
  12 //
  13 // Unless required by applicable law or agreed to in writing, software
  14 // distributed under the License is distributed on an "AS IS" BASIS,
  15 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  16 // See the License for the specific language governing permissions and
  17 // limitations under the License.
  18 //
  19 //-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
  20
  21
  22 #ifndef OC_RANDOM_H
  23 #define OC_RANDOM_H
  24
  25 #include <stdint.h>
  26 #include <stdlib.h>
  27
  28 #ifdef __cplusplus
  29 extern "C" {
  30 #endif
  31
  32 #ifndef ARDUINO
  33 #include <time.h>
  34 #else
  35 // MEGA has 16 input pins whereas Due has only 12 input pins
  36 #define ANALOG_IN (10)
  37 #endif
  38
  39 #define UUID_SIZE (16)
  40 // The characters are 36 long, 37 for the null-term
  41 #define UUID_STRING_SIZE (37)
  42
  43 typedef enum
  44 {
  45     RAND_UUID_OK = 0,
  46     RAND_UUID_INVALID_PARAM = -1,
  47     RAND_UUID_READ_ERROR = -2,
  48     RAND_UUID_CONVERT_ERROR = -3
  49 } OCRandomUuidResult;
  50 /**
  51  * Seed the random number generator. Seeding depends on platform.
  52  * Android and Linux uses current time. Arduino uses Analog reading on pin ANALOG_IN
  53  * @retval 0 for Success, otherwise some error value
  54  */
  55 int8_t OCSeedRandom();
  56
  57 /**
  58  * Generate a uniformly [0,2^32] distributed random number
  59  * @retval On Success, it returns the random value.
  60  */
  61 uint32_t OCGetRandom();
  62
  63 /**
  64  * Generate a uniformly [0,2^8] distributed random number
  65  * @retval On Success, it returns the random value, otherwise -1 for error.
  66  */
  67 uint8_t OCGetRandomByte(void);
  68
  69 /**
  70  * Generate a uniformly [0,2^16] distributed random number
  71  * @retval On Success, it returns the random value, otherwise -1 for error.
  72  */
  73 uint16_t OCGetRandomTwoByte(void);
  74
  75 /**
  76  * Generate a uniformly distributed 8-bit (byte) array random numbers
  77  * @param[out] location
  78  *              memory location to start filling with random bytes
  79  * @param[in] len
  80  *              length of array to be filled with random bytes
  81  */
  82 void OCFillRandomMem(uint8_t * location, uint16_t len);
  83
  84 /*
  85  * Generate a uniformly distributed number on the defined bounded range
  86  * @param[in] firstBound
  87  *              the first bound of the range
  88  * @param[in] secondBound
  89  *              the second bound of the range
  90  */
  91 uint32_t OCGetRandomRange(uint32_t firstBound, uint32_t secondBound);
  92
  93 /**
  94  * Generate a Uniformly Unique Identifier based on RFC4122 and
  95  * provide it as a 16 byte byte-array
  96  *
  97  * @param[out] uuid
  98  *               the 16 byte array to fill with the UUID data
  99  *               of a new UUID
 100  *
 101  * @retval RAND_UUID_OK for success, otherwise an error value
 102  */
 103 OCRandomUuidResult OCGenerateUuid(uint8_t uuid[UUID_SIZE]);
 104
 105 /**
 106  * Generate a Uniformly Unique Identifier based on RFC4122 and
 107  * provide it as a C style string.
 108  *
 109  * @param[out] uuidString
 110  *               a 37-byte length string to fill with the string
 111  *               representation of a new UUID.  Size is 32 chars
 112  *               for the hex data, 4 for '-' characters, and 1
 113  *               for the NULL terminator
 114  *
 115  * @retval RAND_UUID_OK for success, otherwise an error value
 116  */
 117 OCRandomUuidResult OCGenerateUuidString(char uuidString[UUID_STRING_SIZE]);
 118
 119 /**
 120  * Convert a UUID generated by OCGenerateUuid to a C style string
 121  * based on RFC 4122
 122  *
 123  * @param[in]  uuid
 124  *              The 16 byte array filled with UUID data by OCGenerateUuid
 125  * @param[out] uuidString
 126  *              a 37 byte length string to fill with the string
 127  *              representation of the passed UUID.
 128  * @retval RAND_UUID_OK for success, otherwise an error value
 129  */
 130 OCRandomUuidResult OCConvertUuidToString(const uint8_t uuid[UUID_SIZE],
 131         char uuidString[UUID_STRING_SIZE]);
 132
 133 /**
 134  * Convert a C style string to a UUID based on RFC 4122
 135  *
 136  * @param[in] uuidString
 137  *              a 37 byte length string to fill with the string
 138  *              representation of the passed UUID.
 139  * @param[out]  uuid
 140  *              The 16 byte array filled with UUID data
 141  * @retval RAND_UUID_OK for success, otherwise an error value
 142  */
 143 OCRandomUuidResult OCConvertStringToUuid(const char uuidString[UUID_STRING_SIZE],
 144                                          uint8_t uuid[UUID_SIZE]);
 145
 146 #ifdef __cplusplus
 147 }
 148 #endif
 149
 150 #endif // OC_RANDOM_H