UrlInterface Class Reference

#include <url.h>

Detailed Description

Interface class for Urls.

@MAXON_ANNOTATION{refclass=false}

Public Types

using RESTRICT_DICTIONARY_PROPS = URLFLAGS::RESTRICT
 

Public Member Functions

MAXON_METHOD const UrlSchemeGetScheme () const
 
MAXON_METHOD Result< void > SetScheme (const UrlScheme &scheme)
 
MAXON_METHOD Result< void > Append (const String &name)
 
MAXON_METHOD Result< void > Append (const Url &relativeUrl)
 
MAXON_METHOD Result< void > RemoveName ()
 
MAXON_METHOD Url GetEmbeddedUrl () const
 
MAXON_METHOD Result< void > SetEmbeddedUrl (const Url &url)
 
MAXON_METHOD String GetName () const
 
MAXON_METHOD Result< void > SetName (const String &name)
 
MAXON_METHOD Url GetDirectory () const
 
MAXON_METHOD Result< void > SetPath (const String &path)
 
MAXON_METHOD Result< void > SetPath (const String &path, Bool convertWindowsBackslashes)
 
MAXON_METHOD const StringGetPath () const
 
MAXON_METHOD Result< void > SetSystemPath (const String &path)
 
MAXON_METHOD Result< StringGetSystemPath () const
 
MAXON_METHOD Result< void > SetUrl (const String &urlString, Bool enableDefaultFallbackScheme)
 
MAXON_METHOD String GetUrl () const
 
MAXON_METHOD Result< void > SetAuthority (const String &authority)
 
MAXON_METHOD Result< void > SetAuthority (const Url &authority)
 
MAXON_METHOD const UrlGetAuthority () const
 
MAXON_METHOD Result< void > GetComponents (const NonConstArray< String > &parts) const
 
MAXON_METHOD Result< UrlGetRelativeUrl (const Url &basePath) const
 
MAXON_METHOD String GetSuffix () const
 
MAXON_METHOD Bool CheckSuffix (const String &suffix) const
 
MAXON_METHOD Result< void > SetSuffix (const String &suffix)
 
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
 
MAXON_METHOD Result< DataGetData (const ConstDataPtr &key) const
 
MAXON_METHOD Result< void > SetData (ForwardingDataPtr &&key, const Data &data, Bool persistent=true)
 
MAXON_METHOD Result< void > SetData (ForwardingDataPtr &&key, Data &&data, Bool persistent=true)
 
MAXON_METHOD Result< void > EraseData (ForwardingDataPtr &&key, Bool persistent=true)
 
MAXON_FUNCTION IODETECT IoDetect () const
 
MAXON_FUNCTION Result< IoConnectionRef > OpenConnection () const
 
MAXON_FUNCTION Result< InputStreamRef > OpenInputStream (OPENSTREAMFLAGS flags=OPENSTREAMFLAGS::NONE) const
 
MAXON_FUNCTION Result< OutputStreamRef > OpenOutputStream (OPENSTREAMFLAGS flags=OPENSTREAMFLAGS::NONE) const
 
MAXON_FUNCTION Result< InOutputStreamRef > OpenInOutputStream (OPENSTREAMFLAGS flags=OPENSTREAMFLAGS::NONE) const
 
MAXON_FUNCTION Result< IoBrowseRef > GetBrowseIterator (GETBROWSEITERATORFLAGS flags) const
 
MAXON_FUNCTION Result< IOATTRIBUTESIoGetAttributes () const
 
MAXON_FUNCTION Result< void > IoSetAttributes (IOATTRIBUTES flags, IOATTRIBUTES mask) const
 
MAXON_FUNCTION Result< UniversalDateTimeIoGetTime (IOTIMEMODE mode) const
 
MAXON_FUNCTION Result< void > IoSetTime (IOTIMEMODE mode, const UniversalDateTime &dateTime) const
 
MAXON_FUNCTION Result< void > IoDelete (Bool force, Bool recursive=false) const
 
MAXON_FUNCTION Result< void > IoCreateDirectory (Bool createParents, BaseArray< Url > *createdDirs=nullptr) const
 
MAXON_FUNCTION Result< void > IoCopyFile (const Url &destName, Bool overwrite, Bool removeReadOnly, const IoProgressDelegate &progress=IoProgressDelegate()) const
 
MAXON_FUNCTION Result< void > IoMove (const Url &destName) const
 
