#include <url.h>
Interface class for Urls.
@MAXON_ANNOTATION{refclass=false}
Public Types | |
| using | RESTRICT_DICTIONARY_PROPS = URLFLAGS::RESTRICT |
Static Public Member Functions | |
| static MAXON_METHOD Result< void > | DescribeIO (const DataSerializeInterface &stream) |
| static MAXON_METHOD Result< Url > | ConvertFromUiName (const String &str, const AssetRepositoryRef &lookupRepository) |
Private Member Functions | |
| MAXON_INTERFACE_NONVIRTUAL (UrlInterface, MAXON_REFERENCE_COPY_ON_WRITE, "net.maxon.interface.url", MAXON_IMPLEMENTATION_MODULE("net.maxon.kernel")) | |
| using RESTRICT_DICTIONARY_PROPS = URLFLAGS::RESTRICT |
|
private |
| MAXON_METHOD const UrlScheme& GetScheme | ( | ) | const |
Gets the UrlScheme of the Url. Is guarantueed to be lowercase (canonical form for urls) if scheme was automatically determined through SetUrl, otherwise as set.
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.
| MAXON_METHOD Result<void> SetScheme | ( | const UrlScheme & | scheme | ) |
Sets the scheme of the Url. Path and authority will stay unchanged.
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.
| [in] | scheme | The new scheme UrlScheme Id e.g. URLSCHEME_FILESYSTEM, URLSCHEME_ZIPFILE or URLSCHEME_MEMORY. Should always be lowercase because no normalization is applied here. |
| MAXON_METHOD Result<void> Append | ( | const String & | name | ) |
Appends a new component to the Url. E.g. if the Url is "file:///c:/directory" a call of Append("file.txt"_s) will result in "file:///c:/directory/file.txt".
| [in] | name | A component that will be added to the end of the Url. A separator (forward slash) will be placed between the end of the current Url and the new part. The value must not contain any forward slashes (under Windows additionally no backslashes), otherwise nothing will be done. |
@MAXON_ANNOTATION{returnsThis,noResult}
| MAXON_METHOD Result<void> Append | ( | const Url & | relativeUrl | ) |
Appends a relative Url to the current one. E.g. if the Url is "file:///c:/directory" a call of Append(Url("test/file.txt"_s)) will result in "file:///c:/directory/test/file.txt".
| [in] | relativeUrl | The relative Url that will be added. A separator (forward slash) will be placed between the end of the current Url and the new part. relativeUrl must be a Url with URLSCHEME_RELATIVE, otherwise nothing will be done. |
@MAXON_ANNOTATION{returnsThis,noResult}
| MAXON_METHOD Result<void> RemoveName | ( | ) |
Removes the last part of a Url. E.g. if the Url is "file:///c:/directory/file.txt" a call of RemoveName() will result in "file:///c:/directory".
| MAXON_METHOD Url GetEmbeddedUrl | ( | ) | const |
Returns an embedded Url. E.g. if the Url is "zip://[file:///c:/images.zip]/image01.jpg" a call to GetEmbeddedUrl() will return "file:///c:/images.zip".
| MAXON_METHOD Result<void> SetEmbeddedUrl | ( | const Url & | url | ) |
| MAXON_METHOD String GetName | ( | ) | const |
| MAXON_METHOD Result<void> SetName | ( | const String & | name | ) |
Replaces the last component of a Url. The name must not contain a forward slashes and under Windows additionally no backslashes. E.g. if the Url is "file:///c:/directory/file.txt" a call of SetName("change.tif"_s) will result in "file:///c:/directory/change.tif".
| [in] | name | The new name. |
| MAXON_METHOD Url GetDirectory | ( | ) | const |
Returns the Url of the directory. If the Url is empty the directory is empty as well. E.g. if the Url was "file:///c:/directory/file.txt" a call of GetDirectory() will return "file:///c:/directory".
| MAXON_METHOD Result<void> SetPath | ( | const String & | path, |
| Bool | convertWindowsBackslashes = true |
||
| ) |
Replaces the path component of the Url. The path is stored unchanged with the exception that under Windows all backslashes will be changed into forward slashes (unless convertWindowsBackslashes is set to false).
| [in] | path | The new path. |
| [in] | convertWindowsBackslashes | True to convert backslashes under windows (the default). |
| MAXON_METHOD const String& GetPath | ( | ) | const |
| MAXON_METHOD Result<void> SetSystemPath | ( | const String & | path | ) |
Stores a system path in a Url. This call needs to be done after the appropriate scheme has been set. If no scheme is set URLSCHEME_FILESYSTEM will be automatically set. The system path may be converted to a different internal representation, e.g. split into authority and path components. Under Windows all backslashes will be changed into forward slashes.
| [in] | path | The system path. |
| MAXON_METHOD Result<String> GetSystemPath | ( | ) | const |
Returns a path from the Url that the current operating system (or scheme handler) can understand. If the Url contains no valid scheme an error will be returned. An error will also be returned if the Url contains illegal characters for the scheme, e.g. backslashes on Windows in a file scheme.
| MAXON_METHOD Result<void> SetUrl | ( | const String & | urlString, |
| Bool | enableDefaultFallbackScheme | ||
| ) |
Sets the Url. The scheme is detected automatically and converted to the canonical lowercase version (as described in rfc3986#3.1). If a scheme isn't found and enableDefaultFallbackScheme is false the function returns an IllegalArgumentError, otherwise URLSCHEME_FILESYSTEM will be assumed (or URLSCHEME_RELATIVE if 'urlString' starts with no drive letter). Please note that Urls only use forward slashes as delimiter, backslashes are considered to be a part of names and not a delimiter. '?' will be considered as the start of URLFLAGS::QUERY parameters. Everything behin the '?' will be placed in that property. Use url.Get(URLFLAGS::QUERY) to get the query parameters.
| [in] | urlString | The new Url to be set. |
| [in] | enableDefaultFallbackScheme | If false and no scheme is set an error will be returned. |
| MAXON_METHOD String GetUrl | ( | ) | const |
| MAXON_METHOD String GetUrlEncoded | ( | ) | const |
| MAXON_METHOD Result<void> SetAuthority | ( | const String & | authority | ) |
| MAXON_METHOD Result<void> SetAuthority | ( | const Url & | authority | ) |
Sets the authority of a Url. This can be a machine, server or embedded file. Url() can be passed for no authority.
| [in] | authority | The new authority. Can be a machine, server or embedded file. |
| MAXON_METHOD const Url& GetAuthority | ( | ) | const |
| MAXON_METHOD Result<void> GetComponents | ( | const NonConstArray< String > & | parts | ) | const |
Returns all parts of the Url system path as separated strings. E.g. if the Url was "file:///c:/directory/file.txt" a call of GetComponents will return: { "C:", "directory", "file.txt" }.
| [out] | parts | Array with the parts of the system path. A possible authority will be returned as the first part of the array. |
| MAXON_METHOD Result<Url> GetRelativeUrl | ( | const Url & | basePath | ) | const |
Returns a relative url based on the given basePath. The basePath needs to have the same scheme, authority. basepath needs to be part of the path of this url.
| [in] | basePath | The base of the relative url. |
| MAXON_METHOD String GetSuffix | ( | ) | const |
Returns the suffix of the Url. E.g. if the Url was "file:///c:/directory/file.txt" a call of GetSuffix() will return "txt".
| MAXON_METHOD Bool CheckSuffix | ( | const String & | suffix | ) | const |
| MAXON_METHOD Result<void> SetSuffix | ( | const String & | suffix | ) |
Replaces the suffix of the Url. If the Url had no suffix before a dot will be added together with the suffix string. E.g. if the Url is "file:///c:/directory/file.txt" a call of SetSuffix("jpg"_s) will result in "file:///c:/directory/file.jpg".
| [in] | suffix | The new suffix of the Url without dot. |
| MAXON_METHOD void ClearSuffix | ( | ) |
| MAXON_METHOD Bool IsEmpty | ( | ) | const |
| MAXON_FUNCTION Bool IsPopulated | ( | ) | const |
| MAXON_METHOD COMPARERESULT Compare | ( | const UrlInterface * | name, |
| URLCOMPARE | mode = URLCOMPARE::DEFAULT |
||
| ) | const |
Compares the object against 'name'. Note that by default the comparison is case-sensitive, so './Test.tif' and './test.tif' are not the same. To check if Urls point to the identical item use IoNormalize instead.
| [in] | name | Comparison object. |
| [in] | mode | Comparision mode. |
| MAXON_METHOD Result<Data> GetData | ( | const ConstDataPtr & | key | ) | const |
Returns Url attributes. See maxon::URLFLAGS for details.
| [in] | key | The id of the property to get. The possible values for id depend on the scheme. |
| MAXON_METHOD Result<void> SetData | ( | ForwardingDataPtr && | key, |
| const Data & | data, | ||
| Bool | persistent = true |
||
| ) |
Modifies or sets a Url attribute. See maxon::URLFLAGS for details.
| [in] | key | The id of the property to set. The possible values for id depend on the scheme. |
| [in] | data | Data to be set. |
| [in] | persistent | With the default value of true the attribute value is serialized. Use false for a transient attribute (one which shall not be serialized). |
| MAXON_METHOD Result<void> SetData | ( | ForwardingDataPtr && | key, |
| Data && | data, | ||
| Bool | persistent = true |
||
| ) |
Modifies or sets a Url attribute. See maxon::URLFLAGS for details.
| [in] | key | The id of the property to set. The possible values for id depend on the scheme. |
| [in] | data | Data to be set. |
| [in] | persistent | With the default value of true the attribute value is serialized. Use false for a transient attribute (one which shall not be serialized). |
| MAXON_METHOD Result<void> EraseData | ( | ForwardingDataPtr && | key, |
| Bool | persistent = true |
||
| ) |
EraseData removes data from the data dictionary
| [in] | key | The id of the property to erase. The possible values for id depend on the scheme. |
| [in] | persistent | With the default value of true the attribute value is serialized. Use false for a transient attribute (one which shall not be serialized). |
| MAXON_FUNCTION IODETECT IoDetect | ( | ) | const |
| MAXON_FUNCTION Result<IoConnectionRef> OpenConnection | ( | ) | const |
Returns a pointer to a IoConnectionInterface class of this Url.
| MAXON_FUNCTION Result<InputStreamRef> OpenInputStream | ( | OPENSTREAMFLAGS | flags = OPENSTREAMFLAGS::NONE | ) | const |
Returns a pointer to a InputStreamInterface class of this Url.
| [in] | flags | See OPENSTREAMFLAGS for details. |
| MAXON_FUNCTION Result<OutputStreamRef> OpenOutputStream | ( | OPENSTREAMFLAGS | flags = OPENSTREAMFLAGS::NONE | ) | const |
Returns a pointer to a OutputStreamInterface class of this Url.
| [in] | flags | See OPENSTREAMFLAGS for details. |
| MAXON_FUNCTION Result<InOutputStreamRef> OpenInOutputStream | ( | OPENSTREAMFLAGS | flags = OPENSTREAMFLAGS::NONE | ) | const |
Returns a pointer to a InOutputStreamInterface class of this Url.
| [in] | flags | See OPENSTREAMFLAGS for details. |
| MAXON_FUNCTION Result<IoBrowseRef> GetBrowseIterator | ( | GETBROWSEITERATORFLAGS | flags | ) | const |
Returns a IoBrowseIterator to browse through all children of an Url.
Example 1: If you want to catch all errors like opening the directory and error when going next file.
| [in] | flags | See GETBROWSEITERATORFLAGS. |
| MAXON_FUNCTION Result<IOATTRIBUTES> IoGetAttributes | ( | ) | const |
Returns the file attributes of the object behind the Url.
| MAXON_FUNCTION Result<void> IoSetAttributes | ( | IOATTRIBUTES | flags, |
| IOATTRIBUTES | mask | ||
| ) | const |
Modifies the file attributes of the object behind the Url.
| [in] | flags | Flags to set/clear. |
| [in] | mask | Mask with all flags to be changed. |
| MAXON_FUNCTION Result<UniversalDateTime> IoGetTime | ( | IOTIMEMODE | mode | ) | const |
| MAXON_FUNCTION Result<void> IoSetTime | ( | IOTIMEMODE | mode, |
| const UniversalDateTime & | dateTime | ||
| ) | const |
Attempts to modify the DateTime of the current file.
The time is in local time.
| [in] | mode | IOTIMEMODE of the requested time. |
| [in] | dateTime | The new datetime for the file. |
| MAXON_FUNCTION Result<void> IoDelete | ( | Bool | force, |
| Bool | recursive = false |
||
| ) | const |
Attempts to deletes a file or directory physically on the medium.
| [in] | force | Set to true tries to deletes the file/directory even if the file/directory has read only flags set. |
| [in] | recursive | Recursively deletes a directory and its content. If a file is specified this value is ignored. |
| MAXON_FUNCTION Result<void> IoCreateDirectory | ( | Bool | createParents, |
| BaseArray< Url > * | createdDirs = nullptr |
||
| ) | const |
Attempts to physically create the non-existing directories in the directory path expressed by the Url.
Will return an IoError when the full path does already exist, is the empty path, or the user lacks access rights.
| [in] | createParents | Check if parent directory exists and if not create them recursively. |
| [out] | createdDirs | An array that will contain all newly created subdirectories in the order in which they were created. If this parameter is nullptr it will be ignored. |
| MAXON_FUNCTION Result<void> IoCopyFile | ( | const Url & | destName, |
| Bool | overwrite, | ||
| Bool | removeReadOnly, | ||
| const IoProgressDelegate & | progress = IoProgressDelegate() |
||
| ) | const |
Attempts to copy a file to a different location.
The path must exist otherwise the function returns an error.
| [in] | destName | Destination name for the copy operation. |
| [in] | overwrite | Set to true to allow overwriting destName file if it was already there. |
| [in] | removeReadOnly | Set to true to remove the read only flag on the newly created copy. |
| [in] | progress | Progress delegate. |
| MAXON_FUNCTION Result<void> IoMove | ( | const Url & | destName | ) | const |
Moves a file or directory (including hierarchy) to a different location, the path must exist otherwise the function returns an error. If the destName file or directory does already exist the function returns with an error. Moving a file or directory on the same partition will perform without a temporary copy.
| [in] | destName | Destination name for the move operation. |
| MAXON_FUNCTION Result<void> IoRename | ( | const Url & | newName | ) | const |
Renames a file or directory. The newName must not be the name of an existing file or directory.
| [in] | newName | Destination name for the move operation. |
| MAXON_FUNCTION Result<void> IoGetFreeVolumeSpace | ( | Int64 & | availableBytes, |
| Int64 & | totalBytes | ||
| ) | const |
Calculates the free space on a volume. The Url must point to a volume, e.g. by browsing SCHEME_VOLUME.
| [out] | availableBytes | The number of available bytes on the volume. |
| [out] | totalBytes | The total size of the volume in bytes. |
| MAXON_FUNCTION Result<void> IoShowInOS | ( | IOSHOWINOSFLAGS | flags | ) | const |
Opens or shows the file in the systems explorer (desktop/finder). Under windows that would be on the desktop/explorer. Under OSX this would be the Finder. Depending on the url scheme this could also open another browser.
| [in] | flags | Flags to define how to open that file. |
| MAXON_FUNCTION Result<Url> Normalize | ( | NORMALIZEFLAGS | flags = NORMALIZEFLAGS::SCHEME_BASED | ) | const |
Return a normalized a url. Does not involve any Io operation and is just syntax based. If nothing needs to be normalized the same path is returned.
| [in] | flags | Flags to define type of normalization. |
| MAXON_FUNCTION Result<Url> IoNormalize | ( | NORMALIZEFLAGS | flags = NORMALIZEFLAGS::SCHEME_BASED | ) | const |
Return a normalized a url. If the normalized url is a link, the IoHandler can resolve it (if supported). E.g. the file:/// handler resolves symbolic links, where the http:// handler does not resolve llinks.
| [in] | flags | Flags to define type of normalization. |
| MAXON_METHOD String ToString | ( | const FormatStatement * | formatStatement = nullptr | ) | const |
Returns a readable string of the content.
| [in] | formatStatement | Nullptr or additional formatting instruction. Currently no additional formatting instructions are supported. |
| MAXON_METHOD CString ToCString | ( | ) | const |
Returns a readable string of the content.
|
static |
Describe all elements of this class for I/O operations.
| [in] | stream | The stream that is used to register the class members. |
| MAXON_FUNCTION HashInt GetHashCode | ( | ) | const |
Returns the hash code of this @CLASS.
| MAXON_FUNCTION UniqueHash GetUniqueHashCode | ( | ) | const |
Returns the 128-bit hash value of this @CLASS. The implementation ensures uniform distribution, so for practical purposes you can safely assume that two objects are equal if their hash values are equal.
| MAXON_METHOD Result<String> ConvertToUiName | ( | CONVERTTOUINAMEFLAGS | flags, |
| const AssetRepositoryRef & | lookupRepository | ||
| ) | const |
ConvertToUiNameWithRepository converts the url into a humans readable string. Implementations can use this function to convert string. e.g. Assets can build a nice human readable url string.
| [in] | flags | Flags for the conversion, see CONVERTTOUINAMEFLAGS. |
| [in] | lookupRepository | AssetRespoitory to search in. |
|
static |