Roc Toolkit internal modules
Roc Toolkit: real-time audio streaming
io_uri.h File Reference

Audio file or device URI. More...

#include "roc_core/stddefs.h"
Include dependency graph for io_uri.h:
This graph shows which files directly or indirectly include this file:

Go to the source code of this file.


struct  roc::address::IoURI
 Audio file or device URI. More...


 Root namespace.


bool roc::address::parse_io_uri (const char *str, IoURI &result)
 Parse IoURI from string. More...
bool roc::address::format_io_uri (const IoURI &uri, char *buf, size_t buf_size)
 Format IoURI to string. More...

Detailed Description

Audio file or device URI.

Definition in file io_uri.h.

Function Documentation

bool roc::address::format_io_uri ( const IoURI uri,
char *  buf,
size_t  buf_size 

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.

true on success or false if the buffer is too small.
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 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


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.