class CCL::Url

Overview

#include <url.h>

class Url:
    public CCL::Object,
    public CCL::IUrl
{
public:
    // classes

    class Comparer;

    // fields

    static const Url kEmpty;
    static const String strPathChar = CCLSTR ("/");
    static const String strBackslash = CCLSTR ("\\");
     IUrl;

    // construction

    Url (StringRef url, int type = kFile);
    Url (StringRef protocol, StringRef hostname, StringRef path, int type = kFile);
    Url (UrlRef url);
    Url (StringRef relative, UrlRef baseUrl, int type = kFile);
    Url (const Url& url);

    // methods

    DECLARE_CLASS (Url, Object);
    virtual void CCL_API clone (IUrl*& url) const;
    virtual void CCL_API assign (UrlRef url);
    virtual tbool CCL_API isEqualUrl (UrlRef url, tbool withParameters = true) const;
    virtual tbool CCL_API isEmpty () const;
    virtual int CCL_API getType () const;
    virtual void CCL_API getUrl (String& url, tbool withParameters = false) const;
    virtual void CCL_API setUrl (StringRef url, int type = kFile);
    virtual StringRef CCL_API getProtocol () const;
    virtual void CCL_API setProtocol (StringRef protocol);
    virtual StringRef CCL_API getHostName () const;
    virtual void CCL_API setHostName (StringRef name);
    virtual StringRef CCL_API getPath () const;
    virtual void CCL_API setPath (StringRef path, int type = kIgnore);
    virtual void CCL_API getPathName (String& pathName) const;
    virtual void CCL_API getName (String& name, tbool withExtension = true) const;
    virtual void CCL_API setName (StringRef name, int type = kIgnore);
    virtual tbool CCL_API getExtension (String& ext) const;
    virtual void CCL_API setExtension (StringRef ext, tbool replace = true);
    virtual const FileType&CCL_API getFileType () const;

    virtual void CCL_API setFileType (
        const FileType& type,
        tbool replaceExtension = true
    );

    virtual tbool CCL_API isRootPath () const;
    virtual tbool CCL_API isNativePath () const;
    virtual tbool CCL_API toNativePath (uchar* pathBuffer, int bufferSize) const;
    virtual tbool CCL_API fromNativePath (const uchar* pathBuffer, int type = kFile);
    virtual tbool CCL_API toPOSIXPath (char* pathBuffer, int bufferSize) const;
    virtual tbool CCL_API fromPOSIXPath (const char* pathBuffer, int type = kFile);

    virtual tbool CCL_API toDisplayString (
        String& displayString,
        int which = kStringNativePath
    ) const;

    virtual tbool CCL_API fromDisplayString (
        StringRef displayString,
        int type = kFile
    );

    virtual tbool CCL_API isAbsolute () const;
    virtual tbool CCL_API isRelative () const;
    virtual tbool CCL_API makeAbsolute (UrlRef baseUrl);
    virtual tbool CCL_API makeRelative (UrlRef baseUrl);
    virtual tbool CCL_API ascend ();
    virtual tbool CCL_API descend (StringRef name, int type = kFile);
    virtual void CCL_API normalize (int flags);
    virtual IStringDictionary&CCL_API getParameters () const;
    virtual void CCL_API getParameters (String& params) const;
    virtual void CCL_API setParameters (StringRef params);
    virtual tbool CCL_API hasParameters () const;
    bool isCaseSensitive () const;
    bool contains (UrlRef childUrl) const;
    Url& makeUnique (bool forceSuffix = false);
    Url& makeUnique (IFileSystem& fileSystem, bool forceSuffix = false);
    void fromRelativePath (StringRef relative, UrlRef baseUrl, int type = kFile);
    virtual bool equals (const Object& obj) const;
    virtual bool load (const Storage& storage);
    virtual bool save (const Storage& storage) const;
    Url& operator = (const Url& url);
    Url& operator = (const IUrl& url);
    bool operator == (UrlRef url) const;
    bool operator != (UrlRef url) const;
    static bool isUrlString (StringRef string);
    static bool isRelativePathString (StringRef relative);
};

Inherited Members

