[1] | 1 | /** @file
|
---|
[8245] | 2 | * IPRT - Universal Unique Identifiers (UUID).
|
---|
[1] | 3 | */
|
---|
| 4 |
|
---|
| 5 | /*
|
---|
[76553] | 6 | * Copyright (C) 2006-2019 Oracle Corporation
|
---|
[1] | 7 | *
|
---|
| 8 | * This file is part of VirtualBox Open Source Edition (OSE), as
|
---|
| 9 | * available from http://www.virtualbox.org. This file is free software;
|
---|
| 10 | * you can redistribute it and/or modify it under the terms of the GNU
|
---|
[5999] | 11 | * General Public License (GPL) as published by the Free Software
|
---|
| 12 | * Foundation, in version 2 as it comes in the "COPYING" file of the
|
---|
| 13 | * VirtualBox OSE distribution. VirtualBox OSE is distributed in the
|
---|
| 14 | * hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
|
---|
| 15 | *
|
---|
| 16 | * The contents of this file may alternatively be used under the terms
|
---|
| 17 | * of the Common Development and Distribution License Version 1.0
|
---|
| 18 | * (CDDL) only, as it comes in the "COPYING.CDDL" file of the
|
---|
| 19 | * VirtualBox OSE distribution, in which case the provisions of the
|
---|
| 20 | * CDDL are applicable instead of those of the GPL.
|
---|
| 21 | *
|
---|
| 22 | * You may elect to license modified versions of this file under the
|
---|
| 23 | * terms and conditions of either the GPL or the CDDL or both.
|
---|
[1] | 24 | */
|
---|
| 25 |
|
---|
[76557] | 26 | #ifndef IPRT_INCLUDED_uuid_h
|
---|
| 27 | #define IPRT_INCLUDED_uuid_h
|
---|
[76507] | 28 | #ifndef RT_WITHOUT_PRAGMA_ONCE
|
---|
| 29 | # pragma once
|
---|
| 30 | #endif
|
---|
[1] | 31 |
|
---|
| 32 | #include <iprt/cdefs.h>
|
---|
| 33 | #include <iprt/types.h>
|
---|
| 34 |
|
---|
[20374] | 35 | RT_C_DECLS_BEGIN
|
---|
[1] | 36 |
|
---|
| 37 | /** @defgroup grp_rt_uuid RTUuid - Universally Unique Identifiers
|
---|
| 38 | * @ingroup grp_rt
|
---|
| 39 | * @{
|
---|
| 40 | */
|
---|
| 41 |
|
---|
| 42 | /**
|
---|
| 43 | * Generates new UUID value.
|
---|
| 44 | *
|
---|
[11413] | 45 | * @note IPRT uses little endian byte ordering in the UUID integer fields. If
|
---|
| 46 | * you want to pass IPRT UUIDs in binary representation to other UUID libraries
|
---|
| 47 | * and expect to get exactly the same string representation as in IPRT, you
|
---|
| 48 | * need to convert the first three integer fields (one 32 bit value, two 16 bit
|
---|
| 49 | * values) separately to big endian (also called network byte order).
|
---|
| 50 | *
|
---|
| 51 | * @sa RTUUID::Gen
|
---|
| 52 | *
|
---|
[1] | 53 | * @returns iprt status code.
|
---|
| 54 | * @param pUuid Where to store generated uuid.
|
---|
| 55 | */
|
---|
[204] | 56 | RTDECL(int) RTUuidCreate(PRTUUID pUuid);
|
---|
[1] | 57 |
|
---|
| 58 | /**
|
---|
| 59 | * Makes null UUID value.
|
---|
| 60 | *
|
---|
| 61 | * @returns iprt status code.
|
---|
| 62 | * @param pUuid Where to store generated null uuid.
|
---|
| 63 | */
|
---|
[204] | 64 | RTDECL(int) RTUuidClear(PRTUUID pUuid);
|
---|
[1] | 65 |
|
---|
| 66 | /**
|
---|
| 67 | * Checks if UUID is null.
|
---|
| 68 | *
|
---|
| 69 | * @returns true if UUID is null.
|
---|
| 70 | * @param pUuid uuid to check.
|
---|
| 71 | */
|
---|
[9738] | 72 | RTDECL(bool) RTUuidIsNull(PCRTUUID pUuid);
|
---|
[1] | 73 |
|
---|
| 74 | /**
|
---|
| 75 | * Compares two UUID values.
|
---|
| 76 | *
|
---|
| 77 | * @returns 0 if eq, < 0 or > 0.
|
---|
[25645] | 78 | * @param pUuid1 First value to compare. NULL is treated like if
|
---|
| 79 | * RTUuidIsNull() return true.
|
---|
| 80 | * @param pUuid2 Second value to compare. NULL is treated like if
|
---|
| 81 | * RTUuidIsNull() return true.
|
---|
[1] | 82 | */
|
---|
[204] | 83 | RTDECL(int) RTUuidCompare(PCRTUUID pUuid1, PCRTUUID pUuid2);
|
---|
[1] | 84 |
|
---|
| 85 | /**
|
---|
[9738] | 86 | * Compares a UUID value with a UUID string.
|
---|
| 87 | *
|
---|
[11413] | 88 | * @note IPRT uses little endian byte ordering in the UUID integer fields. If
|
---|
| 89 | * you want to pass IPRT UUIDs in binary representation to other UUID libraries
|
---|
[25645] | 90 | * and expect to get exactly the same string representation as in IPRT, you need
|
---|
| 91 | * to convert the first three integer fields (one 32 bit value, two 16 bit
|
---|
[11413] | 92 | * values) separately to big endian (also called network byte order).
|
---|
| 93 | * Correspondingly, if you want to get the right result with UUIDs which are in
|
---|
| 94 | * big endian format, you need to convert them before using this function.
|
---|
| 95 | *
|
---|
| 96 | * @sa RTUUID::Gen
|
---|
| 97 | *
|
---|
[9738] | 98 | * @returns 0 if eq, < 0 or > 0.
|
---|
[25645] | 99 | * @param pUuid1 First value to compare. NULL is not allowed.
|
---|
[25961] | 100 | * @param pszString2 The 2nd UUID in string form. NULL or malformed
|
---|
[25645] | 101 | * string is not permitted.
|
---|
[9738] | 102 | */
|
---|
[25961] | 103 | RTDECL(int) RTUuidCompareStr(PCRTUUID pUuid1, const char *pszString2);
|
---|
[9738] | 104 |
|
---|
| 105 | /**
|
---|
[25961] | 106 | * Compares two UUID strings.
|
---|
| 107 | *
|
---|
| 108 | * @returns 0 if eq, < 0 or > 0.
|
---|
| 109 | * @param pszString1 The 1st UUID in string from. NULL or malformed
|
---|
| 110 | * string is not permitted.
|
---|
| 111 | * @param pszString2 The 2nd UUID in string form. NULL or malformed
|
---|
| 112 | * string is not permitted.
|
---|
| 113 | */
|
---|
| 114 | RTDECL(int) RTUuidCompare2Strs(const char *pszString1, const char *pszString2);
|
---|
| 115 |
|
---|
| 116 | /**
|
---|
[1] | 117 | * Converts binary UUID to its string representation.
|
---|
| 118 | *
|
---|
[11413] | 119 | * @note IPRT uses little endian byte ordering in the UUID integer fields. If
|
---|
| 120 | * you want to pass IPRT UUIDs in binary representation to other UUID libraries
|
---|
| 121 | * and expect to get exactly the same string representation as in IPRT, you
|
---|
| 122 | * need to convert the first three integer fields (one 32 bit value, two 16 bit
|
---|
| 123 | * values) separately to big endian (also called network byte order).
|
---|
| 124 | * Correspondingly, if you want to get the right result with UUIDs which are in
|
---|
| 125 | * big endian format, you need to convert them before using this function.
|
---|
| 126 | *
|
---|
| 127 | * @sa RTUUID::Gen
|
---|
| 128 | *
|
---|
[1] | 129 | * @returns iprt status code.
|
---|
| 130 | * @param pUuid Uuid to convert.
|
---|
| 131 | * @param pszString Where to store result string.
|
---|
| 132 | * @param cchString pszString buffer length, must be >= RTUUID_STR_LENGTH.
|
---|
| 133 | */
|
---|
[9738] | 134 | RTDECL(int) RTUuidToStr(PCRTUUID pUuid, char *pszString, size_t cchString);
|
---|
[1] | 135 |
|
---|
| 136 | /**
|
---|
| 137 | * Converts UUID from its string representation to binary format.
|
---|
| 138 | *
|
---|
[11413] | 139 | * @note IPRT uses little endian byte ordering in the UUID integer fields. If
|
---|
| 140 | * you want to pass IPRT UUIDs in binary representation to other UUID libraries
|
---|
| 141 | * and expect to get exactly the same string representation as in IPRT, you
|
---|
| 142 | * need to convert the first three integer fields (one 32 bit value, two 16 bit
|
---|
| 143 | * values) separately to big endian (also called network byte order).
|
---|
| 144 | * Correspondingly, if you want to get the right result with UUIDs which are in
|
---|
| 145 | * big endian format, you need to convert them before using this function.
|
---|
| 146 | *
|
---|
| 147 | * @sa RTUUID::Gen
|
---|
| 148 | *
|
---|
[1] | 149 | * @returns iprt status code.
|
---|
| 150 | * @param pUuid Where to store result Uuid.
|
---|
| 151 | * @param pszString String with UUID text data.
|
---|
| 152 | */
|
---|
[204] | 153 | RTDECL(int) RTUuidFromStr(PRTUUID pUuid, const char *pszString);
|
---|
[1] | 154 |
|
---|
[19198] | 155 | /**
|
---|
| 156 | * Converts binary UUID to its UTF-16 string representation.
|
---|
| 157 | *
|
---|
| 158 | * @note See note in RTUuidToStr.
|
---|
| 159 | *
|
---|
| 160 | * @sa RTUUID::Gen
|
---|
| 161 | *
|
---|
| 162 | * @returns iprt status code.
|
---|
| 163 | * @param pUuid Uuid to convert.
|
---|
| 164 | * @param pwszString Where to store result string.
|
---|
| 165 | * @param cwcString pszString buffer length, must be >=
|
---|
| 166 | * RTUUID_STR_LENGTH.
|
---|
| 167 | */
|
---|
| 168 | RTDECL(int) RTUuidToUtf16(PCRTUUID pUuid, PRTUTF16 pwszString, size_t cwcString);
|
---|
| 169 |
|
---|
| 170 | /**
|
---|
| 171 | * Converts UUID from its UTF-16 string representation to binary format.
|
---|
| 172 | *
|
---|
| 173 | * @note See note in RTUuidFromStr.
|
---|
| 174 | *
|
---|
| 175 | * @sa RTUUID::Gen
|
---|
| 176 | *
|
---|
| 177 | * @returns iprt status code.
|
---|
| 178 | * @param pUuid Where to store result Uuid.
|
---|
| 179 | * @param pwszString String with UUID text data.
|
---|
| 180 | */
|
---|
| 181 | RTDECL(int) RTUuidFromUtf16(PRTUUID pUuid, PCRTUTF16 pwszString);
|
---|
| 182 |
|
---|
[1] | 183 | /** @} */
|
---|
| 184 |
|
---|
[20374] | 185 | RT_C_DECLS_END
|
---|
[1] | 186 |
|
---|
[76585] | 187 | #endif /* !IPRT_INCLUDED_uuid_h */
|
---|
[1] | 188 |
|
---|