1 /*
2 * Copyright (c) 2022 Pierre-Anthony Lemieux <pal@palemieux.com>
3 * Zane van Iperen <zane@zanevaniperen.com>
4 *
5 * This file is part of FFmpeg.
6 *
7 * FFmpeg is free software; you can redistribute it and/or
8 * modify it under the terms of the GNU Lesser General Public
9 * License as published by the Free Software Foundation; either
10 * version 2.1 of the License, or (at your option) any later version.
11 *
12 * FFmpeg is distributed in the hope that it will be useful,
13 * but WITHOUT ANY WARRANTY; without even the implied warranty of
14 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
15 * Lesser General Public License for more details.
16 *
17 * You should have received a copy of the GNU Lesser General Public
18 * License along with FFmpeg; if not, write to the Free Software
19 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
20 */
21
22 /**
23 * @file
24 * UUID parsing and serialization utilities.
25 * The library treats the UUID as an opaque sequence of 16 unsigned bytes,
26 * i.e. ignoring the internal layout of the UUID, which depends on the type
27 * of the UUID.
28 *
29 * @author Pierre-Anthony Lemieux <pal@palemieux.com>
30 * @author Zane van Iperen <zane@zanevaniperen.com>
31 */
32
33 #ifndef AVUTIL_UUID_H
34 #define AVUTIL_UUID_H
35
36 #include <stdint.h>
37 #include <string.h>
38
39 #define AV_PRI_UUID \
40 "%02hhx%02hhx%02hhx%02hhx-%02hhx%02hhx-" \
41 "%02hhx%02hhx-%02hhx%02hhx-%02hhx%02hhx%02hhx%02hhx%02hhx%02hhx"
42
43 #define AV_PRI_URN_UUID \
44 "urn:uuid:%02hhx%02hhx%02hhx%02hhx-%02hhx%02hhx-" \
45 "%02hhx%02hhx-%02hhx%02hhx-%02hhx%02hhx%02hhx%02hhx%02hhx%02hhx"
46
47 /* AV_UUID_ARG() is used together with AV_PRI_UUID() or AV_PRI_URN_UUID
48 * to print UUIDs, e.g.
49 * av_log(NULL, AV_LOG_DEBUG, "UUID: " AV_PRI_UUID, AV_UUID_ARG(uuid));
50 */
51 #define AV_UUID_ARG(x) \
52 (x)[ 0], (x)[ 1], (x)[ 2], (x)[ 3], \
53 (x)[ 4], (x)[ 5], (x)[ 6], (x)[ 7], \
54 (x)[ 8], (x)[ 9], (x)[10], (x)[11], \
55 (x)[12], (x)[13], (x)[14], (x)[15]
56
57 #define AV_UUID_LEN 16
58
59 /* Binary representation of a UUID */
60 typedef uint8_t AVUUID[AV_UUID_LEN];
61
62 /**
63 * Parses a string representation of a UUID formatted according to IETF RFC 4122
64 * into an AVUUID. The parsing is case-insensitive. The string must be 37
65 * characters long, including the terminating NUL character.
66 *
67 * Example string representation: "2fceebd0-7017-433d-bafb-d073a7116696"
68 *
69 * @param[in] in String representation of a UUID,
70 * e.g. 2fceebd0-7017-433d-bafb-d073a7116696
71 * @param[out] uu AVUUID
72 * @return A non-zero value in case of an error.
73 */
74 int av_uuid_parse(const char *in, AVUUID uu);
75
76 /**
77 * Parses a URN representation of a UUID, as specified at IETF RFC 4122,
78 * into an AVUUID. The parsing is case-insensitive. The string must be 46
79 * characters long, including the terminating NUL character.
80 *
81 * Example string representation: "urn:uuid:2fceebd0-7017-433d-bafb-d073a7116696"
82 *
83 * @param[in] in URN UUID
84 * @param[out] uu AVUUID
85 * @return A non-zero value in case of an error.
86 */
87 int av_uuid_urn_parse(const char *in, AVUUID uu);
88
89 /**
90 * Parses a string representation of a UUID formatted according to IETF RFC 4122
91 * into an AVUUID. The parsing is case-insensitive.
92 *
93 * @param[in] in_start Pointer to the first character of the string representation
94 * @param[in] in_end Pointer to the character after the last character of the
95 * string representation. That memory location is never
96 * accessed. It is an error if `in_end - in_start != 36`.
97 * @param[out] uu AVUUID
98 * @return A non-zero value in case of an error.
99 */
100 int av_uuid_parse_range(const char *in_start, const char *in_end, AVUUID uu);
101
102 /**
103 * Serializes a AVUUID into a string representation according to IETF RFC 4122.
104 * The string is lowercase and always 37 characters long, including the
105 * terminating NUL character.
106 *
107 * @param[in] uu AVUUID
108 * @param[out] out Pointer to an array of no less than 37 characters.
109 * @return A non-zero value in case of an error.
110 */
111 void av_uuid_unparse(const AVUUID uu, char *out);
112
113 /**
114 * Compares two UUIDs for equality.
115 *
116 * @param[in] uu1 AVUUID
117 * @param[in] uu2 AVUUID
118 * @return Nonzero if uu1 and uu2 are identical, 0 otherwise
119 */
av_uuid_equal(const AVUUID uu1,const AVUUID uu2)120 static inline int av_uuid_equal(const AVUUID uu1, const AVUUID uu2)
121 {
122 return memcmp(uu1, uu2, AV_UUID_LEN) == 0;
123 }
124
125 /**
126 * Copies the bytes of src into dest.
127 *
128 * @param[out] dest AVUUID
129 * @param[in] src AVUUID
130 */
av_uuid_copy(AVUUID dest,const AVUUID src)131 static inline void av_uuid_copy(AVUUID dest, const AVUUID src)
132 {
133 memcpy(dest, src, AV_UUID_LEN);
134 }
135
136 /**
137 * Sets a UUID to the nil UUID, i.e. a UUID with have all
138 * its 128 bits set to zero.
139 *
140 * @param[in,out] uu UUID to be set to the nil UUID
141 */
av_uuid_nil(AVUUID uu)142 static inline void av_uuid_nil(AVUUID uu)
143 {
144 memset(uu, 0, AV_UUID_LEN);
145 }
146
147 #endif /* AVUTIL_UUID_H */
148