public:
    // typedefs

    typedef CStringRef MemberID;

    // enums

    enum NormalizationFlags;
    enum StringTypes;
    enum Types;

    // methods

    virtual tresult CCL_API queryInterface (UIDRef iid, void** ptr) = 0;
    virtual unsigned int CCL_API retain () = 0;
    virtual unsigned int CCL_API release () = 0;
    Unknown& operator = (const Unknown&);
    unsigned int getRetainCount () const;
    virtual Object*CCL_API revealObject (const void* moduleAddress) = 0;
    virtual void CCL_API addObserver (IObserver* observer) = 0;
    virtual void CCL_API removeObserver (IObserver* observer) = 0;
    virtual void CCL_API signal (MessageRef msg) = 0;
    virtual void CCL_API deferSignal (IMessage* msg) = 0;
    static ISubject void addObserver (IUnknown* unknown, IObserver* observer);
    static void removeObserver (IUnknown* unknown, IObserver* observer);
    virtual void CCL_API notify (ISubject* subject, MessageRef msg) = 0;

    static IObserver void notify (
        IUnknown* unknown,
        ISubject* subject,
        MessageRef msg
    );

    virtual const ITypeInfo&CCL_API getTypeInfo () const = 0;
    virtual tbool CCL_API getProperty (Variant& var, MemberID propertyId) const = 0;
    virtual tbool CCL_API setProperty (MemberID propertyId, const Variant& var) = 0;
    virtual tbool CCL_API getPropertyNames (IPropertyCollector& collector) const = 0;
    virtual tbool CCL_API invokeMethod (Variant& returnValue, MessageRef msg) = 0;
    DECLARE_BASE_CLASS (Object);
    virtual void CCL_API removeObserver (IObserver* observer);
    virtual void CCL_API signal (MessageRef msg);
    virtual void CCL_API deferSignal (IMessage* msg);
    virtual void deferChanged ();
    virtual void CCL_API notify (ISubject* subject, MessageRef msg);
    virtual bool equals (const Object& obj) const;
    virtual int compare (const Object& obj) const;
    virtual bool load (const Storage& storage);
    virtual bool save (const Storage& storage) const;
    virtual bool save (const OutputStorage& storage) const;
    virtual bool toString (String& string, int flags = 0) const;
    virtual int getHashCode (int size) const;
    IUnknown* asUnknown ();
    static void addGarbageCollected (Object* obj, bool globalScope = true);
    static void deferDestruction (Object* obj);
    static const void* getModuleAddress ();
    virtual void CCL_API clone (IUrl*& url) const = 0;
    virtual void CCL_API assign (UrlRef url) = 0;
    virtual tbool CCL_API isEqualUrl (UrlRef url, tbool withParameters = true) const = 0;
    virtual tbool CCL_API isEmpty () const = 0;
    virtual int CCL_API getType () const = 0;
    virtual void CCL_API getUrl (String& url, tbool withParameters = false) const = 0;
    virtual void CCL_API setUrl (StringRef url, int type = kFile) = 0;
    virtual StringRef CCL_API getProtocol () const = 0;
    virtual void CCL_API setProtocol (StringRef protocol) = 0;
    virtual StringRef CCL_API getHostName () const = 0;
    virtual void CCL_API setHostName (StringRef name) = 0;
    virtual StringRef CCL_API getPath () const = 0;
    virtual void CCL_API setPath (StringRef path, int type = kIgnore) = 0;
    virtual void CCL_API getPathName (String& pathName) const = 0;
    virtual void CCL_API getName (String& name, tbool withExtension = true) const = 0;
    virtual void CCL_API setName (StringRef name, int type = kIgnore) = 0;
    virtual tbool CCL_API getExtension (String& ext) const = 0;
    virtual void CCL_API setExtension (StringRef ext, tbool replace = true) = 0;
    virtual const FileType&CCL_API getFileType () const = 0;

    virtual void CCL_API setFileType (
        const FileType& type,
        tbool replaceExtension = true
    ) = 0;

    virtual tbool CCL_API isRootPath () const = 0;
    virtual tbool CCL_API isNativePath () const = 0;
    virtual tbool CCL_API toNativePath (uchar* pathBuffer, int bufferSize) const = 0;
    virtual tbool CCL_API fromNativePath (const uchar* pathBuffer, int type = kFile) = 0;
    virtual tbool CCL_API toPOSIXPath (char* pathBuffer, int bufferSize) const = 0;
    virtual tbool CCL_API fromPOSIXPath (const char* pathBuffer, int type = kFile) = 0;

    virtual tbool CCL_API toDisplayString (
        String& displayString,
        int which = kStringNativePath
    ) const = 0;

    virtual tbool CCL_API fromDisplayString (
        StringRef displayString,
        int type = kFile
    ) = 0;

    virtual tbool CCL_API isAbsolute () const = 0;
    virtual tbool CCL_API isRelative () const = 0;
    virtual tbool CCL_API makeAbsolute (UrlRef baseUrl) = 0;
    virtual tbool CCL_API makeRelative (UrlRef baseUrl) = 0;
    virtual tbool CCL_API ascend () = 0;
    virtual tbool CCL_API descend (StringRef name, int type = kFile) = 0;
    virtual void CCL_API normalize (int flags) = 0;
    virtual IStringDictionary&CCL_API getParameters () const = 0;
    virtual void CCL_API getParameters (String& params) const = 0;
    virtual void CCL_API setParameters (StringRef params) = 0;
    virtual tbool CCL_API hasParameters () const = 0;
    IUrl bool isFile () const;
    bool isFolder () const;
    IUrl& operator = (UrlRef url);

Detailed Documentation

Construction

Url (StringRef url, int type = kFile)

Construct from a URL string.

Parameters:

url

A URL string in the form <protocol>://<hostname>/<path>, see also https://datatracker.ietf.org/doc/html/rfc1738 This constructor URL-decodes URL parameters, but does not decode protocol, hostname, or path. See also UrlUtils::fromEncodedString. If you need to convert a display string to a URL, consider using fromDisplayString or fromNativePath instead.

