Url Manual

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
// 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
// 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;
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;
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
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;
// Retrieves the answer and read it to memory
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

maxon::FileUtilities::ReadFileToMemory
static MAXON_METHOD Result< void > ReadFileToMemory(UrlOrInputStream &&name, WritableArrayInterface< Char > &arr)
maxon::OPENSTREAMFLAGS::SEEK_TO_END
@ SEEK_TO_END
Sets the file handle to the end of file after opening. To append to the end of a file use WRITE_DONT_...
maxon::IODETECT::DIRECTORY
@ DIRECTORY
Url is a directory, you can use GetBrowseIterator to iterate through the children.
maxon::IOSHOWINOSFLAGS::SHOW_IN_EXPLORER
@ SHOW_IN_EXPLORER
Show the url in the windows explorer or osx finder.
maxon::IODETECT::NONEXISTENT
@ NONEXISTENT
Url doesn't exist.
maxon::String
Definition: string.h:1197
maxon::OK
return OK
Definition: apibase.h:2532
maxon::BaseArray::Resize
ResultMem Resize(Int newCnt, COLLECTION_RESIZE_FLAGS resizeFlags=COLLECTION_RESIZE_FLAGS::DEFAULT)
Definition: basearray.h:1077
maxon::Bool
bool Bool
boolean type, possible values are only false/true, 8 bit
Definition: apibase.h:177
maxon::Id
Definition: apibaseid.h:250
iferr_return
#define iferr_return
Definition: resultbase.h:1434
maxon::URLSCHEME_HTTPS
static const Id URLSCHEME_HTTPS
Definition: url.h:663
maxon::BaseArray
Definition: basearray.h:366
maxon::HTTPMETHOD::POST
@ POST
DiagnosticOutput
#define DiagnosticOutput(formatString,...)
Definition: debugdiagnostics.h:166
maxon::Url
Definition: url.h:819
maxon::URLSCHEME_HTTP
static const Id URLSCHEME_HTTP
Definition: url.h:658
maxon::Int
Int64 Int
signed 32/64 bit int, size depends on the platform
Definition: apibase.h:184
maxon::URLSCHEME_FILESYSTEM
static const Id URLSCHEME_FILESYSTEM
Definition: url.h:587
ApplicationOutput
#define ApplicationOutput(formatString,...)
Definition: debugdiagnostics.h:207
maxon::IODETECT::FILE
@ FILE
Url is a file.
maxon::GETBROWSEITERATORFLAGS::NONE
@ NONE
No flags specified.
maxon::OPENSTREAMFLAGS::WRITE_DONT_TRUNCATE
@ WRITE_DONT_TRUNCATE
Allows to write to existing files without truncation, so the existing file is kept as is.
iferr
#define iferr(...)
Definition: errorbase.h:380
maxon::CString
Definition: string.h:1436