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:

maxon::UrlInterface::Append(): Appends the given part to the URL.
maxon::UrlInterface::operator+(): Returns the combination of the current URL with the given URL.

 // 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:

maxon::Application::GetUrl(): Returns the requested URL, see maxon::APPLICATION_URLTYPE.
maxon::Application::GetTempUrl(): Returns a new unique URL for a temporary file.
maxon::Application::GetModulePaths(): Returns all module (plugin) paths.

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:

maxon::UrlInterface::GetScheme(): Returns the scheme of the URL.
maxon::UrlInterface::SetScheme(): Sets the scheme of the URL.

The supported maxon::UrlScheme types are:

maxon::URLSCHEME_FILESYSTEM: For files of the file system. It supports streams and directory browsing.
maxon::URLSCHEME_ZIPFILE: For zip files. It supports directory browsing and InputStreams.
maxon::URLSCHEME_MEMORY: For memory files. Please use maxon::IoMemoryInterface for initialization. Supports InputStreams and OutputStreams.
maxon::URLSCHEME_TCP: Raw TCP connections. Supports InputStreams, OutputStreams and InOutputStreams.
maxon::URLSCHEME_HTTP: For http files. This type only supports InputStreams at the moment.
maxon::URLSCHEME_HTTPS: For https files. This type only supports InputStreams at the moment.
maxon::URLSCHEME_PERFORCE: For perforce access. It supports browsing depots and InputStreams.
maxon::URLSCHEME_CRYPTOFILE: En-/decryption handler. It supports InputStreams, OutputStreams and InOutputStreams.
maxon::URLSCHEME_FTP: For ftp files. This type supports InputStreams, OutputStreams and browsing at the moment.
maxon::URLSCHEME_SFTP: For sftp files. This type supports InputStreams, OutputStreams and browsing at the moment.
maxon::URLSCHEME_CACHE: Wrap input streams to temp files in the file system. This type supports InputStreams at the moment.
maxon::URLSCHEME_PIPE: For inter-process communication. One endpoint can be passed to the started process, the other one can be used for reading and writing. This can only be used with InOutputStreams.
maxon::URLSCHEME_STDOUT: Redirects stdout. Can only be used as OutputStream.
maxon::URLSCHEME_STDERR: Redirects stderr. Can only be used as OutputStream.
maxon::URLSCHEME_STDIN: Redirects stdin. Can only be used as InputStream.
maxon::URLSCHEME_AUTHORITY: Scheme to store authority information.
maxon::URLSCHEME_RELATIVE: Scheme to store relative paths.
maxon::URLSCHEME_VOLUME: Scheme to browse through all available volumes.

 // 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:

maxon::UrlInterface::GetAuthority(): Returns the authority.
maxon::UrlInterface::SetAuthority(): Sets the authority.
maxon::UrlInterface::GetDirectory(): Returns the directory of the URL.
maxon::UrlInterface::GetPath(): Returns the full path.
maxon::UrlInterface::SetPath(): Sets the full path.
maxon::UrlInterface::GetName(): Returns the file name.
maxon::UrlInterface::RemoveName(): Removes the file name.
maxon::UrlInterface::GetSuffix(): Returns the file suffix.
maxon::UrlInterface::SetSuffix(): Sets the file suffix.
maxon::UrlInterface::CheckSuffix(): Returns true if the given file suffix matches.
maxon::UrlInterface::ClearSuffix(): Clears the file suffix.
maxon::UrlInterface::GetEmbeddedUrl(): Returns the embedded URL (e.g. Zip file).
maxon::UrlInterface::SetEmbeddedUrl(): Sets the embedded URL (e.g. Zip file).
maxon::UrlInterface::SetSystemPath(): Sets the system path.
maxon::UrlInterface::GetSystemPath(): Returns the system path.
maxon::UrlInterface::SetUrl(): Sets the URL.
maxon::UrlInterface::GetUrl(): Returns the URL as a maxon::String.
maxon::UrlInterface::GetRelativeUrl(): Returns a relative URL based on the given path.
maxon::UrlInterface::GetComponents(): Fills the given maxon::NonConstArray with the components of the URL.

 // 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:

maxon::UrlInterface::IoDetect(): Checks the state of the referenced file. See maxon::IODETECT.
maxon::UrlInterface::IoGetAttributes(): Returns the file attributes as maxon::IOATTRIBUTES.
maxon::UrlInterface::IoSetAttributes(): Sets the maxon::IOATTRIBUTES file attributes.
maxon::UrlInterface::IoGetTime(): Returns the time specified with maxon::IOTIMEMODE.
maxon::UrlInterface::IoSetTime(): Sets the time.
maxon::UrlInterface::IoDelete(): Deletes the referenced file or directory.
maxon::UrlInterface::IoCreateDirectory(): Creates the referenced directory.
maxon::UrlInterface::IoCopyFile(): Copies the file to the given target file path.
maxon::UrlInterface::IoMove(): Moves the file to the given target file path.
maxon::UrlInterface::IoRename(): Renames the file.
maxon::UrlInterface::IoGetFreeVolumeSpace(): Calculates the free space of a volume.
maxon::UrlInterface::IoShowInOS(): Opens the file or folder in the system's explorer.
maxon::UrlInterface::IoNormalize(): Returns a normalized URL.
maxon::UrlInterface::GetBrowseIterator(): Returns a maxon::IoBrowseIterator to browse through all children of an URL.

 // 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:

maxon::UrlInterface::OpenConnection(): Opens a maxon::IoConnectionInterface connection.
maxon::UrlInterface::OpenInputStream(): Opens an maxon::InputStreamInterface input stream.
maxon::UrlInterface::OpenOutputStream(): Opens a maxon::OutputStreamInterface output stream.
maxon::UrlInterface::OpenInOutputStream(): Opens an maxon::InOutputStreamInterface in-/output stream.

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::Int64 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.

maxon::UrlInterface::GetData(): Returns various URL attributes.
maxon::UrlInterface::SetData(): Sets an URL attribute.
maxon::Url::Get() Gets data stored under a specific key.
maxon::Url::Set() Sets data under a specific id.

 // 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:

maxon::UrlInterface::Compare(): Compares the URL with the given maxon::Url.
maxon::UrlInterface::Normalize(): Returns the normalized URL.
maxon::UrlInterface::IsEmpty(): Returns true if the URL has no content.
maxon::UrlInterface::IsPopulated(): Returns true if the URL has any content.
maxon::UrlInterface::ToString(): Returns a readable maxon::String of the URL's content.
maxon::UrlInterface::GetHashCode(): Returns the hash code for the URL.

Table of Contents