Url (StringRef protocol, StringRef hostname, StringRef path, int type = kFile)

Construct from protocol, hostname and path.

Url (UrlRef url)

Copy constructor.

Url (StringRef relative, UrlRef baseUrl, int type = kFile)

Construct from a base URL and a relative path string.

Equivalent to calling fromRelativePath.

Methods

DECLARE_CLASS (Url, Object)

Construct an empty URL.

virtual void CCL_API clone (IUrl*& url) const

Clone URL object.

virtual void CCL_API assign (UrlRef url)

Assign from other URL reference.

virtual tbool CCL_API isEqualUrl (UrlRef url, tbool withParameters = true) const

Check two URLs for equality.

virtual tbool CCL_API isEmpty () const

Check if URL is empty.

virtual int CCL_API getType () const

Get URL type (file or folder).

virtual void CCL_API getUrl (String& url, tbool withParameters = false) const

Get full URL string (e.g.

“file://localhost/folder1/folder2/file.ext”).

virtual void CCL_API setUrl (StringRef url, int type = kFile)

Set full URL string and type.

virtual StringRef CCL_API getProtocol () const

Get protocol string (e.g.

“file”).

virtual void CCL_API setProtocol (StringRef protocol)

Set protocol string.

virtual StringRef CCL_API getHostName () const

Get host string (e.g.

“localhost”).

virtual void CCL_API setHostName (StringRef name)

Set host string.

virtual StringRef CCL_API getPath () const

Get path string (folder + file name, e.g.

“folder1/folder2/file.ext”).

virtual void CCL_API setPath (StringRef path, int type = kIgnore)

Set path string (folder + file name).

virtual void CCL_API getPathName (String& pathName) const

Get path name without file name (e.g.

“folder1/folder2”).

virtual void CCL_API getName (String& name, tbool withExtension = true) const

Get file name with or without extension (e.g.

“file” or “file.ext”).

virtual void CCL_API setName (StringRef name, int type = kIgnore)

Set file name and extension.

virtual tbool CCL_API getExtension (String& ext) const

Get extension string (e.g.

“ext”)

virtual void CCL_API setExtension (StringRef ext, tbool replace = true)

Set extension string, either by appending or replacing the existing one (e.g.

“file.new” or “file.old.new”).

virtual const FileType&CCL_API getFileType () const

Get file type (extension + description + MIME type).

Not all fields are guaranteed to be valid.

virtual void CCL_API setFileType (
    const FileType& type,
    tbool replaceExtension = true
)

Set extension with file type, either by appending or replacing the existing one.

virtual tbool CCL_API isRootPath () const

Check if URL is a root path (e.g.

path is empty or “/” or “C:”).

virtual tbool CCL_API isNativePath () const

Check if URL is a native path using “file” protocol (e.g.

“file:///C:/folder/file.ext”).

virtual tbool CCL_API toNativePath (uchar* pathBuffer, int bufferSize) const

Convert to native path string in UTF-16 enconding (e.g.

“C:folderfile.ext” or “Volumes/folder/file.ext”).

virtual tbool CCL_API fromNativePath (const uchar* pathBuffer, int type = kFile)

Assign native path.

On Windows a path string like “C:...” will be mapped to “file:///C:/…”.

virtual tbool CCL_API toPOSIXPath (char* pathBuffer, int bufferSize) const

Convert to POSIX-style path (‘/’ as separator) in UTF-8 encoding.

virtual tbool CCL_API fromPOSIXPath (const char* pathBuffer, int type = kFile)

Assign from POSIX-style path.

virtual tbool CCL_API toDisplayString (
    String& displayString,
    int which = kStringNativePath
) const

Get beautified string for display respecting the platform conventions.

virtual tbool CCL_API fromDisplayString (
    StringRef displayString,
    int type = kFile
)

Assign path from native display string, following platform conventions.

virtual tbool CCL_API isAbsolute () const

Check if it is an absolute path.

virtual tbool CCL_API isRelative () const

Check if it is a relative path.

virtual tbool CCL_API makeAbsolute (UrlRef baseUrl)

Make relative URL absolute to base URL.

virtual tbool CCL_API makeRelative (UrlRef baseUrl)

Make absolute URL relative to given base URL.

virtual tbool CCL_API ascend ()

Ascend one directory level (e.g.

“folder1/folder2” becomes “folder1”).

virtual tbool CCL_API descend (StringRef name, int type = kFile)

Descend one directory level appending given name and type.

virtual void CCL_API normalize (int flags)

Normalize URL with given options.

virtual IStringDictionary&CCL_API getParameters () const

Access to dictionary with (decoded) parameters.

virtual void CCL_API getParameters (String& params) const

Get parameters as URL-encoded string.

virtual void CCL_API setParameters (StringRef params)

Set parameters from URL-encoded string.

virtual tbool CCL_API hasParameters () const

Check if URL has parameters.