URIs and addresses. More...

Classes
class	EndpointUri
	Network endpoint URI. More...

class	endpoint_uri_to_str
	Convert EndpointUri to string. More...

class	IoUri
	Audio file or device URI. More...

class	io_uri_to_str
	Convert IoUri to string. More...

struct	ProtocolAttrs
	Protocol attributes. More...

class	ProtocolMap
	Protocol attributes map. More...

class	socket_addr_to_str
	Convert network address to string. More...

class	SocketAddr
	Socket address. More...

Enumerations
enum	AddrFamily { Family_Unknown = 0 , Family_IPv4 , Family_IPv6 }
	Address family. More...

enum	Interface { Iface_Invalid , Iface_Consolidated , Iface_AudioSource , Iface_AudioRepair , Iface_AudioControl , Iface_Max }
	Interface ID. More...

enum	PctMode { PctNonUnreserved , PctNonHost , PctNonPath }
	Percent-encoding mode. More...

enum	Protocol { Proto_None , Proto_RTSP , Proto_RTP , Proto_RTP_RS8M_Source , Proto_RS8M_Repair , Proto_RTP_LDPC_Source , Proto_LDPC_Repair , Proto_RTCP }
	Protocol ID. More...

Functions
const char *	addr_family_to_str (AddrFamily family)
	Convert address family to string. More...

ROC_ATTR_NODISCARD bool	parse_endpoint_uri (const char *str, EndpointUri::Subset subset, EndpointUri &result)
	Parse EndpointUri from string. More...

ROC_ATTR_NODISCARD bool	format_endpoint_uri (const EndpointUri &uri, EndpointUri::Subset subset, core::StringBuilder &dst)
	Format EndpointUri to string. More...

const char *	interface_to_str (Interface)
	Get string name of the interface. More...

bool	parse_io_uri (const char *str, IoUri &result)
	Parse IoUri from string. More...

bool	format_io_uri (const IoUri &uri, core::StringBuilder &dst)
	Format IoUri to string. More...

ROC_ATTR_NODISCARD bool	parse_socket_addr (const char *host, int port, SocketAddr &addr)
	Parse socket address (host and port). More...

ROC_ATTR_NODISCARD bool	pct_encode (core::StringBuilder &dst, const char *src, size_t src_sz, PctMode mode)
	Percent-encode an UTF-8 string. More...

ROC_ATTR_NODISCARD bool	pct_decode (core::StringBuilder &dst, const char *src, size_t src_sz)
	Percent-decode an UTF-8 string. More...

ROC_ATTR_NODISCARD bool	print_supported (ProtocolMap &, core::IArena &)
	Print supported interfaces and protocols. More...

const char *	proto_to_str (Protocol proto)
	Get string name of the protocol. More...

Detailed Description

URIs and addresses.

Enumeration Type Documentation

◆ AddrFamily

enum roc::address::AddrFamily

Address family.

Enumerator
Family_Unknown	Invalid.
Family_IPv4	IPv4.
Family_IPv6	IPv6.

Definition at line 19 of file addr_family.h.

◆ Interface

enum roc::address::Interface

Interface ID.

Enumerator
Iface_Invalid	Invalid interface.
Iface_Consolidated	Interface that consolidated all types of streams (e.g. RTSP).
Iface_AudioSource	Source packets of audio stream (e.g. RTP or RTP + RS8M).
Iface_AudioRepair	Repair packets of audio stream (e.g. RS8M).
Iface_AudioControl	Control packets of audio stream (e.g. RTCP).
Iface_Max	Number of interfaces.

Definition at line 19 of file interface.h.

◆ PctMode

enum roc::address::PctMode

Percent-encoding mode.

Enumerator
PctNonUnreserved	Percent-encode all symbols that are not unreserved.
PctNonHost	Percent-encode all symbols that are not allowed in host.
PctNonPath	Percent-encode all symbols that are not allowed in path.

Definition at line 23 of file pct.h.

◆ Protocol

enum roc::address::Protocol

Protocol ID.

Enumerator
Proto_None	Protocol is not set.
Proto_RTSP	RTSP.
Proto_RTP	Bare RTP.
Proto_RTP_RS8M_Source	RTP source packet + FECFRAME Reed-Solomon footer (m=8).
Proto_RS8M_Repair	FEC repair packet + FECFRAME Reed-Solomon header (m=8).
Proto_RTP_LDPC_Source	RTP source packet + FECFRAME LDPC footer.
Proto_LDPC_Repair	FEC repair packet + FECFRAME LDPC header.
Proto_RTCP	RTCP.

Definition at line 19 of file protocol.h.

