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:

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

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