VirtualBox

source: vbox/trunk/include/iprt/uuid.h@ 103224

Last change on this file since 103224 was 98103, checked in by vboxsync, 21 months ago

Copyright year updates by scm.

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

© 2024 Oracle Support Privacy / Do Not Sell My Info Terms of Use Trademark Policy Automated Access Etiquette