MAXON_FUNCTION Result< void > IoRename (const Url &newName) const
 
MAXON_FUNCTION Result< void > IoGetFreeVolumeSpace (Int64 &availableBytes, Int64 &totalBytes) const
 
MAXON_FUNCTION Result< void > IoShowInOS (IOSHOWINOSFLAGS flags) const
 
MAXON_FUNCTION Result< UrlNormalize (NORMALIZEFLAGS flags=NORMALIZEFLAGS::SCHEME_BASED) const
 
MAXON_FUNCTION Result< UrlIoNormalize (NORMALIZEFLAGS flags=NORMALIZEFLAGS::SCHEME_BASED) const
 
MAXON_FUNCTION Result< Urloperator+ (const String &s) const
 
MAXON_FUNCTION Result< Urloperator+ (const Url &s) const
 
MAXON_METHOD String ToString (const FormatStatement *formatStatement=nullptr) const
 
MAXON_METHOD CString ToCString () const
 
MAXON_METHOD Result< StringConvertToUiName (CONVERTTOUINAMEFLAGS flags) const
 
MAXON_FUNCTION HashInt GetHashCode () const
 
MAXON_FUNCTION UniqueHash GetUniqueHashCode () const
 
MAXON_METHOD Result< StringConvertToUiNameWithRepository (CONVERTTOUINAMEFLAGS flags, const AssetRepositoryRef &lookupRepository) const
 

Static Public Member Functions

static MAXON_METHOD Result< UrlConvertFromUiName (const String &str)
 
static MAXON_METHOD Result< void > DescribeIO (const DataSerializeInterface &stream)
 
static MAXON_METHOD Result< UrlConvertFromUiNameWithRepository (const String &str, const AssetRepositoryRef &lookupRepository)
 

Private Member Functions

 MAXON_INTERFACE_NONVIRTUAL (UrlInterface, MAXON_REFERENCE_COPY_ON_WRITE, "net.maxon.interface.url")
 

Member Typedef Documentation

◆ RESTRICT_DICTIONARY_PROPS

using RESTRICT_DICTIONARY_PROPS = URLFLAGS::RESTRICT

Member Function Documentation

◆ MAXON_INTERFACE_NONVIRTUAL()

MAXON_INTERFACE_NONVIRTUAL ( UrlInterface  ,
MAXON_REFERENCE_COPY_ON_WRITE  ,
"net.maxon.interface.url"   
)
private

◆ GetScheme()

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.

Returns
Returns the UrlScheme for the Url (e.g. "file", "http"). If no scheme is set the returned value is UrlScheme().

◆ SetScheme()

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.

Parameters
[in]schemeThe new scheme UrlScheme Id e.g. URLSCHEME_FILESYSTEM, URLSCHEME_ZIPFILE or URLSCHEME_MEMORY. Should always be lowercase because no normalization is applied here.
Returns
OK on success.

◆ Append() [1/2]

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

Parameters
[in]nameA 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.
Returns
*this.

@MAXON_ANNOTATION{returnsThis,noResult}

◆ Append() [2/2]

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

Parameters
[in]relativeUrlThe 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.
Returns
*this.

@MAXON_ANNOTATION{returnsThis,noResult}

◆ RemoveName()

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

Returns
OK on success. Returns an error if there is nothing to remove.

◆ GetEmbeddedUrl()

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

Returns
The embedded Url or if there was none Url().

◆ SetEmbeddedUrl()

MAXON_METHOD Result<void> SetEmbeddedUrl ( const Url url)

Replaces and sets an embedded Url. E.g. if the Url is "zip://[file:///c:/images.zip]/image01.jpg" a call to SetEmbeddedUrl("file:///c:/otherimages.zip"_s) will result in "zip://[file:///c:/otherimages.zip]/image01.jpg".

Parameters
[in]urlThe new embedded Url.
Returns
OK on success.

◆ GetName()

MAXON_METHOD String GetName ( ) const

Returns the name of the last component. E.g. if the Url is "file:///c:/directory/file.txt" a call to GetName() will return "file.txt".

Returns
The name of the last path component.

◆ SetName()

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

Parameters
[in]nameThe new name.
Returns
OK on success.

◆ GetDirectory()

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

Returns
The directory Url.

◆ SetPath() [1/2]

MAXON_METHOD Result<void> SetPath ( const String path)

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.

Parameters
[in]pathThe new path.
Returns
OK on success.

◆ SetPath() [2/2]

