Url Manual

Table of Contents

• About
• Construction
• Scheme
• Parts
• File Functions
• Streams
• Url Flags
• Miscellaneous
• Further Reading

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.

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:

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

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_MEMORYFILESTRUCT	Scheme identifier for MemoryFileStruct streams.
maxon::URLSCHEME_RAMDISK	Scheme identifier for virtual file systems in RAM.
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_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.");

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.

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

Further Reading

• Files & Media
• MAXON API Files & Media
• InputStream Manual
• OutputStream Manual
• FileMonitor Manual