Url Manual

Table of Contents

About

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.

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

Construction

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);

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

See also Application Manual.

Scheme

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.");

Parts

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);

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
workFolder.IoShowInOS(maxon::IOSHOWINOSFLAGS::SHOW_IN_EXPLORER) iferr_return;
// 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)
continue;
// 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;
}
}

Streams

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
maxon::BaseArray<maxon::Char> fileData;
maxon::FileUtilities::ReadFileToMemory(logFile, fileData) iferr_return;
// 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 auto flags = maxon::OPENSTREAMFLAGS::WRITE_DONT_TRUNCATE | maxon::OPENSTREAMFLAGS::SEEK_TO_END;
const maxon::OutputStreamRef stream = logFile.OpenOutputStream(flags) iferr_return;
stream.Write(logDataMem) iferr_return;
stream.Close() iferr_return;
// 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::Int length = inputStream.GetStreamLength() iferr_return;
maxon::BaseArray<maxon::Char> data;
data.Resize(length) 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;
}
// This example reads the content of a stream using ReadEOS().
// open stream
const maxon::InputStreamRef inputStream = webFile.OpenInputStream() iferr_return;
// prepare memory
maxon::BaseArray<maxon::Char> data;
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;
}

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;
maxon::BaseArray<maxon::Char> memReq;
// Retrieves the answer and read it to memory
iferr (maxon::FileUtilities::ReadFileToMemory(theServer, memReq))
DiagnosticOutput("@", err);
// Prints the answer from server
ApplicationOutput("answer @", memReq);
// Prints the answer as a string
maxon::String result(memReq);
ApplicationOutput("result @", result);

Miscellaneous

Miscellaneous functions are:

Further Reading