Roc Toolkit internal modules
Roc Toolkit: real-time audio streaming
io_uri.h
Go to the documentation of this file.
1 /*
2  * Copyright (c) 2019 Roc authors
3  *
4  * This Source Code Form is subject to the terms of the Mozilla Public
5  * License, v. 2.0. If a copy of the MPL was not distributed with this
6  * file, You can obtain one at http://mozilla.org/MPL/2.0/.
7  */
8 
9 //! @file roc_address/io_uri.h
10 //! @brief Audio file or device URI.
11 
12 #ifndef ROC_ADDRESS_IO_URI_H_
13 #define ROC_ADDRESS_IO_URI_H_
14 
15 #include "roc_core/stddefs.h"
16 
17 namespace roc {
18 namespace address {
19 
20 //! Audio file or device URI.
21 struct IoURI {
22  //! Initialize empty URI.
23  IoURI();
24 
25  //! Returns true if the URI is empty.
26  bool is_empty() const;
27 
28  //! Returns true if the scheme is "file".
29  bool is_file() const;
30 
31  //! Returns true if the scheme is "file" and the path is "-".
32  bool is_special_file() const;
33 
34  enum {
35  // An estimate maximum length of encoded URI.
36  MaxLength = 1280
37  };
38 
39  //! URI scheme.
40  //! May be "file" or device type, e.g. "alsa".
41  char scheme[16];
42 
43  //! URI path.
44  //! May be device name or file path depending on scheme.
45  char path[1024];
46 };
47 
48 //! Parse IoURI from string.
49 //!
50 //! The URI should be in one of the following forms:
51 //!
52 //! - DEVICE_TYPE://DEVICE_NAME (audio device)
53 //!
54 //! - file:///ABS/PATH (file, absolute path)
55 //! - file://localhost/ABS/PATH (equivalent to the above)
56 //! - file:/ABS/PATH (equivalent to the above)
57 //!
58 //! - file:REL/PATH (file, relative path)
59 //!
60 //! - file://- (stdin or stdout)
61 //! - file:- (equivalent to the above)
62 //!
63 //! Where:
64 //! - DEVICE_TYPE specifies the audio system name, e.g. "alsa" or "pulse"
65 //! - DEVICE_NAME specifies the audio device name, e.g. ALSA card name
66 //! - /ABS/PATH specifies an absolute file path
67 //! - REL/PATH specifies a relative file path
68 //!
69 //! Examples:
70 //! - alsa://card0
71 //! - file:///home/user/somefile.wav
72 //! - file://localhost/home/user/somefile.wav
73 //! - file:/home/user/somefile.wav
74 //! - file:./somefile.wav
75 //! - file:somefile.wav
76 //! - file://-
77 //! - file:-
78 //!
79 //! The URI syntax is defined by RFC 8089 and RFC 3986.
80 //!
81 //! The path part of the URI is percent-decoded.
82 //!
83 //! The RFC allows usages of file:// URIs both for local and remote files. Local files
84 //! should use either empty or special "localhost" hostname. This parser only recognizes
85 //! these two variants; other hostnames will be considered as a parsing error.
86 //!
87 //! The RFC allows only absolute paths in file:// URIs. This parser additionally allows
88 //! relative paths, but only in the "file:" form (without "//"). Relative paths are not
89 //! allowed in the "file://" form (with "//") because it would lead to an ambiguity.
90 //!
91 //! This parser also allows a non-standard "-" path for stdin/stdout.
92 //!
93 //! This parser does not try to perform full URI validation. For example, it does not
94 //! check that path contains only allowed symbols. If it can be parsed, it will be.
95 bool parse_io_uri(const char* str, IoURI& result);
96 
97 //! Format IoURI to string.
98 //!
99 //! Formats a normalized form of the URI.
100 //!
101 //! The path part of the URI is percent-encoded if necessary.
102 //!
103 //! This function always uses the "file:" form (without "//") for files because this is
104 //! the only form that supports both absolute and relative paths.
105 //!
106 //! @returns
107 //! true on success or false if the buffer is too small.
108 bool format_io_uri(const IoURI& uri, char* buf, size_t buf_size);
109 
110 } // namespace address
111 } // namespace roc
112 
113 #endif // ROC_ADDRESS_IO_URI_H_
Audio file or device URI.
Definition: io_uri.h:21
Root namespace.
bool is_empty() const
Returns true if the URI is empty.
IoURI()
Initialize empty URI.
Commonly used types and functions.
char path[1024]
URI path. May be device name or file path depending on scheme.
Definition: io_uri.h:45
bool parse_io_uri(const char *str, IoURI &result)
Parse IoURI from string.
bool is_file() const
Returns true if the scheme is "file".
char scheme[16]
URI scheme. May be "file" or device type, e.g. "alsa".
Definition: io_uri.h:41
bool format_io_uri(const IoURI &uri, char *buf, size_t buf_size)
Format IoURI to string.
bool is_special_file() const
Returns true if the scheme is "file" and the path is "-".