MAXON_METHOD Result<void> SetPath ( const String path,
Bool  convertWindowsBackslashes 
)

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.

Parameters
[in]pathThe new path.
[in]convertWindowsBackslashesTrue to convert backslashes under windows.
Returns
OK on success.

◆ GetPath()

MAXON_METHOD const String& GetPath ( ) const

Returns the path component of the Url. Note that this doesn't contain scheme and authority. E.g. if the Url is "file:///c:/directory/file.txt" a call will return "c:/directory/file.txt".

Returns
The path component of the Url (with no authority and scheme).

◆ SetSystemPath()

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.

Parameters
[in]pathThe system path.
Returns
OK on success.

◆ GetSystemPath()

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.

Returns
The system path.

◆ SetUrl()

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.

Parameters
[in]urlStringThe new Url to be set.
[in]enableDefaultFallbackSchemeIf false and no scheme is set an error will be returned.
Returns
OK on success.

◆ GetUrl()

MAXON_METHOD String GetUrl ( ) const

Returns the Url as a string. A Url has the format scheme://authority/path.

Returns
The Url as a string.

◆ SetAuthority() [1/2]

MAXON_METHOD Result<void> SetAuthority ( const String authority)

Sets the authority of a Url. This can be a machine or server.

Parameters
[in]authorityThe new authority. String() can be passed for no authority / localhost. The authority scheme will be URLSCHEME_AUTHORITY.
Returns
OK on success.

◆ SetAuthority() [2/2]

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.

Parameters
[in]authorityThe new authority. Can be a machine, server or embedded file.
Returns
OK on success.

◆ GetAuthority()

MAXON_METHOD const Url& GetAuthority ( ) const

Returns the authority of a Url. The authority can be a machine, server or embedded file.

Returns
The authority of the Url. If the machine is localhost the returned Url is empty. If it is a machine or server the scheme will be URLSCHEME_AUTHORITY. Otherwise it defines an embedded file.

◆ GetComponents()

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" }.

Parameters
[out]partsArray with the parts of the system path. A possible authority will be returned as the first part of the array.
Returns
OK on success.

◆ GetRelativeUrl()

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.

Parameters
[in]basePathThe base of the relative url.
Returns
Returns the relative url on success.

◆ GetSuffix()

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

Returns
The suffix without dot.

◆ CheckSuffix()

MAXON_METHOD Bool CheckSuffix ( const String suffix) const

Checks whether the Url has the a given suffix E.g. if the Url is "file:///c:/directory/file.txt" a call of CheckSuffix("txt"_s) will return true.

Parameters
[in]suffixThe suffix without dot to check against.
Returns
True if the suffix matches.

◆ SetSuffix()

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

Parameters
[in]suffixThe new suffix of the Url without dot.
Returns
OK on success.

◆ ClearSuffix()

MAXON_METHOD void ClearSuffix ( )

Deletes the suffix of the Url. E.g. if the Url was "file:///c:/directory/file.txt" a call will result in "file:///c:/directory/file".

◆ IsEmpty()

MAXON_METHOD Bool IsEmpty ( ) const

Returns if the Url has no content. A Url is considered empty if it has no path component and no authority (even if a scheme is set).

Returns
True if the Url is empty.

@MAXON_ANNOTATION{default=true}

◆ IsPopulated()

MAXON_FUNCTION Bool IsPopulated ( void  ) const

Returns if the Url has any content. A Url is considered populated if it has a path component or authority set.

Returns
True if the Url has content.

◆ Compare()

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 Url::IoNormalizeAndResolve instead.

Parameters
[in]nameComparison object.
[in]modeComparision mode.
Returns
The comparison result.

◆ GetData()

MAXON_METHOD Result<Data> GetData ( const ConstDataPtr key) const

Returns Url attributes. See maxon::URLFLAGS for details.

Parameters
[in]keyThe id of the property to get. The possible values for id depend on the scheme.
Returns
The attribute value or an error if there was none.

◆ SetData() [1/2]

MAXON_METHOD Result<void> SetData ( ForwardingDataPtr &&  key,
const Data data,
Bool  persistent = true 
)

Modifies or sets a Url attribute. See maxon::URLFLAGS for details.

