Public Member Functions | List of all members
Url Class Reference
IO

#include <url.h>

Inheritance diagram for Url:
Inheritance graph
[legend]

Detailed Description

Class to handle Urls.

Urls consist of three parts: a scheme, an authority and a path. The readable text-representation is "scheme://authority/path".

The scheme defines which handler is used, e.g. "http" for web-based connections or "file" for the regular file system.

The authority defines the machine, which can be empty for "localhost", a network drive or a webserver. It can also refer to an embedded file, e.g. a ZIP. To distinguish that case the readable text representation contains brackets: "scheme://[authority]/path". Nesting is possible repeatedly.

Finally the path component defines the unique location of a file or directory on the target machine. In most schemes paths are a combination of the directory path and file path, but the path could also be a network query or database entry. Path components are always separated by a forward slash and the forward slash is a reserved character that cannot be used for names.

Urls are always case-sensitive, independent of the used scheme handler.

Under Windows the backslash is automatically replaced and converted to a forward slash when you use SetPath or SetSystemPath. Note that backslashes passed to SetUrl or Url() will not be converted.

One note about constructing Url paths: if you use Append or + there is a big difference whether you add a String or a Url. If you add a String you can only add a single name component. With a relative Url you can add multiple path components at once (however this must be a relative Url, any other type will fail). E.g. allowed is Url a = Url("file:///HD"_s) + "test"_s + "image.tif"_s; Url b = Url("file:///HD"_s) + Url("test/image.tif"_s); whereas this will fail: Url a = Url("file:///HD"_s) + "test/image.tif"_s; Url a = Url("file:///HD"_s) + Url("file:///test"_s);

Here an overview over different types of Urls:

  • Url("file:///c:/test/image.tif"_s) - this is a regular Windows file equivalent to Url("c:\test\image.tif"_s) or Url("c:/test/image.tif"_s) GetScheme() returns URLSCHEME_FILE GetAuthority() returns an empty Url with UrlScheme() GetPath() returns "c:/test/image.tif" GetSystemPath() returns "c:/test/image.tif"
  • Url("file:///HD/test/image.tif"_s) - this is a regular OS X or Linux file equivalent to Url("/HD/test/image.tif"_s) GetScheme() returns URLSCHEME_FILE GetAuthority() returns an empty Url with UrlScheme() GetPath() returns "HD/test/image.tif" GetSystemPath() returns "/HD/test/image.tif"
  • Url("file://qnap/test/image.tif"_s) - this is a file on a Windows network drive equivalent to Url("\\qnap\test\image.tif"_s) or Url("//qnap/test/image.tif"_s) GetScheme() returns URLSCHEME_FILE GetAuthority() returns a Url with URLSCHEME_AUTHORITY and path "qnap" GetPath() returns "test/image.tif"; GetSystemPath() returns "//qnap/test/image.tif";
  • Url("ftp://192.168.0.1/test/image.tif"_s) - this is a regular ftp file equivalent to Url(URLSCHEME_FTP, Url(URLSCHEME_AUTHORITY, Url(), "192.168.0.1"_s), "test/image.tif"_s) GetScheme() returns URLSCHEME_FTP GetAuthority() returns a Url with URLSCHEME_FTP and authority "192.168.0.1" GetPath() returns "test/image.tif"; GetSystemPath() returns "test/image.tif";
  • Url("zip://[http://192.168.0.1:1234/archive.zip]/test/image.tif"_s) - this is a file embedded in a ZIP archive on a Web server. equivalent to Url(URLSCHEME_ZIP, Url("http://192.168.0.1:1234/archive.zip"_s), "test/image.tif"_s) GetScheme() returns URLSCHEME_FILE GetAuthority() returns the embedded zip file - a Url with URLSCHEME_HTTP, Authority 192.168.0.1:1234 and path "archive.zip" GetPath() returns "test/image.tif" GetSystemPath() returns "test/image.tif"
  • Url("test/image.tif"_s) - this is relative path equivalent to Url("./test/image.tif"_s) GetScheme() returns URLSCHEME_RELATIVE GetAuthority() returns an empty Url with UrlScheme() GetPath() returns "test/image.tif" GetSystemPath() returns "test/image.tif"

If the Url class is used, it should always be clear what the object can be - a file, a directory, a path (file or directory) or a relative path. Therefore the naming convention is very strict and refers to RFC1738. The path component of a Url typically consists of a directory and a name. Name is the term for a simple filename like test.abc or picture.png. Its placed at the end of a Url. A directory is a set of strings, split by the forward slash-delimiter, in which other directories are kept, e.g. \/Users/MyUser/Desktop. Path is the combination of directory and name.

Following this convention helps the maintainers and users of a function to keep track of what is accepted. If the Url parameter name of a saving function contains for example path it's always clear that the function needs the directory and a name. If the user is allowed to pass everything to the function (a file or directory) the documentation should clarify that (and if the behavior differs from what is passed it must also be documented). Examples:

