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);
Definition: url.h:942
#define DiagnosticOutput(formatString,...)
Definition: debugdiagnostics.h:176
#define iferr_return
Definition: resultbase.h:1521

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: Schemes exposed in url.h :

Scheme Description
maxon::URLSCHEME_FILESYSTEM Scheme identifier for generic file system access.
maxon::URLSCHEME_RELATIVE Scheme identifier for relative Urls which can be resolved with maxon::Url::IoNormalize.
maxon::URLSCHEME_NETWORK Scheme identifier for handling network drive access of a system.
maxon::URLSCHEME_STORAGE Scheme identifier for handling storage device access on a system.
maxon::URLSCHEME_VOLUME Scheme identifier for handling local drive access of a system.
maxon::URLSCHEME_ZIPFILE Scheme identifier for handling zip archive access.
maxon::URLSCHEME_GZIPFILE Scheme identifier for handling zip archive access.
maxon::URLSCHEME_APK_ASSET Scheme identifier for the Android Package (apk) file format.
maxon::URLSCHEME_CRYPTOFILE Scheme identifier for en- and decryption streams.
maxon::URLSCHEME_CACHE Scheme identifier for handling temporary file systems to accelerate file IO.
maxon::URLSCHEME_MEMORY Scheme identifier for handling memory files.
maxon::URLSCHEME_TCP Scheme identifier for Transmission Control Protocol (TCP) connections.
maxon::URLSCHEME_WS Scheme identifier for WebSocket connections.
maxon::URLSCHEME_WSS Scheme identifier for SSL encrypted WebSocket connections.
maxon::URLSCHEME_FTP Scheme identifier for File Transfer Protocol (FTP) connections.
maxon::URLSCHEME_SFTP Scheme identifier for Secure/SSH File Transfer Protocol (SFTP) connections.
maxon::URLSCHEME_HTTP Scheme identifier for Hypertext Transfer Protocol (HTTP) connections.
maxon::URLSCHEME_HTTPS Scheme identifier for Hypertext Transfer Protocol Secure (HTTPS) connections.
maxon::URLSCHEME_PERFORCE Scheme identifier for Perforce access.
maxon::URLSCHEME_AUTHORITY Scheme identifier for storing authority information within the type maxon::Url.
maxon::URLSCHEME_HANDLER Scheme identifier for the default scheme implementation.
maxon::URLSCHEME_PIPE Scheme identifier for inter-process communication.
maxon::URLSCHEME_STDERR Scheme identifier for redirecting outputs to stderr.
maxon::URLSCHEME_STDIN Scheme identifier for redirecting inputs to stdin.
maxon::URLSCHEME_STDOUT Scheme identifier for redirecting outputs to stdout.

Unexposed or outside of url.h exposed schemes:

Scheme Description
maxon::URLSCHEME_UNCFILESYSTEM Scheme identifier for Uniform Naming Convention (UNC) network resource access. Currently not exposed, uses the identifier "unc".
maxon::URLSCHEME_MEMORYFILESTRUCT Scheme identifier for memory file streams. Currently not exposed, uses the identifier "mfs".
maxon::URLSCHEME_RAMDISK Currently only exposed in ramdisk.h .
maxon::URLSCHEME_ASSET Currently only exposed in assets.h .
maxon::URLSCHEME_ASSETDB Currently only exposed in assets.h .
maxon::URLSCHEME_META Currently only exposed in assets.h .
maxon::URLSCHEME_METASQ Currently only exposed in assets.h .
// 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.");
static constexpr LiteralId URLSCHEME_FILESYSTEM
Scheme identifier for generic file system access.
Definition: url.h:671

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);
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_IN_EXPLORER
Show the url in the windows explorer or osx finder.
@ NONEXISTENT
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)
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;
}
}
return OK
Definition: apibase.h:2747
@ NONE
No flags specified.
@ DIRECTORY
Url is a directory, you can use GetBrowseIterator to iterate through the children.
@ FILE
Url is a file.

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;
PyCompilerFlags * flags
Definition: ast.h:14
Definition: basearray.h:415
static MAXON_METHOD Result< void > ReadFileToMemory(UrlOrInputStream &&name, WritableArrayInterface< Char > &arr)
PyObject * stream
Definition: codecs.h:186
@ 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_...
@ WRITE_DONT_TRUNCATE
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;
}
ResultMem Resize(Int newCnt, COLLECTION_RESIZE_FLAGS resizeFlags=COLLECTION_RESIZE_FLAGS::DEFAULT)
Definition: basearray.h:1209
Definition: apibaseid.h:237
bool Bool
boolean type, possible values are only false/true, 8 bit
Definition: apibase.h:206
int64_t Int64
64 bit signed integer datatype.
Definition: apibase.h:203
static constexpr LiteralId URLSCHEME_HTTP
Scheme identifier for Hypertext Transfer Protocol (HTTP) connections.
Definition: url.h:759
static constexpr LiteralId URLSCHEME_HTTPS
Scheme identifier for Hypertext Transfer Protocol Secure (HTTPS) connections.
Definition: url.h:765
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:213

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

Miscellaneous functions are:

Further Reading