QUrl Class

Detailed Description

It can parse and construct URLs in both encoded and unencoded form. QUrl also has support for internationalized domain names (IDNs).

The most common way to use QUrl is to initialize it via the constructor by passing a QString. Otherwise, setUrl() can also be used.

URLs can be represented in two forms: encoded or unencoded. The unencoded representation is suitable for showing to users, but the encoded representation is typically what you would send to a web server. For example, the unencoded URL "http://bühler.example.com/List of applicants.xml" would be sent to the server as "http://xn--bhler-kva.example.com/List%20of%20applicants.xml".

A URL can also be constructed piece by piece by calling setScheme(), setUserName(), setPassword(), setHost(), setPort(), setPath(), setQuery() and setFragment(). Some convenience functions are also available: setAuthority() sets the user name, password, host and port. setUserInfo() sets the user name and password at once.

Call isValid() to check if the URL is valid. This can be done at any point during the constructing of a URL. If isValid() returns false, you should clear() the URL before proceeding, or start over by parsing a new URL with setUrl().

Constructing a query is particularly convenient through the use of the QUrlQuery class and its methods QUrlQuery::setQueryItems(), QUrlQuery::addQueryItem() and QUrlQuery::removeQueryItem(). Use QUrlQuery::setQueryDelimiters() to customize the delimiters used for generating the query string.

For the convenience of generating encoded URL strings or query strings, there are two static functions called fromPercentEncoding() and toPercentEncoding() which deal with percent encoding and decoding of QString objects.

fromLocalFile() constructs a QUrl by parsing a local file path. toLocalFile() converts a URL to a local file path.

The human readable representation of the URL is fetched with toString(). This representation is appropriate for displaying a URL to a user in unencoded form. The encoded form however, as returned by toEncoded(), is for internal use, passing to web servers, mail clients and so on. Both forms are technically correct and represent the same URL unambiguously -- in fact, passing either form to QUrl's constructor or to setUrl() will yield the same QUrl object.

QUrl conforms to the URI specification from RFC 3986 (Uniform Resource Identifier: Generic Syntax), and includes scheme extensions from RFC 1738 (Uniform Resource Locators). Case folding rules in QUrl conform to RFC 3491 (Nameprep: A Stringprep Profile for Internationalized Domain Names (IDN)). It is also compatible with the file URI specification from freedesktop.org, provided that the locale encodes file names using UTF-8 (required by IDN).

Relative URLs vs Relative Paths

Calling isRelative() will return whether or not the URL is relative. A relative URL has no scheme. For example:

     qDebug() << QUrl("main.qml").isRelative();          // true: no scheme
     qDebug() << QUrl("qml/main.qml").isRelative();      // true: no scheme
     qDebug() << QUrl("file:main.qml").isRelative();     // false: has "file" scheme
     qDebug() << QUrl("file:qml/main.qml").isRelative(); // false: has "file" scheme

Notice that a URL can be absolute while containing a relative path, and vice versa:

     // Absolute URL, relative path
     QUrl url("file:file.txt");
     qDebug() << url.isRelative();                 // false: has "file" scheme
     qDebug() << QDir::isAbsolutePath(url.path()); // false: relative path

     // Relative URL, absolute path
     url = QUrl("/home/user/file.txt");
     qDebug() << url.isRelative();                 // true: has no scheme
     qDebug() << QDir::isAbsolutePath(url.path()); // true: absolute path

A relative URL can be resolved by passing it as an argument to resolved(), which returns an absolute URL. isParentOf() is used for determining whether one URL is a parent of another.

Error checking

QUrl is capable of detecting many errors in URLs while parsing it or when components of the URL are set with individual setter methods (like setScheme(), setHost() or setPath()). If the parsing or setter function is successful, any previously recorded error conditions will be discarded.

By default, QUrl setter methods operate in QUrl::TolerantMode, which means they accept some common mistakes and mis-representation of data. An alternate method of parsing is QUrl::StrictMode, which applies further checks. See QUrl::ParsingMode for a description of the difference of the parsing modes.

QUrl only checks for conformance with the URL specification. It does not try to verify that high-level protocol URLs are in the format they are expected to be by handlers elsewhere. For example, the following URIs are all considered valid by QUrl, even if they do not make sense when used:

• "http:/filename.html"
• "mailto://example.com"

When the parser encounters an error, it signals the event by making isValid() return false and toString() / toEncoded() return an empty string. If it is necessary to show the user the reason why the URL failed to parse, the error condition can be obtained from QUrl by calling errorString(). Note that this message is highly technical and may not make sense to end-users.

QUrl is capable of recording only one error condition. If more than one error is found, it is undefined which error is reported.

Character Conversions

Follow these rules to avoid erroneous character conversion when dealing with URLs and strings:

• When creating a QString to contain a URL from a QByteArray or a char*, always use QString::fromUtf8().