Url Manual


A maxon::Url defines the location of a file or a similar resource. The class allows to construct a file path and to handle files. maxon::Url is based on maxon::UrlInterface.

To convert a maxon::Url to a Filename use MaxonConvert().


A maxon::Url can be constructed with:

// This example constructs an URL and prints the result to the console.
// start file scheme on drive C
maxon::Url url { "file:///c:"_s };
// add folder
url.Append("folder"_s) iferr_return;
// add file
url = (url + "file.txt"_s)iferr_return;
// print result
DiagnosticOutput("Full URL: @", url);
Definition: url.h:892
#define DiagnosticOutput(formatString,...)
Definition: debugdiagnostics.h:176
#define iferr_return
Definition: resultbase.h:1465

Various default folders can be obtained from the maxon::Application class:

See also Application Manual.


An URL can reference files on the file system, web addresses, files within ZIP files, etc. The scheme defines what kind of object a given maxon::Url is referencing:

The supported maxon::UrlScheme types are:

// This example checks if the given URL contains
// a reference to a file in the file system.
const maxon::Url url { "file:///c:/folder/file.txt"_s };
if (url.GetScheme() == maxon::URLSCHEME_FILESYSTEM)
DiagnosticOutput("URL points to a file in the file system.");
Definition: url.h:659


An maxon::Url is composed of several parts. These parts can be accessed individually:

// This example prints different forms and paths of the given URL to the console.
const maxon::String stringPath = url.GetUrl();
DiagnosticOutput("Full URL: @", stringPath);
const maxon::String systemPath = url.GetSystemPath() iferr_return;
DiagnosticOutput("System Path: @", systemPath);
// get authority and directory; no format statement applied
const maxon::String authority = url.GetAuthority().ToString(nullptr);
const maxon::String directory = url.GetDirectory().ToString(nullptr);
const maxon::String name = url.GetName();
const maxon::String suffix = url.GetSuffix();
DiagnosticOutput("URL Parts: @, @, @, @", authority, directory, name, suffix);
const char const char * name
Definition: abstract.h:195
Definition: string.h:1235

File Functions

The maxon::Url class contains several functions to analyse and handle files:

// This example checks if a given folder exists. If not, the folder is created.
// Finally the folder is opened using the default tool of the OS.
// check if folder does not exit
if (workFolder.IoDetect() == maxon::IODETECT::NONEXISTENT)
// create folder
workFolder.IoCreateDirectory(true) iferr_return;
// show folder
Show the url in the windows explorer or osx finder.
Url doesn't exist.
// This example checks the files of the given folder.
// If a file is of a certain type (suffix "exr") it is moved to a sub-folder.
// check if folder exists
if (renderFolder.IoDetect() != maxon::IODETECT::DIRECTORY)
return maxon::OK;
// create sub-folder
const maxon::Url exrFolder = (renderFolder + "exr"_s)iferr_return;
exrFolder.IoCreateDirectory(true) iferr_return;
// move all *.exr files to sub-folder
for (const auto& it : renderFolder.GetBrowseIterator(maxon::GETBROWSEITERATORFLAGS::NONE))
const maxon::IoBrowseRef& browseDirectory = (it) iferr_return;
const maxon::Url url = browseDirectory.GetCurrentPath();
// check if element is a file
if (url.IoDetect() != maxon::IODETECT::FILE)
// check if *.exr file
if (url.CheckSuffix("exr"_s))
// construct target file name
const maxon::Url targetFile = (exrFolder + url.GetName())iferr_return;
DiagnosticOutput("Move file @ to @", url, targetFile);
// move file
url.IoMove(targetFile) iferr_return;
return OK
Definition: apibase.h:2663
No flags specified.
Url is a directory, you can use GetBrowseIterator to iterate through the children.
Url is a file.


Data streams are used to write into and read from a resource defined with a maxon::Url:

See also maxon::IoFileOutputHelper and maxon::IoFileInputHelper.

For details on input/output streams see InputStream Manual and OutputStream Manual.

