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