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 Streaming 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/attributes.h"
16 #include "roc_core/noncopyable.h"
17 #include "roc_core/stddefs.h"
18 #include "roc_core/string_buffer.h"
20 
21 namespace roc {
22 namespace address {
23 
24 //! Audio file or device URI.
25 class IoUri : public core::NonCopyable<> {
26 public:
27  //! Initialize empty URI.
28  explicit IoUri(core::IArena&);
29 
30  //! Returns true if the URI has all required fields (scheme and path).
31  bool is_valid() const;
32 
33  //! Returns true if the scheme is "file".
34  bool is_file() const;
35 
36  //! Returns true if the scheme is "file" and the path is "-".
37  bool is_special_file() const;
38 
39  //! Clear all fields.
40  void clear();
41 
42  //! URI scheme.
43  //! May be "file" or device type, e.g. "alsa".
44  const char* scheme() const;
45 
46  //! Set URI scheme.
47  //! String should not be zero-terminated.
48  ROC_ATTR_NODISCARD bool set_scheme(const char* str, size_t str_len);
49 
50  //! URI path.
51  //! May be device name or file path depending on scheme.
52  const char* path() const;
53 
54  //! Set URI path.
55  //! String should be percent-encoded.
56  //! String should not be zero-terminated.
57  ROC_ATTR_NODISCARD bool set_encoded_path(const char* str, size_t str_len);
58 
59  //! Get URI path.
60  //! String will be percent-encoded.
62 
63 private:
64  core::StringBuffer scheme_;
65  core::StringBuffer path_;
66 };
67 
68 //! Parse IoUri from string.
69 //!
70 //! The URI should be in one of the following forms:
71 //!
72 //! - DEVICE_TYPE://DEVICE_NAME (audio device)
73 //!
74 //! - file:///ABS/PATH (file, absolute path)
75 //! - file://localhost/ABS/PATH (equivalent to the above)
76 //! - file:/ABS/PATH (equivalent to the above)
77 //!
78 //! - file:REL/PATH (file, relative path)
79 //!
80 //! - file://- (stdin or stdout)
81 //! - file:- (equivalent to the above)
82 //!
83 //! Where:
84 //! - DEVICE_TYPE specifies the audio system name, e.g. "alsa" or "pulse"
85 //! - DEVICE_NAME specifies the audio device name, e.g. ALSA card name
86 //! - /ABS/PATH specifies an absolute file path
87 //! - REL/PATH specifies a relative file path
88 //!
89 //! Examples:
90 //! - alsa://card0
91 //! - file:///home/user/somefile.wav
92 //! - file://localhost/home/user/somefile.wav
93 //! - file:/home/user/somefile.wav
94 //! - file:./somefile.wav
95 //! - file:somefile.wav
96 //! - file://-
97 //! - file:-
98 //!
99 //! The URI syntax is defined by RFC 8089 and RFC 3986.
100 //!
101 //! The path part of the URI is percent-decoded.
102 //!
103 //! The RFC allows usages of file:// URIs both for local and remote files. Local files
104 //! should use either empty or special "localhost" hostname. This parser only recognizes
105 //! these two variants; other hostnames will be considered as a parsing error.
106 //!
107 //! The RFC allows only absolute paths in file:// URIs. This parser additionally allows
108 //! relative paths, but only in the "file:" form (without "//"). Relative paths are not
109 //! allowed in the "file://" form (with "//") because it would lead to an ambiguity.
110 //!
111 //! This parser also allows a non-standard "-" path for stdin/stdout.
112 //!
113 //! This parser does not try to perform full URI validation. For example, it does not
114 //! check that path contains only allowed symbols. If it can be parsed, it will be.
115 bool parse_io_uri(const char* str, IoUri& result);
116 
117 //! Format IoUri to string.
118 //!
119 //! Formats a normalized form of the URI.
120 //!
121 //! The path part of the URI is percent-encoded if necessary.
122 //!
123 //! This function always uses the "file:" form (without "//") for files because this is
124 //! the only form that supports both absolute and relative paths.
125 //!
126 //! @returns
127 //! true on success or false if the buffer is too small.
128 bool format_io_uri(const IoUri& uri, core::StringBuilder& dst);
129 
130 } // namespace address
131 } // namespace roc
132 
133 #endif // ROC_ADDRESS_IO_URI_H_
Compiler attributes.
#define ROC_ATTR_NODISCARD
Emit warning if function result is not checked.
Definition: attributes.h:31
Audio file or device URI.
Definition: io_uri.h:25
ROC_ATTR_NODISCARD bool format_encoded_path(core::StringBuilder &dst) const
Get URI path. String will be percent-encoded.
bool is_special_file() const
Returns true if the scheme is "file" and the path is "-".
bool is_file() const
Returns true if the scheme is "file".
void clear()
Clear all fields.
IoUri(core::IArena &)
Initialize empty URI.
bool is_valid() const
Returns true if the URI has all required fields (scheme and path).
ROC_ATTR_NODISCARD bool set_encoded_path(const char *str, size_t str_len)
Set URI path. String should be percent-encoded. String should not be zero-terminated.
ROC_ATTR_NODISCARD bool set_scheme(const char *str, size_t str_len)
Set URI scheme. String should not be zero-terminated.
const char * scheme() const
URI scheme. May be "file" or device type, e.g. "alsa".
const char * path() const
URI path. May be device name or file path depending on scheme.
Memory arena interface.
Definition: iarena.h:23
Base class for non-copyable objects.
Definition: noncopyable.h:23
bool parse_io_uri(const char *str, IoUri &result)
Parse IoUri from string.
bool format_io_uri(const IoUri &uri, core::StringBuilder &dst)
Format IoUri to string.
Root namespace.
Non-copyable object.
Commonly used types and functions.
String buffer.
String builder.