// This example opens a simple text file and prints the content to the console.
// After that, additional text is added to the file.
// construct file URL
const maxon::Url logFile = (targetFolder + maxon::Url("log.txt"_s))iferr_return;
// read file if it exists
if (logFile.IoDetect() == maxon::IODETECT::FILE)
// read data
// to maxon::String
const maxon::String fileString { fileData };
DiagnosticOutput("Log Content: @", fileString);
// output string
const maxon::String logData { "logged event..\r\n" };
const maxon::BaseArray<maxon::Char> logDataMem = logData.GetCString() iferr_return;
// write using stream
const maxon::OutputStreamRef stream = logFile.OpenOutputStream(flags) iferr_return;
stream.Write(logDataMem) iferr_return;
PyCompilerFlags * flags
Definition: ast.h:14
Definition: basearray.h:412
static MAXON_METHOD Result< void > ReadFileToMemory(UrlOrInputStream &&name, WritableArrayInterface< Char > &arr)
PyObject * stream
Definition: codecs.h:186
Sets the file handle to the end of file after opening. To append to the end of a file use WRITE_DONT_...
Allows to write to existing files without truncation, so the existing file is kept as is.
// This example loads a file from the web and saves it to the local file system.
// check if the given URL references a file on the web
const maxon::UrlScheme scheme = webFile.GetScheme();
const maxon::Bool isHTTP = scheme == maxon::URLSCHEME_HTTP;
const maxon::Bool isHTTPS = scheme == maxon::URLSCHEME_HTTPS;
if (isHTTP || isHTTPS)
// read data
// input stream
const maxon::InputStreamRef inputStream = webFile.OpenInputStream() iferr_return;
const maxon::Int64 length = inputStream.GetStreamLength() iferr_return;
inputStream.Read(data) iferr_return;
inputStream.Close() iferr_return;
// save data to file
// prepare file name
const maxon::Url localFile = (targetFolder + webFile.GetName())iferr_return;
// output stream
const maxon::OutputStreamRef outputStream = localFile.OpenOutputStream() iferr_return;
// write to file
outputStream.Write(data) iferr_return;
outputStream.Close() iferr_return;
Definition: basearray.h:1369
Definition: apibaseid.h:253
bool Bool
boolean type, possible values are only false/true, 8 bit
Definition: apibase.h:183
int64_t Int64
64 bit signed integer datatype.
Definition: apibase.h:180
static const Id URLSCHEME_HTTPS
Definition: url.h:735
static const Id URLSCHEME_HTTP
Definition: url.h:730
PyWideStringList Py_ssize_t length
Definition: initconfig.h:448
// This example reads the content of a stream using ReadEOS().
// open stream
const maxon::InputStreamRef inputStream = webFile.OpenInputStream() iferr_return;
// prepare memory
data.Resize(predictedSize) iferr_return;
// read until end of stream
const maxon::Int streamSize = inputStream.ReadEOS(data) iferr_return;
// resize
if (streamSize < predictedSize)
data.Resize(streamSize) iferr_return;
Int64 Int
signed 32/64 bit int, size depends on the platform
Definition: apibase.h:190

Url Flags

maxon::URLFLAGS can be used to define maxon::Url attributes.

// This example retrieve the result from a POST and print it.
maxon::Url theServer { "http://localhost:8080"_s };
// Prepares the data that will be post
maxon::String postData = "foo=bar&bin=go"_s;
theServer.Set(maxon::URLFLAGS::HTTP_POSTMETHOD, maxon::HTTPMETHOD::POST) iferr_return;
theServer.Set(maxon::URLFLAGS::HTTP_POSTDATA, maxon::CString(postData, maxon::StringEncodings::Utf8())) iferr_return;
// Retrieves the answer and read it to memory
DiagnosticOutput("@", err);
// Prints the answer from server
ApplicationOutput("answer @", memReq);
// Prints the answer as a string
ApplicationOutput("result @", result);
Definition: string.h:1490
PyObject PyObject * result
Definition: abstract.h:43
#define ApplicationOutput(formatString,...)
Definition: debugdiagnostics.h:210
#define iferr(...)
Definition: errorbase.h:388


Miscellaneous functions are:

Further Reading