FFmpeg 5.1.6
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 */
60typedef 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 */
74int 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 */
87int 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 */
100int 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 */
111void 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 */
120static 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 */
131static 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 */
142static inline void av_uuid_nil(AVUUID uu)
143{
144 memset(uu, 0, AV_UUID_LEN);
145}
146
147#endif /* AVUTIL_UUID_H */
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.
static void av_uuid_copy(AVUUID dest, const AVUUID src)
Copies the bytes of src into dest.
Definition: uuid.h:131
static int av_uuid_equal(const AVUUID uu1, const AVUUID uu2)
Compares two UUIDs for equality.
Definition: uuid.h:120
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.
#define AV_UUID_LEN
Definition: uuid.h:57
static void av_uuid_nil(AVUUID uu)
Sets a UUID to the nil UUID, i.e.
Definition: uuid.h:142
void av_uuid_unparse(const AVUUID uu, char *out)
Serializes a AVUUID into a string representation according to IETF RFC 4122.
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.
uint8_t AVUUID[AV_UUID_LEN]
Definition: uuid.h:60