FFmpeg
uuid.h
Go to the documentation of this file.
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  */
110 void av_uuid_unparse(const AVUUID uu, char *out);
111 
112 /**
113  * Compares two UUIDs for equality.
114  *
115  * @param[in] uu1 AVUUID
116  * @param[in] uu2 AVUUID
117  * @return Nonzero if uu1 and uu2 are identical, 0 otherwise
118  */
119 static inline int av_uuid_equal(const AVUUID uu1, const AVUUID uu2)
120 {
121  return memcmp(uu1, uu2, AV_UUID_LEN) == 0;
122 }
123 
124 /**
125  * Copies the bytes of src into dest.
126  *
127  * @param[out] dest AVUUID
128  * @param[in] src AVUUID
129  */
130 static inline void av_uuid_copy(AVUUID dest, const AVUUID src)
131 {
132  memcpy(dest, src, AV_UUID_LEN);
133 }
134 
135 /**
136  * Sets a UUID to the nil UUID, i.e. a UUID with have all
137  * its 128 bits set to zero.
138  *
139  * @param[in,out] uu UUID to be set to the nil UUID
140  */
141 static inline void av_uuid_nil(AVUUID uu)
142 {
143  memset(uu, 0, AV_UUID_LEN);
144 }
145 
146 #endif /* AVUTIL_UUID_H */
AVUUID
uint8_t AVUUID[AV_UUID_LEN]
Definition: uuid.h:60
out
FILE * out
Definition: movenc.c:55
av_uuid_urn_parse
int av_uuid_urn_parse(const char *in, AVUUID uu)
Parses a URN representation of a UUID, as specified at IETF RFC 4122, into an AVUUID.
Definition: uuid.c:135
AV_UUID_LEN
#define AV_UUID_LEN
Definition: uuid.h:57
av_uuid_nil
static void av_uuid_nil(AVUUID uu)
Sets a UUID to the nil UUID, i.e.
Definition: uuid.h:141
av_uuid_equal
static int av_uuid_equal(const AVUUID uu1, const AVUUID uu2)
Compares two UUIDs for equality.
Definition: uuid.h:119
av_uuid_parse_range
int av_uuid_parse_range(const char *in_start, const char *in_end, AVUUID uu)
Parses a string representation of a UUID formatted according to IETF RFC 4122 into an AVUUID.
Definition: uuid.c:88
av_uuid_parse
int av_uuid_parse(const char *in, AVUUID uu)
Parses a string representation of a UUID formatted according to IETF RFC 4122 into an AVUUID.
Definition: uuid.c:67
av_uuid_copy
static void av_uuid_copy(AVUUID dest, const AVUUID src)
Copies the bytes of src into dest.
Definition: uuid.h:130
src
#define src
Definition: vp8dsp.c:248
av_uuid_unparse
void av_uuid_unparse(const AVUUID uu, char *out)
Serializes a AVUUID into a string representation according to IETF RFC 4122.
Definition: uuid.c:117