Function Documentation

◆ addr_family_to_str()

const char* roc::address::addr_family_to_str ( AddrFamily family )

Convert address family to string.

◆ format_endpoint_uri()

ROC_ATTR_NODISCARD bool roc::address::format_endpoint_uri	(	const EndpointUri &	uri,
		EndpointUri::Subset	subset,
		core::StringBuilder &	dst
	)

Format EndpointUri to string.

Formats a normalized form of the URI.

The path and host parts of the URI are percent-encoded if necessary. The query field is stored in the encoded form, so it is just copied as is.

Returns: true on success or false if the buffer is too small.

◆ format_io_uri()

bool roc::address::format_io_uri	(	const IoUri &	uri,
		core::StringBuilder &	dst
	)

Format IoUri to string.

Formats a normalized form of the URI.

The path part of the URI is percent-encoded if necessary.

This function always uses the "file:" form (without "//") for files because this is the only form that supports both absolute and relative paths.

Returns: true on success or false if the buffer is too small.

◆ interface_to_str()

const char* roc::address::interface_to_str ( Interface )

Get string name of the interface.

◆ parse_endpoint_uri()

ROC_ATTR_NODISCARD bool roc::address::parse_endpoint_uri	(	const char *	str,
		EndpointUri::Subset	subset,
		EndpointUri &	result
	)

Parse EndpointUri from string.

The URI should be in the following form:

PROTOCOL://HOST[:PORT][/PATH][?QUERY]

Examples:

rtp+rs8m://localhost
rtsp://localhost:123/path?query
rtp://127.0.0.1:123
rtp://[::1]:123

The URI syntax is defined by RFC 3986.

The path and query fields are allowed only for some protocols.

The port field can be omitted if the protocol have standard port. Otherwise, the port can not be omitted.

The path and host fields of the URI are percent-decoded. (But the set of allowed unencoded characters is different for path and host).

The query fields of the URI is kept as is. The user is responsible to percent-decode it when necessary.

This parser does not try to perform full URI validation. For example, it does not check that path contains only allowed symbols. If it can be parsed, it will be.

◆ parse_io_uri()

bool roc::address::parse_io_uri	(	const char *	str,
		IoUri &	result
	)

Parse IoUri from string.

The URI should be in one of the following forms:

DEVICE_TYPE://DEVICE_NAME (audio device)
file:///ABS/PATH (file, absolute path)
file://localhost/ABS/PATH (equivalent to the above)
file:/ABS/PATH (equivalent to the above)
file:REL/PATH (file, relative path)
file://- (stdin or stdout)
file:- (equivalent to the above)

Where:

DEVICE_TYPE specifies the audio system name, e.g. "alsa" or "pulse"
DEVICE_NAME specifies the audio device name, e.g. ALSA card name
/ABS/PATH specifies an absolute file path
REL/PATH specifies a relative file path

Examples:

The URI syntax is defined by RFC 8089 and RFC 3986.

The path part of the URI is percent-decoded.

The RFC allows usages of file:// URIs both for local and remote files. Local files should use either empty or special "localhost" hostname. This parser only recognizes these two variants; other hostnames will be considered as a parsing error.

The RFC allows only absolute paths in file:// URIs. This parser additionally allows relative paths, but only in the "file:" form (without "//"). Relative paths are not allowed in the "file://" form (with "//") because it would lead to an ambiguity.

This parser also allows a non-standard "-" path for stdin/stdout.

This parser does not try to perform full URI validation. For example, it does not check that path contains only allowed symbols. If it can be parsed, it will be.

◆ parse_socket_addr()

ROC_ATTR_NODISCARD bool roc::address::parse_socket_addr	(	const char *	host,
		int	port,
		SocketAddr &	addr
	)

Parse socket address (host and port).

Remarks

The host string should be in one of the following forms:

"IPv4" e.g. "1.2.3.4"
"[IPv6]" e.g. "[::1]"

Returns: false if host can't be parsed.

◆ pct_decode()

ROC_ATTR_NODISCARD bool roc::address::pct_decode	(	core::StringBuilder &	dst,
		const char *	src,
		size_t	src_sz
	)

Percent-decode an UTF-8 string.

Parameters

dst - destination buffer
src - source string in UTF-8
src_sz - source string size

Remarks: The source string should NOT be null-terminated. The source string size should NOT include the terminating zero byte.

◆ pct_encode()

ROC_ATTR_NODISCARD bool roc::address::pct_encode	(	core::StringBuilder &	dst,
		const char *	src,
		size_t	src_sz,
		PctMode	mode
	)

Percent-encode an UTF-8 string.