Parameters
[in]keyThe id of the property to set. The possible values for id depend on the scheme.
[in]dataData to be set.
[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.

◆ SetData() [2/2]

MAXON_METHOD Result<void> SetData ( ForwardingDataPtr &&  key,
Data &&  data,
Bool  persistent = true 
)

Modifies or sets a Url attribute. See maxon::URLFLAGS for details.

Parameters
[in]keyThe id of the property to set. The possible values for id depend on the scheme.
[in]dataData to be set.
[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.

◆ EraseData()

MAXON_METHOD Result<void> EraseData ( ForwardingDataPtr &&  key,
Bool  persistent = true 
)

EraseData removes data from the data dictionary

Parameters
[in]keyThe id of the property to erase. The possible values for id depend on the scheme.
[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.

◆ IoDetect()

MAXON_FUNCTION IODETECT IoDetect ( ) const

Detects the type of the object behind Url. This allows to check if a file or directory exists.

Returns
IODETECT of the given Url.

◆ OpenConnection()

MAXON_FUNCTION Result<IoConnectionRef> OpenConnection ( ) const

Returns a pointer to a IoConnectionInterface class of this Url.

Returns
The pointer to the IoConnectionInterface. The return value needs to be checked against nullptr.

◆ OpenInputStream()

MAXON_FUNCTION Result<InputStreamRef> OpenInputStream ( OPENSTREAMFLAGS  flags = OPENSTREAMFLAGS::NONE) const

Returns a pointer to a InputStreamInterface class of this Url.

Parameters
[in]flagsSee OPENSTREAMFLAGS for details.
Returns
The pointer to the InputStreamInterface. The return value needs to be checked against nullptr.

◆ OpenOutputStream()

MAXON_FUNCTION Result<OutputStreamRef> OpenOutputStream ( OPENSTREAMFLAGS  flags = OPENSTREAMFLAGS::NONE) const

Returns a pointer to a OutputStreamInterface class of this Url.

Parameters
[in]flagsSee OPENSTREAMFLAGS for details.
Returns
The pointer to the OutputStreamInterface. The return value needs to be checked against nullptr.

◆ OpenInOutputStream()

MAXON_FUNCTION Result<InOutputStreamRef> OpenInOutputStream ( OPENSTREAMFLAGS  flags = OPENSTREAMFLAGS::NONE) const

Returns a pointer to a InOutputStreamInterface class of this Url.

Parameters
[in]flagsSee OPENSTREAMFLAGS for details.
Returns
The pointer to the InOutputStreamInterface. The return value needs to be checked against nullptr.

◆ GetBrowseIterator()

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.

path.SetPath("h:/testdir"_s);
for (const auto& it : path.GetBrowseIterator(GETBROWSEITERATORFLAGS::NONE))
{
// it's essential that error checking happens here at this point.
// this error can be opening the directory as well as browsing to the next file.
const IoBrowseRef& browseRef = (it) iferr_return;
// do anything like browseRef.GetCurrentPath();
}
static const Id URLSCHEME_FILESYSTEM
Scheme identifier for generic file system access.
Definition: url.h:681
@ NONE
No flags specified.
#define iferr_return
Definition: resultbase.h:1465
Parameters
[in]flagsSee GETBROWSEITERATORFLAGS.
Returns
IoBrowseIterator object.

◆ IoGetAttributes()

MAXON_FUNCTION Result<IOATTRIBUTES> IoGetAttributes ( ) const

Returns the file attributes of the object behind Url.

Returns
IOATTRIBUTES of the file.

◆ IoSetAttributes()

MAXON_FUNCTION Result<void> IoSetAttributes ( IOATTRIBUTES  flags,
IOATTRIBUTES  mask 
) const

Modify the file attributes of the object behind Url.

Parameters
[in]flagsFlags to set/clear.
[in]maskMask with all flags to be changed.
Returns
OK on success.

◆ IoGetTime()

MAXON_FUNCTION Result<UniversalDateTime> IoGetTime ( IOTIMEMODE  mode) const

Returns the DateTime of the current file. The time is in local time.

Parameters
[in]modeIOTIMEMODE of the requested time.
Returns
Returns the DateTime or an error.

◆ IoSetTime()

MAXON_FUNCTION Result<void> IoSetTime ( IOTIMEMODE  mode,
const UniversalDateTime dateTime 
) const

Modifies the DateTime of the current file. The time is in local time.

Parameters
[in]modeIOTIMEMODE of the requested time.
[in]dateTimeThe new datetime for the file.
Returns
OK on success.

◆ IoDelete()

MAXON_FUNCTION Result<void> IoDelete ( Bool  force,
Bool  recursive = false 
) const

Deletes a file or directory physically on the medium.

Parameters
[in]forceSet to true tries to deletes the file/directory even if the file/directory has read only flags set.
[in]recursiveRecursively deletes a directory and its content. If a file is specified this value is ignored.
Returns
Set to true if the file/directory could be removed successfully.

◆ IoCreateDirectory()

MAXON_FUNCTION Result<void> IoCreateDirectory ( Bool  createParents,
BaseArray< Url > *  createdDirs = nullptr 
) const

Creates a new directory. The function will return false if the directory already exists.

Parameters
[in]createParentsCheck if parent directory exists and if not create them recursively.
[out]createdDirsAn 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.
Returns
Set to true if the directory could be created successfully.

◆ IoCopyFile()

MAXON_FUNCTION Result<void> IoCopyFile ( const Url destName,
Bool  overwrite,
Bool  removeReadOnly,
const IoProgressDelegate progress = IoProgressDelegate() 
) const

Copies a file to a different location, the path must exist otherwise the function returns an error.

Parameters
[in]destNameDestination name for the copy operation.
[in]overwriteSet to true to allow overwriting destName file if it was already there.
[in]removeReadOnlySet to true to remove the read only flag on the newly created copy.
[in]progressProgress delegate.
Returns
OK on success.

◆ IoMove()

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.

Parameters
[in]destNameDestination name for the move operation.
Returns
OK on success.

◆ IoRename()

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.

Parameters
[in]newNameDestination name for the move operation.
Returns
OK on success.

◆ IoGetFreeVolumeSpace()

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.

Parameters
[out]availableBytesThe number of available bytes on the volume.
[out]totalBytesThe total size of the volume in bytes.
Returns
OK on success.

◆ IoShowInOS()

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.

Parameters
[in]flagsFlags to define how to open that file.
Returns
OK on success.

◆ Normalize()

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.

Parameters
[in]flagsFlags to define type of normalization.
Returns
The normalized url. In case of a normalization error *this is returned.

◆ IoNormalize()

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.

Parameters
[in]flagsFlags to define type of normalization.
Returns
The normalized and resolved url. In case of a normalization error *this is returned.

◆ ToString()

MAXON_METHOD String ToString ( const FormatStatement formatStatement = nullptr) const

Returns a readable string of the content.

Parameters
[in]formatStatementNullptr or additional formatting instruction. Currently no additional formatting instructions are supported.
Returns
The converted result.

◆ ToCString()

MAXON_METHOD CString ToCString ( ) const

Returns a readable string of the content.

Returns
The converted result.

◆ ConvertToUiName()

MAXON_METHOD Result<String> ConvertToUiName ( CONVERTTOUINAMEFLAGS  flags) const

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

Parameters
[in]flagsFlags for the conversion, see CONVERTTOUINAMEFLAGS.
Returns
String on success.

◆ ConvertFromUiName()

static MAXON_METHOD Result<Url> ConvertFromUiName ( const String str)
static

ConvertFromUiName converts a string into a url.

Parameters
[in]strString to convert.
Returns
Url on success. Please note that the url might be translated into another scheme (e.g. assetdb:// -> asset://).

◆ DescribeIO()

static MAXON_METHOD Result<void> DescribeIO ( const DataSerializeInterface stream)
static

Describe all elements of this class for I/O operations.

Parameters
[in]streamThe stream that is used to register the class members.
Returns
OK on success.

◆ GetHashCode()

MAXON_FUNCTION HashInt GetHashCode ( ) const

Returns the hash code of this @CLASS.

Returns
Hash code of this @CLASS.

◆ GetUniqueHashCode()

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.

Returns
Hash value of this @CLASS.

◆ ConvertToUiNameWithRepository()

MAXON_METHOD Result<String> ConvertToUiNameWithRepository ( 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.

Parameters
[in]flagsFlags for the conversion, see CONVERTTOUINAMEFLAGS.
[in]lookupRepositoryAssetRespoitory to search in.
Returns
String on success.

◆ ConvertFromUiNameWithRepository()

static MAXON_METHOD Result<Url> ConvertFromUiNameWithRepository ( const String str,
const AssetRepositoryRef &  lookupRepository 
)
static

ConvertFromUiName converts a string into a url.

Parameters
[in]strString to convert.
[in]lookupRepositoryAssetRespoitory to search in.
Returns
Url on success. Please note that the url might be translated into another scheme (e.g. assetdb:// -> asset://).