Use `URI` all caps in documentation
[iotivity.git] / resource / c_common / ocrandom / include / experimental / 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 #include <stdbool.h>
28
29 #ifdef __cplusplus
30 extern "C" {
31 #endif
32
33  /* Number of bytes in a UUID. */
34 #define UUID_SIZE (16)
35
36 /*
37  * Size of a UUID string.
38  * IoTivity formats UUIDs as strings following RFC 4122, Section 3.
39  * For example, "f81d4fae-7dec-11d0-a765-00a0c91e6bf6".
40  * This requires 36 characters, plus one for the null terminator.
41  */
42 #define UUID_STRING_SIZE (37)
43
44 /**
45  * Generate a uniformly distributed 32-bit random number.
46  * @retval On success, it returns the random value.
47  */
48 uint32_t OCGetRandom(void);
49
50 /**
51  * Generate an array of uniformly distributed random bytes.
52  * @param[out] output
53  *              Array to fill with random bytes
54  * @param[in] len
55  *              Length of array
56  * @retval true for success, otherwise false and an error is logged
57  */
58 bool OCGetRandomBytes(uint8_t * output, size_t len);
59
60 /**
61  * Generate a uniformly distributed number in a given range.
62  * @param[in] firstBound
63  *              The output is greater than or equal to firstBound
64  * @param[in] secondBound
65  *              The output is less than or equal to secondBound
66  */
67 uint32_t OCGetRandomRange(uint32_t firstBound, uint32_t secondBound);
68
69 /**
70  * Generate a Uniformly Unique Identifier based on RFC4122 and
71  * provide it as UUID_SIZE bytes.
72  *
73  * @param[out] uuid
74  *               UUID_SIZE array to hold the new UUID
75  *
76  * @retval true for success, otherwise false and an error is logged
77  */
78 bool OCGenerateUuid(uint8_t uuid[UUID_SIZE]);
79
80 /**
81  * Convert a UUID generated by OCGenerateUuid to a C string
82  * based on RFC 4122.
83  *
84  * @param[in]  uuid
85  *              Array of length UUID_SIZE bytes with output of OCGenerateUuid
86  * @param[out] uuidString
87  *              A UUID_STRING_SIZE length string to hold the string
88  *              representation of the input UUID.
89  * @retval true for success, otherwise false and an error is logged
90  */
91 bool OCConvertUuidToString(const uint8_t uuid[UUID_SIZE],
92         char uuidString[UUID_STRING_SIZE]);
93
94 /**
95  * Convert a C style string to a UUID based on RFC 4122
96  *
97  * @param[in] uuidString
98  *              a 37 byte length string to fill with the string
99  *              representation of the passed UUID.
100  * @param[out]  uuid
101  *              The 16 byte array filled with UUID data
102  * @retval true for success, otherwise false and an error is logged
103  */
104 bool OCConvertStringToUuid(const char uuidString[UUID_STRING_SIZE],
105                                          uint8_t uuid[UUID_SIZE]);
106
107 /**
108  * Check if the provided uuid is valid.
109  * 1. The length of uuids should always be 36.
110  * 2. Hyphens are expected at positions {9, 14, 19, 24}.
111  * 3. The rest charcters should be simple xdigits.
112  *
113  * @param[in] uuid    uuid extracted from URI
114  *
115  * @retval true for success, otherwise false and an error is logged
116  */
117 bool OCIsUUID(const char *uuid);
118
119 #ifdef __cplusplus
120 }
121 #endif
122
123 #endif // OC_RANDOM_H