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 distributed 8-bit (byte) array random numbers
  71  * @param[out] location
  72  *              memory location to start filling with random bytes
  73  * @param[in] len
  74  *              length of array to be filled with random bytes
  75  */
  76 void OCFillRandomMem(uint8_t * location, uint16_t len);
  77
  78 /*
  79  * Generate a uniformly distributed number on the defined bounded range
  80  * @param[in] firstBound
  81  *              the first bound of the range
  82  * @param[in] secondBound
  83  *              the second bound of the range
  84  */
  85 uint32_t OCGetRandomRange(uint32_t firstBound, uint32_t secondBound);
  86
  87 /**
  88  * Generate a Uniformly Unique Identifier based on RFC4122 and
  89  * provide it as a 16 byte byte-array
  90  *
  91  * @param[out] uuid
  92  *               the 16 byte array to fill with the UUID data
  93  *               of a new UUID
  94  *
  95  * @retval RAND_UUID_OK for success, otherwise an error value
  96  */
  97 OCRandomUuidResult OCGenerateUuid(uint8_t uuid[UUID_SIZE]);
  98
  99 /**
 100  * Generate a Uniformly Unique Identifier based on RFC4122 and
 101  * provide it as a C style string.
 102  *
 103  * @param[out] uuidString
 104  *               a 37-byte length string to fill with the string
 105  *               representation of a new UUID.  Size is 32 chars
 106  *               for the hex data, 4 for '-' characters, and 1
 107  *               for the NULL terminator
 108  *
 109  * @retval RAND_UUID_OK for success, otherwise an error value
 110  */
 111 OCRandomUuidResult OCGenerateUuidString(char uuidString[UUID_STRING_SIZE]);
 112
 113 /**
 114  * Convert a UUID generated by OCGenerateUuid to a C style string
 115  * based on RFC 4122
 116  *
 117  * @param[in]  uuid
 118  *              The 16 byte array filled with UUID data by OCGenerateUuid
 119  * @param[out] uuidString
 120  *              a 37 byte length string to fill with the string
 121  *              representation of the passed UUID.
 122  * @retval RAND_UUID_OK for success, otherwise an error value
 123  */
 124 OCRandomUuidResult OCConvertUuidToString(const uint8_t uuid[UUID_SIZE],
 125         char uuidString[UUID_STRING_SIZE]);
 126
 127 #ifdef __cplusplus
 128 }
 129 #endif
 130
 131 #endif // OC_RANDOM_H