void DeleteItem(Url targetFile); // Accepts a file like file:///Users/MyUser/Desktop/test.jpg, but no directory.
void DeleteItem(Url targetDir); // Accepts a directory like file:///Users/MyUser/Desktop, but no file.
void DeleteItem(Url targetPath); // Accepts a file or directory.
void DeleteItem(String targetName); // Accepts a name like test.png. Names cannot be stored in Urls. The documentation of the function should contain information on where the file needs to be locaeted.
void DeleteItem(Url relativePath); // Accepts a path like ./test/test.png. The documentation of the function should contain information on how the relative path is evaluated.
Url GetFile(); // Returns e.g. file:///Users/MyUser/Desktop/test.jpg.
Url GetDirectory(); // Returns e.g. file:///Users/MyUser/Desktop
String GetName(); // Returns e.g. file.jpg
Url GetPath(); // Returns a file or directory.
String
Definition: c4d_string.h:41
maxon::Url::Url
Url(const UrlScheme &scheme)
Definition: url.h:950
maxon::details::GetPath
Opt< IoNodePath > GetPath(const IoNodePath &p)
Definition: graph_selection.h:18

Functions starting with "Io" operate directly on the object behind the Url (e.g. a file or directory).

@MAXON_ANNOTATION{reflection}

Public Member Functions

 MAXON_DEFAULT_REFERENCE_CONSTRUCTORS (Url, Reference)
 
 Url (const UrlScheme &scheme)
 
 Url (const String &urlString)
 
 Url (const CString &urlString)
 
 Url (const UrlScheme &scheme, const Url &authority, const String &path)
 
template<typename T = void, typename KEY = void>
Result< typename std::conditional< STD_IS_REPLACEMENT(void, T), typename IsFidClass< KEY >::type, T >::type > Get (KEY &&key) const
 
template<typename T , typename KEY >
T Get (KEY &&key, const T &defaultValue) const
 
template<typename T , typename KEY >
Result< void > Set (KEY &&key, T &&data, Bool persistent=true)
 

Constructor & Destructor Documentation

◆ Url() [1/4]

Url ( const UrlScheme &  scheme)
explicit

UrlScheme constructor.

Parameters
[in]schemeCreates an Url and sets a scheme (e.g. URLSCHEME_FILE or URLSCHEME_HTTP).

◆ Url() [2/4]

Url ( const String &  urlString)
explicit

Url constructor from a String. Identical to SetUrl(urlString, true).

Parameters
[in]urlStringA valid Url, e.g. "file:///H:/test.txt". If no scheme is specified URLSCHEME_FILESYSTEM will be assumed and the regular file system syntax can be passed. If no scheme is specified and the urlString starts with no drive letter or slash URLSCHEME_RELATIVE will be assumed.

◆ Url() [3/4]

Url ( const CString &  urlString)
explicit

Url constructor from a CString. Identical to SetUrl(urlString, true).

Parameters
[in]urlStringA valid Url, e.g. "file:///H:/test.txt". If no scheme is specified URLSCHEME_FILESYSTEM will be assumed and the regular file system syntax can be passed. If no scheme is specified and the urlString starts with no drive letter or slash URLSCHEME_RELATIVE will be assumed.

◆ Url() [4/4]

Url ( const UrlScheme &  scheme,
const Url &  authority,
const String &  path 
)
explicit

Url constructor with scheme, authority and path.

Parameters
[in]schemeThe scheme that will be set. Should always be lowercase because no normalization is applied here.
[in]authorityThe authority that will be set. Can be an empty Url().
[in]pathThe path that will be set.

Member Function Documentation

◆ MAXON_DEFAULT_REFERENCE_CONSTRUCTORS()

MAXON_DEFAULT_REFERENCE_CONSTRUCTORS ( Url  ,
Reference   
)

◆ Get() [1/2]

Result<typename std::conditional<STD_IS_REPLACEMENT(void, T), typename IsFidClass<KEY>::type, T>::type> Get ( KEY &&  key) const

Get data stored under a specific key. If the key is not found an error will be returned. This functions offers 2 possible calls. First using an FId "dict.Get(MAXCHINEINFO::COMPUTERNAME)" or second using any type directly together with the result type "dict.Get<String>(Int32(5))". The data type needs to be registered.

Parameters
[in]keyKey under which the data is stored.
Returns
Data converted to the right type on success.

◆ Get() [2/2]

T Get ( KEY &&  key,
const T &  defaultValue 
) const

Get data stored under a specific key. If the key is not found the given default value will be returned. This functions offers 2 possible calls. First using an FId "dict.Get(MAXCHINEINFO::COMPUTERNAME, String())" or second using any type directly together with the result type "dict.Get(Int32(5), String())". The data type needs to be registered.

Parameters
[in]keyKey under which the data is stored.
[in]defaultValueDefault value which should be returned if the key cannot be found.
Returns
Data converted to the right type if found in the dictionary, otherwise the default value.

◆ Set()

Result<void> Set ( KEY &&  key,
T &&  data,
Bool  persistent = true 
)

Set data under a specific id. this function is template to allow implicit Set calls for each data type. This functions offers 2 possible calls. First using an FId "dict.Set(MAXCHINEINFO::COMPUTERNAME, "data"_s)" or second using any type directly "dict.Set(Int32(5), "data"_s)". The data type needs to be registered. LiteralId data type is not allowed as value type (#data).

Parameters
[in]keyKey under which the data is stored.
[in]dataData to be stored in the dictionary.
[in]persistentWith the default value of true the attribute value is serialized. Use false for a transient attribute (one which shall not be serialized).
Returns
OK on success.