Класс QUrl

Класс QUrl предоставляет удобный интерфейс для работы с URL-адресами. Подробнее...

• Список всех членов, включая унаследованные

Примечание: Все функции в этом классе являются реентерабельными.

Публичные типы

Публичные функции

Статические публичные члены

Связанные нечлены

Макросы

Подробное описание

Она может анализировать и создавать URL как в кодированном, так и в некодированном виде. QUrl также поддерживает международные доменные имена (IDN).

Наиболее распространённый способ использования QUrl — инициализировать его через конструктор, передав QString. В противном случае, можно также использовать setUrl().

URL могут быть представлены в двух формах: кодированной и некодированной. Некодированная форма подходит для отображения пользователю, но кодированная форма обычно используется при отправке на веб-сервер. Например, некодированный URL «http://bühler.example.com/List of applicants.xml» будет отправлен на сервер как «http://xn--bhler-kva.example.com/List%20of%20applicants.xml».

URL также можно создавать по частям, вызывая setScheme(), setUserName(), setPassword(), setHost(), setPort(), setPath(), setQuery() и setFragment(). Также доступны некоторые удобные функции: setAuthority() задаёт имя пользователя, пароль, хост и порт. setUserInfo() задаёт имя пользователя и пароль сразу.

Вызовите isValid(), чтобы проверить, является ли URL допустимым. Это можно сделать в любой момент во время построения URL. Если isValid() возвращает false, вы должны clear() URL перед продолжением или начать заново, проанализировав новый URL с помощью setUrl().

Создание запроса особенно удобно с использованием класса QUrlQuery и его методов QUrlQuery::setQueryItems(), QUrlQuery::addQueryItem() и QUrlQuery::removeQueryItem(). Используйте QUrlQuery::setQueryDelimiters(), чтобы настроить разделители, используемые для генерации строки запроса.

Для удобства генерации кодированных строк URL или строк запроса есть две статические функции fromPercentEncoding() и toPercentEncoding(), которые занимаются кодированием и декодированием процентов в объектах QString.

fromLocalFile() создаёт QUrl, анализируя локальный путь к файлу. toLocalFile() преобразует URL в локальный путь к файлу.

Человекочитаемая форма URL извлекается с помощью toString(). Эта форма подходит для отображения URL пользователю в некодированном виде. Кодированная форма, возвращаемая toEncoded(), используется для внутренних целей, передачи веб-серверам, почтовым клиентам и т. д. Обе формы технически верны и однозначно представляют один и тот же URL — на самом деле, передача любой формы в конструктор QUrl или в setUrl() приведет к созданию одного и того же объекта QUrl.

QUrl соответствует спецификации URI из RFC 3986 (Унифицированный идентификатор ресурса: Общий синтаксис) и включает расширения схемы из RFC 1738 (Унифицированные указатели ресурсов). Правила преобразования регистра в QUrl соответствуют RFC 3491 (Nameprep: Профиль Stringprep для международных доменных имён (IDN)). Он также совместим со спецификацией файла URI с freedesktop.org, при условии, что локаль кодирует имена файлов с использованием UTF-8 (требуется IDN).

Относительные URL-адреса против относительных путей

Вызов isRelative() вернёт true, если URL относительный. Относительный URL-адрес не имеет схемы. Например:

    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

Обратите внимание, что URL-адрес может быть абсолютным, содержа при этом относительный путь, и наоборот:

    // 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

Относительный URL-адрес можно разрешить, передав его в качестве аргумента в resolved(), которое возвращает абсолютный URL. isParentOf() используется для определения того, является ли один URL родителем другого.

Обработка ошибок

QUrl способен обнаруживать множество ошибок в URL при его анализе или когда компоненты URL устанавливаются с помощью отдельных методов-установщиков (например, setScheme(), setHost() или setPath()). Если функция анализа или установки успешно выполняется, все ранее записанные состояния ошибок будут удалены.

По умолчанию методы установки QUrl работают в режиме QUrl::TolerantMode, что означает, что они принимают некоторые распространённые ошибки и некорректное представление данных. Альтернативный метод анализа — QUrl::StrictMode, который выполняет дополнительные проверки. Обратитесь к QUrl::ParsingMode для описания различий в режимах анализа.

QUrl проверяет только соответствие спецификации URL. Он не пытается проверить, что URL-адреса высокого уровня протокола имеют ожидаемый формат для обработчиков в другом месте. Например, следующие URI считаются допустимыми QUrl, даже если они не имеют смысла в использовании:

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

При обнаружении ошибки анализатор сигнализирует об этом, делая isValid() равным false и toString() / toEncoded() возвращающими пустую строку. Если необходимо показать пользователю причину, по которой URL не удалось проанализировать, состояние ошибки можно получить из QUrl, вызвав errorString(). Обратите внимание, что это сообщение очень техническое и может быть непонятным для конечных пользователей.

QUrl способен записывать только одно состояние ошибки. Если обнаружено более одной ошибки, не определено, какая ошибка будет сообщена.

Преобразования символов

Следуйте этим правилам, чтобы избежать ошибочных преобразований символов при работе с URL-адресами и строками:

• При создании QString для хранения URL из QByteArray или char*, всегда используйте QString::fromUtf8().

Документация по типу членов

[since 5.0] перечисление QUrl::ComponentFormattingOptionфлаги QUrl::ComponentFormattingOptions

Параметры форматирования компонентов определяют, как компоненты URL будут отформатированы при записи в виде текста. Их можно комбинировать с параметрами из QUrl::FormattingOptions при использовании в toString() и toEncoded().

Значения EncodeReserved и DecodeReserved не следует использовать вместе в одном вызове. Поведение в этом случае не определено. Они предоставляются как отдельные значения, потому что поведение "красивого режима" по отношению к зарезервированным символам отличается в определенных компонентах и особенно в полном URL.

Полное декодирование

Режим FullyDecoded аналогичен поведению функций, возвращающих QString в Qt 4.x, в том смысле, что каждый символ представляет собой самого себя и никогда не имеет никакого специального значения. Это верно даже для символа процента ('%'), который должен интерпретироваться как буквальный процент, а не как начало последовательности, закодированной с использованием процентов. Тот же самый символ во всех других режимах декодирования представляется последовательностью "%25".

При повторном применении данных, полученных с помощью QUrl::FullyDecoded в QUrl, необходимо учитывать использование параметра QUrl::DecodedMode в установщиках (например, setPath() и setUserName()). Несоблюдение этого может привести к повторной интерпретации символа процента ('%') как начала последовательности, закодированной с использованием процентов.

Этот режим очень полезен, когда части URL используются в контексте, не связанном с URL. Например, для извлечения имени пользователя, пароля или путей к файлам в приложении FTP-клиента следует использовать режим FullyDecoded.

Этот режим следует использовать с осторожностью, так как есть две ситуации, которые не могут быть надежно представлены в возвращаемом QString.

• Последовательности, не являющиеся UTF-8: URL могут содержать последовательности закодированных с использованием процентов символов, которые не образуют допустимые UTF-8 последовательности. Поскольку URL необходимо декодировать с использованием UTF-8, любая ошибка декодера приведет к тому, что QString будет содержать один или несколько символов замены там, где существовала последовательность.
• Закодированные разделители: URL также могут различать разделитель в его буквальной форме и его эквивалент в закодированном с использованием процентов виде. Это чаще всего встречается в запросе, но допускается во многих частях URL.

Следующий пример иллюстрирует проблему:

    QUrl original("http://example.com/?q=a%2B%3Db%26c");
    QUrl copy(original);
    copy.setQuery(copy.query(QUrl::FullyDecoded), QUrl::DecodedMode);

    qDebug() << original.toString();   // prints: http://example.com/?q=a%2B%3Db%26c
    qDebug() << copy.toString();       // prints: http://example.com/?q=a+=b&c

Если бы эти два URL использовались через HTTP GET, интерпретация веб-сервером, вероятно, была бы другой. В первом случае он интерпретировал бы его как один параметр с ключом "q" и значением "a+=b&c". Во втором случае он, вероятно, интерпретировал бы его как два параметра: один с ключом "q" и значением "a =b", а второй с ключом "c" и без значения.

Этот перечисление был введён или изменён в Qt 5.0.

Тип ComponentFormattingOptions является типом typedef для QFlags<ComponentFormattingOption>. Он хранит комбинацию значений ComponentFormattingOption, полученную с помощью операции OR.

См. также QUrl::FormattingOptions.

Перечисление QUrl::ParsingMode

Режим разбора управляет способом, которым QUrl анализирует строки.

В режиме TolerantMode поведение парсера следующее:

• Пробелы и "%20": не закодированные пробелы будут приняты и будут рассматриваться как эквивалент "%20".
• Одиночные символы "%": Любые случаи символа процента "%", за которым не следует ровно два шестнадцатеричных символа (например, "13% coverage.html"), будут заменены на "%25". Обратите внимание, что один одиночный символ "%" вызовет режим исправления для всех символов процента.
• Зарезервированные и незарезервированные символы: Закодированный URL должен содержать только несколько символов как литералы; все остальные символы должны быть закодированы с использованием процентов. В режиме TolerantMode эти символы будут приняты, если они найдены в URL: пробел / двойная кавычка / "<" / ">" / "" / "^" / "`" / "{" / "|" / "}". Те же самые символы могут быть декодированы повторно, передав QUrl::DecodeReserved в toString() или toEncoded(). В методах получения отдельных компонентов эти символы часто возвращаются в декодированном виде.

В режиме StrictMode, если обнаружена ошибка парсинга, isValid() вернёт false а errorString() вернёт сообщение об ошибке. Если обнаружено более одной ошибки, поведение неопределённо.

Обратите внимание, что режима TolerantMode обычно недостаточно для разбора пользовательского ввода, который часто содержит больше ошибок и ожиданий, чем парсер может обработать. При работе с данными, поступающими непосредственно от пользователя (в отличие от данных, поступающих из источников передачи данных, таких как другие программы), рекомендуется использовать fromUserInput().

См. также fromUserInput(), setUrl(), toString(), toEncoded(), и QUrl::FormattingOptions.

Перечисление QUrl::UrlFormattingOptionфлаги QUrl::FormattingOptions

Параметры форматирования определяют, как URL форматируется при записи в виде текста.

Обратите внимание, что правила преобразования регистра в Nameprep, которым соответствует QUrl, требуют, чтобы имена хостов всегда преобразовывались в нижний регистр, независимо от используемых Qt::FormattingOptions.

Также возможны опции из QUrl::ComponentFormattingOptions.

Тип FormattingOptions является псевдонимом для QFlags<UrlFormattingOption>. Он хранит сочетание значений UrlFormattingOption.

См. также QUrl::ComponentFormattingOptions.

[since 5.4] перечисление QUrl::UserInputResolutionOptionфлаги QUrl::UserInputResolutionOptions

Параметры разрешения пользовательского ввода определяют, как fromUserInput() должен интерпретировать строки, которые могут быть относительным путем или коротким форматом HTTP URL. Например, file.pl может быть как локальным файлом, так и URL http://file.pl.

Это перечисление было введено или изменено в Qt 5.4.

Тип UserInputResolutionOptions — это псевдоним для QFlags<UserInputResolutionOption>. Он хранит сочетание значений UserInputResolutionOption.

См. также fromUserInput().

Документация по членам функций

[since 5.2] QUrl::QUrl(QUrl &&other)

Создаёт экземпляр QUrl, указывая на тот же объект, на который указывал other.

Эта функция была введена в Qt 5.2.

QUrl::QUrl(const QString &url, QUrl::ParsingMode parsingMode = TolerantMode)

Создаёт URL путём парсинга url. QUrl автоматически закодирует процентами все символы, которые не разрешены в URL, и декодирует последовательности процентокодирования, представляющие нерезервированный символ (буквы, цифры, дефисы, нижние подчёркивания, точки и тильды). Все остальные символы остаются в их исходной форме.

Парсит url с помощью режима парсинга parsingMode. В режиме TolerantMode (по умолчанию) QUrl исправит некоторые ошибки, в частности, наличие символа процента ('%') без двух шестнадцатеричных цифр, и примет любой символ в любой позиции. В режиме StrictMode ошибки кодирования не будут допущены, и QUrl также проверит, что некоторые запрещённые символы не присутствуют в незакодированном виде. Если ошибка обнаружена в режиме StrictMode, isValid() вернёт false. Режим парсинга DecodedMode в этом контексте недопустим.

Пример:

QUrl url("http://www.example.com/List of holidays.xml");
// url.toEncoded() == "http://www.example.com/List%20of%20holidays.xml"

Для создания URL из закодированной строки вы также можете использовать fromEncoded():

QUrl url = QUrl::fromEncoded("http://qt-project.org/List%20of%20holidays.xml");

Обе функции эквивалентны и в Qt 5 обе функции принимают закодированные данные. Обычно выбор между конструктором QUrl или setUrl() по сравнению с fromEncoded() зависит от исходных данных: конструктор и setUrl() принимают QString, а fromEncoded() принимает QByteArray.

См. также setUrl(), fromEncoded() и TolerantMode.

QUrl::QUrl(const QUrl &other)

Создаёт копию other.

QUrl::QUrl()

Создаёт пустой объект QUrl.

[since 5.2] QUrl &QUrl::operator=(QUrl &&other)

Перемещает other в этот экземпляр QUrl.

Эта функция была введена в Qt 5.2.

QUrl &QUrl::operator=(const QString &url)

Присваивает указанный url этому объекту.

QUrl &QUrl::operator=(const QUrl &url)

Присваивает указанный url этому объекту.

QUrl::~QUrl()

Деструктор; вызывается непосредственно перед удалением объекта.

[since 5.2] QUrl QUrl::adjusted(QUrl::FormattingOptions options) const

Возвращает скорректированную версию URL. Выход можно настроить, передав флаги с options.

Опции кодирования из QUrl::ComponentFormattingOption не имеют большого смысла для этого метода, также как и QUrl::PreferLocalFile.

Это всегда эквивалентно QUrl(url.toString(options)).

Эта функция была введена в Qt 5.2.

См. также FormattingOptions, toEncoded() и toString().

QString QUrl::authority(QUrl::ComponentFormattingOptions options = PrettyDecoded) const

Возвращает область действия URL, если она определена; в противном случае возвращается пустая строка.

Эта функция возвращает однозначное значение, которое может содержать символы, которые всё ещё закодированы процентами, плюс некоторые управляющие последовательности, которые не могут быть представлены в декодированной форме в QString.

Аргумент options управляет форматированием компонента информации пользователя. Значение QUrl::FullyDecoded недопустимо в этой функции. Если вам нужно получить полностью декодированные данные, вызовите userName(), password(), host() и port() по отдельности.

См. также setAuthority(), userInfo(), userName(), password(), host() и port().

void QUrl::clear()

Сбрасывает содержимое QUrl. После вызова этой функции QUrl эквивалентен тому, который был создан с пустым конструктором по умолчанию.

См. также isEmpty().

QString QUrl::errorString() const

Возвращает сообщение об ошибке, если последняя операция, изменившая этот объект QUrl, столкнулась с ошибкой разбора. Если ошибка не была обнаружена, эта функция возвращает пустую строку, а isValid() возвращает true.

Сообщение об ошибке, возвращаемое этой функцией, технического характера и может быть непонятным для конечных пользователей. Оно в основном полезно разработчикам, пытающимся понять, почему QUrl не принимает некоторый ввод.

См. также QUrl::ParsingMode.

[since 5.2] QString QUrl::fileName(QUrl::ComponentFormattingOptions options = FullyDecoded) const

Возвращает имя файла, исключая путь к каталогу.

Обратите внимание, что если этому объекту QUrl задан путь, заканчивающийся слешем, имя файла считается пустым.

Если путь не содержит слешей, он полностью возвращается как fileName.

Пример:

QUrl url("http://qt-project.org/support/file.html");
// url.adjusted(RemoveFilename) == "http://qt-project.org/support/"
// url.fileName() == "file.html"

Аргумент options управляет форматированием компонента имени файла. Все значения дают однозначный результат. С QUrl::FullyDecoded все закодированные процентами последовательности декодируются; в противном случае возвращаемое значение может содержать некоторые закодированные процентами последовательности для некоторых управляющих последовательностей, которые не могут быть представлены в декодированном виде в QString.

Эта функция была добавлена в Qt 5.2.

См. также path().

QString QUrl::fragment(QUrl::ComponentFormattingOptions options = PrettyDecoded) const

Возвращает фрагмент URL-адреса. Чтобы определить, содержал ли разобранный URL-адрес фрагмент, используйте hasFragment().

Аргумент options управляет форматированием компонента фрагмента. Все значения дают однозначный результат. С QUrl::FullyDecoded все закодированные процентами последовательности декодируются; в противном случае возвращаемое значение может содержать некоторые закодированные процентами последовательности для некоторых управляющих последовательностей, которые не могут быть представлены в декодированном виде в QString.

Обратите внимание, что QUrl::FullyDecoded может привести к потере данных, если присутствуют эти непредставимые последовательности. Рекомендуется использовать это значение, когда результат будет использован в контексте, не являющемся URL.

См. также setFragment() и hasFragment().

[static] QString QUrl::fromAce(const QByteArray &domain)

Возвращает Unicode-форму заданного имени домена domain, закодированного в ASCII Compatible Encoding (ACE). Результат этой функции считается эквивалентным domain.

Если значение в domain не может быть закодировано, оно будет преобразовано в QString и возвращено.

ASCII Compatible Encoding (ACE) определяется RFC 3490, RFC 3491 и RFC 3492. Это часть спецификации Internationalizing Domain Names in Applications (IDNA), которая позволяет именам домена (например, "example.com") записываться с использованием международных символов.

[static, since 5.2] QUrl QUrl::fromCFURL(CFURLRef url)

Создаёт QUrl, содержащую копию CFURL url.

Эта функция была добавлена в Qt 5.2.

[static] QUrl QUrl::fromEncoded(const QByteArray &input, QUrl::ParsingMode parsingMode = TolerantMode)

Разбирает input и возвращает соответствующий QUrl. input предполагается закодированным, содержащим только символы ASCII.

Разбирает URL-адрес, используя parsingMode. См. setUrl() для получения дополнительной информации об этом параметре. QUrl::DecodedMode не разрешён в этом контексте.

См. также toEncoded() и setUrl().

[static] QUrl QUrl::fromLocalFile(const QString &localFile)

Возвращает QUrl представление localFile, интерпретированное как локальный файл. Эта функция принимает пути, разделённые слешами, а также системный разделитель для данной платформы.

Эта функция также принимает пути с удвоенным начальным слешем (или обратным слешем), чтобы указать удалённый файл, как в "//servername/path/to/file.txt". Обратите внимание, что только определённые платформы могут фактически открыть этот файл с помощью QFile::open().

Пустая localFile приводит к пустому URL (с Qt 5.4).

    qDebug() << QUrl::fromLocalFile("file.txt");            // QUrl("file:file.txt")
    qDebug() << QUrl::fromLocalFile("/home/user/file.txt"); // QUrl("file:///home/user/file.txt")
    qDebug() << QUrl::fromLocalFile("file:file.txt");       // doesn't make sense; expects path, not url with scheme

В первой строке в приведённом фрагменте URL-адрес файла создаётся из локального относительного пути. URL-адрес файла с относительным путём имеет смысл только если существует базовый URL-адрес для его разрешения. Например:

    QUrl url = QUrl::fromLocalFile("file.txt");
    QUrl baseUrl = QUrl("file:/home/user/");
    // wrong: prints QUrl("file:file.txt"), as url already has a scheme
    qDebug() << baseUrl.resolved(url);

Для разрешения такого URL-адреса необходимо удалить схему предварительно:

    // correct: prints QUrl("file:///home/user/file.txt")
    url.setScheme(QString());
    qDebug() << baseUrl.resolved(url);

По этой причине лучше использовать относительный URL (то есть без схемы) для относительных путей к файлам:

    QUrl url = QUrl("file.txt");
    QUrl baseUrl = QUrl("file:/home/user/");
    // prints QUrl("file:///home/user/file.txt")
    qDebug() << baseUrl.resolved(url);

См. также toLocalFile(), isLocalFile() и QDir::toNativeSeparators().

[static, since 5.2] QUrl QUrl::fromNSURL(const NSURL *url)

Создаёт QUrl, содержащую копию NSURL url.

Эта функция была добавлена в Qt 5.2.

[static] QString QUrl::fromPercentEncoding(const QByteArray &input)

Возвращает декодированную копию input. input сначала декодируется из процентов кодирования, а затем преобразуется из UTF-8 в юникод.

[static, since 5.1] QList<QUrl> QUrl::fromStringList(const QStringList &urls, QUrl::ParsingMode mode = TolerantMode)

Преобразует список строк, представляющих urls, в список URL-адресов, используя QUrl(str, mode). Обратите внимание, что это означает, что все строки должны быть URL-адресами, а не, например, локальными путями.

Эта функция была добавлена в Qt 5.1.

[static, since 5.4] QUrl QUrl::fromUserInput(const QString &userInput, const QString &workingDirectory = QString(), QUrl::UserInputResolutionOptions options = DefaultResolution)

Возвращает допустимый URL из введённой пользователем строки userInput, если он может быть выведен. В случае невозможности возвращается недопустимый QUrl().

Это позволяет пользователю вводить URL-адрес или локальный путь к файлу в виде обычной строки. Эта строка может быть введена вручную в адресную строку, получена из буфера обмена или передана через аргументы командной строки.

Если строка не является уже допустимым URL-адресом, производится наилучшее предположение, делая различные допущения.

В случае, если строка соответствует допустимому пути к файлу в системе, создаётся URL-адрес файла:// с помощью QUrl::fromLocalFile().

Если это не так, производится попытка преобразовать строку в URL-адрес http:// или ftp://. Последний — в случае, если строка начинается с 'ftp'. Результат затем передаётся в толерантный анализатор QUrl, и в случае успеха возвращается допустимый QUrl, в противном случае — QUrl().

Примеры:

• qt-project.org становится http://qt-project.org
• ftp.qt-project.org становится ftp://ftp.qt-project.org
• hostname становится http://hostname
• /home/user/test.html становится file:///home/user/test.html

Для обработки относительных путей этот метод принимает необязательный путь workingDirectory. Это особенно полезно при обработке аргументов командной строки. Если workingDirectory пустое, обработка относительных путей не выполняется.

По умолчанию строка ввода, похожая на относительный путь, будет рассматриваться как таковая только если файл действительно существует в данном каталоге рабочего пространства. Если приложение может обрабатывать файлы, которые ещё не существуют, оно должно передавать флаг AssumeLocalFile в options.

Эта функция была добавлена в Qt 5.4.

bool QUrl::hasFragment() const

Возвращает true если этот URL содержит фрагмент (т.е., если # был виден на нём).

См. также fragment() и setFragment().

bool QUrl::hasQuery() const

Возвращает true если этот URL содержит запрос (т.е., если ? был виден на нём).

См. также setQuery(), query() и hasFragment().

QString QUrl::host(QUrl::ComponentFormattingOptions options = FullyDecoded) const

Возвращает хост URL-адреса, если он определён; в противном случае возвращается пустая строка.

Аргумент options управляет тем, как будет форматироваться имя хоста. Флаг QUrl::EncodeUnicode заставит эту функцию вернуть имя хоста в формате ASCII-совместимого кодирования (ACE), которое подходит для использования в каналах, не поддерживающих 8-битное чистое кодирование или требующих устаревшее имя хоста (например, запросы DNS или в заголовках запросов HTTP). Если этот флаг отсутствует, функция возвращает имя домена в формате Unicode (IDN) в соответствии со списком разрешенных доменных имен верхнего уровня (см. idnWhitelist()).

Все остальные флаги игнорируются. Имена хостов не могут содержать управляющие символы или символы процента, поэтому возвращаемое значение можно считать полностью декодированным.

См. также setHost(), idnWhitelist(), setIdnWhitelist() и authority().

[static] QStringList QUrl::idnWhitelist()

Возвращает текущий белый список доменных имен верхнего уровня, которым разрешено содержать не-ASCII символы в их составе.

См. setIdnWhitelist() для обоснования этого списка.

См. также setIdnWhitelist().

bool QUrl::isEmpty() const

Возвращает true если URL не содержит данных; в противном случае возвращает false.

См. также clear().

bool QUrl::isLocalFile() const

Возвращает true если этот URL указывает на локальный путь к файлу. URL является локальным путем к файлу, если схема равна "file".

Обратите внимание, что эта функция считает URL с именами хостов локальными путями к файлам, даже если конечный путь к файлу не может быть открыт с помощью QFile::open().

См. также fromLocalFile() и toLocalFile().

bool QUrl::isParentOf(const QUrl &childUrl) const

Возвращает true если этот URL является родительским для childUrl. childUrl является дочерним для этого URL, если два URL имеют одинаковую схему и авторитет, и путь этого URL является родительским для пути childUrl.

bool QUrl::isRelative() const

Возвращает true если URL является относительным; в противном случае возвращает false. URL является относительной ссылкой, если его схема не определена; следовательно, эта функция эквивалентна вызову scheme().isEmpty().

Относительные ссылки определены в RFC 3986 разделе 4.2.

См. также Относительные URL по сравнению с относительными путями.

bool QUrl::isValid() const

Возвращает true если URL не пуст и валиден; в противном случае возвращает false.

URL проходит проверку соответствия. Каждая часть URL должна соответствовать стандартным правилам кодирования стандарта URI, чтобы URL считался валидным.

bool checkUrl(const QUrl &url) {
    if (!url.isValid()) {
        qDebug("Invalid URL: %s", qUtf8Printable(url.toString()));
        return false;
    }

    return true;
}

[since 5.2] bool QUrl::matches(const QUrl &url, QUrl::FormattingOptions options) const

Возвращает true если этот URL и указанный url равны после применения options к обоим; в противном случае возвращает false.

Это эквивалентно вызову adjusted(options) для обоих URL и сравнения полученных URL, но быстрее.

Эта функция была введена в Qt 5.2.

QString QUrl::password(QUrl::ComponentFormattingOptions options = FullyDecoded) const

Возвращает пароль URL, если он определён; в противном случае возвращается пустая строка.

Аргумент options управляет форматированием компонента имени пользователя. Все значения дают однозначный результат. С QUrl::FullyDecoded все проценты кодированные последовательности декодируются; в противном случае возвращаемое значение может содержать некоторые проценты кодированные последовательности для некоторых управляющих последовательностей, которые не могут быть представлены в декодированном виде в QString.

Обратите внимание, что QUrl::FullyDecoded может привести к потере данных, если присутствуют непредставимые последовательности. Рекомендуется использовать это значение, когда результат будет использован в контексте не URL, например, при установке в QAuthenticator или при согласовании входа в систему.

См. также setPassword().

QString QUrl::path(QUrl::ComponentFormattingOptions options = FullyDecoded) const

Возвращает путь URL.

    qDebug() << QUrl("file:file.txt").path();                   // "file.txt"
    qDebug() << QUrl("/home/user/file.txt").path();             // "/home/user/file.txt"
    qDebug() << QUrl("http://www.example.com/test/123").path(); // "/test/123"

Аргумент options управляет форматированием компонента пути. Все значения дают однозначный результат. С QUrl::FullyDecoded все проценты кодированные последовательности декодируются; в противном случае возвращаемое значение может содержать некоторые проценты кодированные последовательности для некоторых управляющих последовательностей, которые не могут быть представлены в декодированном виде в QString.

Обратите внимание, что QUrl::FullyDecoded может привести к потере данных, если присутствуют непредставимые последовательности. Рекомендуется использовать это значение, когда результат будет использован в контексте, отличном от URL, например, при отправке на FTP-сервер.

Пример потери данных, когда у вас есть последовательности, которые не поддерживаются Unicode, и вы используете FullyDecoded (по умолчанию):

    qDebug() << QUrl("/foo%FFbar").path();

В этом примере произойдёт потеря данных, потому что %FF не может быть преобразован.

Потеря данных также может произойти, когда путь содержит подразделители (например, +):

    qDebug() << QUrl("/foo+bar%2B").path(); // "/foo+bar+"

Другие примеры декодирования:

    const QUrl url("/tmp/Mambo %235%3F.mp3");
    qDebug() << url.path(QUrl::FullyDecoded);  // "/tmp/Mambo #5?.mp3"
    qDebug() << url.path(QUrl::PrettyDecoded); // "/tmp/Mambo #5?.mp3"
    qDebug() << url.path(QUrl::FullyEncoded);  // "/tmp/Mambo%20%235%3F.mp3"

См. также setPath().

int QUrl::port(int defaultPort = -1) const

Возвращает порт URL или defaultPort, если порт не указан.

Пример:

QTcpSocket sock;
sock.connectToHost(url.host(), url.port(80));

См. также setPort().

QString QUrl::query(QUrl::ComponentFormattingOptions options = PrettyDecoded) const

Возвращает строку запроса URL, если она есть, или пустое значение, если нет. Чтобы определить, содержал ли проанализированный URL строку запроса, используйте hasQuery().

Аргумент options управляет форматированием компонента запроса. Все значения дают однозначный результат. С QUrl::FullyDecoded все проценты кодированные последовательности декодируются; в противном случае возвращаемое значение может содержать некоторые проценты кодированные последовательности для некоторых управляющих последовательностей, которые не могут быть представлены в декодированном виде в QString.

Обратите внимание, что использование QUrl::FullyDecoded в запросах не рекомендуется, так как запросы часто содержат данные, которые должны оставаться процентами кодированными, включая использование последовательности "%2B" для представления знака плюс ('+').

См. также setQuery() и hasQuery().

QUrl QUrl::resolved(const QUrl &relative) const

Возвращает результат объединения этого URL с relative. Этот URL используется в качестве базы для преобразования relative в абсолютный URL.

Если relative не является относительным URL, эта функция вернет relative напрямую. В противном случае пути двух URL объединяются, и новый возвращённый URL имеет схему и авторитет базового URL, но с объединённым путем, как в следующем примере:

QUrl baseUrl("http://qt.digia.com/Support/");
QUrl relativeUrl("../Product/Library/");
qDebug(baseUrl.resolved(relativeUrl).toString());
// prints "http://qt.digia.com/Product/Library/"

Вызов resolved() с ".." возвращает QUrl, директория которого находится на уровень выше исходной. Аналогично, вызов resolved() с "../.." удаляет два уровня из пути. Если relative равно "/", путь становится "/".

См. также isRelative().

QString QUrl::scheme() const

Возвращает схему URL. Если возвращается пустая строка, это означает, что схема не определена, и URL является относительным.

Схема может содержать только символы ASCII или цифры, а это означает, что она не может содержать символы, требующие кодирования. Кроме того, схемы всегда возвращаются в нижнем регистре.

См. также setScheme() и isRelative().

void QUrl::setAuthority(const QString &authority, QUrl::ParsingMode mode = TolerantMode)

Устанавливает авторитет URL на authority.

Авторитет URL — это сочетание информации пользователя, имени хоста и порта. Все эти элементы являются необязательными; поэтому допустим и пустой авторитет.

Информация пользователя и хост разделены символом '@', а хост и порт — двоеточием ':'. Если информация пользователя пустая, символ '@' должен быть опущен; хотя случайный двоеточие ':' разрешён, если порт пустой.

Следующий пример показывает допустимую строку авторитета:

Данные authority интерпретируются в соответствии с mode: в StrictMode все символы '%' должны следовать за ровно двумя шестнадцатеричными символами, и некоторые символы (включая пробел) не допускаются в виде не декодированных данных. В TolerantMode (по умолчанию) все символы принимаются в не декодированном виде, и допускающий анализатор исправит случайные символы '%', за которыми не следуют две шестнадцатеричные цифры.

Эта функция не позволяет mode быть QUrl::DecodedMode. Для установки полностью декодированных данных вызовите setUserName(), setPassword(), setHost() и setPort() по отдельности.

См. также authority(), setUserInfo(), setHost() и setPort().

void QUrl::setFragment(const QString &fragment, QUrl::ParsingMode mode = TolerantMode)

Устанавливает фрагмент URL в fragment. Фрагмент — последняя часть URL, представленная символом '#' и последующей строкой символов. Обычно используется в HTTP для ссылки на определённую ссылку или точку на странице:

Фрагмент также иногда называется «ссылкой» URL.

Передача аргумента QString() (пустого QString) удаляет фрагмент. Передача аргумента QString("") (пустого, но не пустого QString) устанавливает фрагмент в пустую строку (как если бы исходный URL содержал только "#").

Данные fragment интерпретируются в соответствии с mode: в StrictMode все символы '%' должны следовать за ровно двумя шестнадцатеричными символами, а некоторые символы (включая пробел) не допускаются в нерасшифрованном виде. В TolerantMode все символы принимаются в нерасшифрованном виде, и толерантный анализатор исправит одиночные символы '%', за которыми не следуют два шестнадцатеричных символа. В DecodedMode '%' символы остаются в том виде, и декодирование символов невозможно.

QUrl::DecodedMode следует использовать при установке фрагмента из источника данных, который не является URL, или с фрагментом, полученным вызовом fragment() с опцией форматирования QUrl::FullyDecoded.

См. также fragment() и hasFragment().

void QUrl::setHost(const QString &host, QUrl::ParsingMode mode = DecodedMode)

Устанавливает хост URL в host. Хост является частью авторитета.

Данные host интерпретируются в соответствии с mode: в StrictMode все символы '%' должны следовать за ровно двумя шестнадцатеричными символами, а некоторые символы (включая пробел) не допускаются в нерасшифрованном виде. В TolerantMode все символы принимаются в нерасшифрованном виде, и толерантный анализатор исправит одиночные символы '%' за которыми не следуют два шестнадцатеричных символа. В DecodedMode '%' символы остаются в том виде, и декодирование символов невозможно.

Обратите внимание, что во всех случаях результат разбора должен быть допустимым именем хоста в соответствии со STD 3 правилами, как модифицировано спецификацией Internationalized Resource Identifiers (RFC 3987). Недопустимые имена хостов не допускаются и приведут к тому, что isValid() станет ложным.

См. также host() и setAuthority().

[static] void QUrl::setIdnWhitelist(const QStringList &list)

Устанавливает белый список доменных имён верхнего уровня (TLD), которые могут иметь не-ASCII символы в доменах, в значение list.

Обратите внимание, что если вы вызываете эту функцию, вам нужно сделать это до начала работы потоков, которые могут получить доступ к idnWhitelist().

Qt поставляется с предустановленным списком, который содержит доменные имена верхнего уровня в интернете, которые опубликовали поддержку международных доменных имён (IDN) и правила, гарантирующие, что мошенничество не может произойти между похожими символами (такими как латинская строчная буква 'a' и её кириллический эквивалент, которые в большинстве шрифтов визуально идентичны).

Этот список периодически обновляется, поскольку регистраторы публикуют новые правила.

Эта функция предоставляется для тех, кому нужно изменять список, чтобы добавлять или удалять TLD. Не рекомендуется изменять его значение для целей, отличных от тестирования, так как это может подвергнуть пользователей риску безопасности.

См. также idnWhitelist().

void QUrl::setPassword(const QString &password, QUrl::ParsingMode mode = DecodedMode)

Устанавливает пароль URL в password. password является частью элемента user info в авторитете URL, как описано в setUserInfo().

Данные password интерпретируются в соответствии с mode: в StrictMode все символы '%' должны следовать за ровно двумя шестнадцатеричными символами, а некоторые символы (включая пробел) не допускаются в нерасшифрованном виде. В TolerantMode все символы принимаются в нерасшифрованном виде, и толерантный анализатор исправит одиночные символы '%' за которыми не следуют два шестнадцатеричных символа. В DecodedMode '%' символы остаются в том виде, и декодирование символов невозможно.

QUrl::DecodedMode следует использовать при установке пароля из источника данных, который не является URL, например, из диалогового окна ввода пароля для пользователя или с паролем, полученным вызовом password() с опцией форматирования QUrl::FullyDecoded.

См. также password() и setUserInfo().

void QUrl::setPath(const QString &path, QUrl::ParsingMode mode = DecodedMode)

Устанавливает путь URL в path. Путь — часть URL, которая следует за авторитетом, но предшествует строке запроса.

Для схем без иерархии путь будет включать всё, что следует за объявлением схемы, как в следующем примере:

Данные path интерпретируются в соответствии с mode: в StrictMode все символы '%' должны следовать за ровно двумя шестнадцатеричными символами, а некоторые символы (включая пробел) не допускаются в нерасшифрованном виде. В TolerantMode все символы принимаются в нерасшифрованном виде, и толерантный анализатор исправит одиночные символы '%' за которыми не следуют два шестнадцатеричных символа. В DecodedMode '%' символы остаются в том виде, и декодирование символов невозможно.

QUrl::DecodedMode следует использовать при установке пути из источника данных, который не является URL, например, из диалогового окна для пользователя или с путём, полученным вызовом path() с опцией форматирования QUrl::FullyDecoded.

См. также path().

void QUrl::setPort(int port)

Устанавливает порт URL в port. Порт является частью авторитета URL, как описано в setAuthority().

port должен быть между 0 и 65535 включительно. Установка порта в -1 означает, что порт не указан.

См. также port().

void QUrl::setQuery(const QString &query, QUrl::ParsingMode mode = TolerantMode)

Устанавливает строку запроса URL в query.

Эта функция полезна, если вам нужно передать строку запроса, которая не соответствует шаблону ключ-значение или использует другой способ кодирования специальных символов, чем предложенный QUrl.

Передача значения QString() в query (пустой QString) полностью удаляет запрос. Однако передача QString("") установит запрос в пустое значение, как если бы исходный URL содержал только "?".

Строки запроса часто содержат проценты-кодированные последовательности, поэтому использование DecodedMode не рекомендуется. Одна специальная последовательность, о которой следует помнить, это символ плюс ('+'). QUrl не преобразует пробелы в символы плюс, хотя HTML-формы, отправляемые веб-браузерами, это делают. Для представления фактического символа плюс в запросе обычно используется последовательность "%2B". Эта функция оставит последовательности "%2B" без изменений в TolerantMode или StrictMode.

См. также query() и hasQuery().

[since 5.0] void QUrl::setQuery(const QUrlQuery &query)

Это перегруженная функция.

Устанавливает строку запроса URL в query.

Эта функция восстанавливает строку запроса из объекта QUrlQuery и устанавливает её в этот объект QUrl. Эта функция не имеет параметров разбора, так как QUrlQuery содержит данные, которые уже обработаны.

Эта функция была добавлена в Qt 5.0.

См. также query() и hasQuery().

void QUrl::setScheme(const QString &scheme)

Устанавливает схему URL в scheme. Поскольку схема может содержать только символы ASCII, преобразование или декодирование входных данных не производится. Она также должна начинаться с ASCII буквы.

Схема описывает тип (или протокол) URL. Она представлена одной или несколькими ASCII-символами в начале URL.

Схема строго соответствует спецификации RFC 3986: scheme = ALPHA *( ALPHA / DIGIT / "+" / "-" / "." )

В следующем примере показан URL, где схема — "ftp":

Для установки схемы используется следующий вызов:

    QUrl url;
    url.setScheme("ftp");

Схема также может быть пустой, в этом случае URL интерпретируется как относительный.

См. также scheme() и isRelative().

void QUrl::setUrl(const QString &url, QUrl::ParsingMode parsingMode = TolerantMode)

Парсит url и устанавливает этому объекту это значение. QUrl автоматически кодирует посимвольно все символы, которые не разрешены в URL, и декодирует закодированные последовательности, представляющие незарезервированный символ (буквы, цифры, дефисы, подчёркивания, точки и тильды). Все остальные символы остаются в их исходной форме.

Парсит url с использованием режима парсера parsingMode. В режиме TolerantMode (по умолчанию) QUrl исправляет определённые ошибки, в частности наличие символа процента ('%') без двух последующих шестнадцатеричных цифр, и принимает любой символ в любом положении. В режиме StrictMode ошибки кодирования не допускаются, и QUrl также проверяет, что определённые запрещённые символы отсутствуют в некодированной форме. Если в режиме StrictMode обнаружена ошибка, isValid() вернёт false. Режим парсинга DecodedMode в этом контексте недопустим и вызовет предупреждение во время выполнения.

См. также url() и toString().

void QUrl::setUserInfo(const QString &userInfo, QUrl::ParsingMode mode = TolerantMode)

Устанавливает пользовательские данные URL на userInfo. Пользовательские данные — это необязательная часть авторизации URL, как описано в setAuthority().

Пользовательские данные состоят из имени пользователя и, необязательно, пароля, разделённых двоеточием. Если пароль пустой, двоеточие следует опустить. Следующий пример показывает допустимую строку пользовательских данных:

Данные userInfo интерпретируются в соответствии с mode: в режиме StrictMode все символы '%' должны следовать точно двум шестнадцатеричным символам, и некоторые символы (включая пробелы) не допускаются в некодированной форме. В режиме TolerantMode (по умолчанию) все символы принимаются в некодированной форме, а толерантный парсер исправит случайные '%' без двух шестнадцатеричных символов.

Эта функция не допускает mode в режиме QUrl::DecodedMode. Для установки полностью декодированных данных вызовите setUserName() и setPassword() по отдельности.

См. также userInfo(), setUserName(), setPassword(), и setAuthority().

void QUrl::setUserName(const QString &userName, QUrl::ParsingMode mode = DecodedMode)

Устанавливает имя пользователя URL на userName. Имя пользователя является частью элемента пользовательских данных в авторизации URL, как описано в setUserInfo().

Данные userName интерпретируются в соответствии с mode: в режиме StrictMode все символы '%' должны следовать точно двум шестнадцатеричным символам, и некоторые символы (включая пробелы) не допускаются в некодированной форме. В режиме TolerantMode (по умолчанию) все символы принимаются в некодированной форме, и толерантный парсер исправит случайные '%' без двух шестнадцатеричных символов. В режиме DecodedMode '%' воспринимаются как сами по себе, и кодированные символы невозможны.

QUrl::DecodedMode следует использовать при установке имени пользователя из источника данных, который не является URL, например, из диалогового окна пароля, показанного пользователю, или с именем пользователя, полученным путем вызова userName() с параметром форматирования QUrl::FullyDecoded.

См. также userName() и setUserInfo().

void QUrl::swap(QUrl &other)

Меняет местами URL other с этим URL. Эта операция очень быстрая и никогда не терпит неудачу.

[static] QByteArray QUrl::toAce(const QString &domain)

Возвращает ASCII-совместимое кодирование данного доменного имени domain. Результат этой функции считается эквивалентным domain.

ASCII-совместимое кодирование (ACE) определяется RFC 3490, RFC 3491 и RFC 3492. Оно является частью спецификации Internationalizing Domain Names in Applications (IDNA), которая позволяет доменным именам (например, "example.com") быть записанными с использованием международных символов.

Эта функция возвращает пустой QByteArray, если domain не является допустимым именем хоста. Обратите внимание, что IPv6-литералы не являются допустимыми доменными именами.

[since 5.2] CFURLRef QUrl::toCFURL() const

Создаёт CFURL из QUrl.

Вызывающий владеет CFURL и отвечает за его освобождение.

Эта функция была добавлена в Qt 5.2.

[since 5.0] QString QUrl::toDisplayString(QUrl::FormattingOptions options = FormattingOptions(PrettyDecoded)) const

Возвращает строку, отображаемую человеком, представляющую URL. Выходные данные можно настроить, передавая флаги в options. Флаг RemovePassword всегда включён, так как пароли никогда не должны отображаться пользователям.

С параметрами по умолчанию полученная QString может быть позже передана в QUrl, но любой первоначально присутствовавший пароль будет потерян.

Эта функция была добавлена в Qt 5.0.

См. также FormattingOptions, toEncoded() и toString().

QByteArray QUrl::toEncoded(QUrl::FormattingOptions options = FullyEncoded) const

Возвращает закодированное представление URL, если оно допустимо; в противном случае возвращается пустой QByteArray. Выходные данные можно настроить, передавая флаги в options.

Пользовательские данные, путь и фрагмент конвертируются в UTF-8, а все символы, не являющиеся ASCII, затем кодируются посимвольно. Имя хоста кодируется с помощью Punycode.

QString QUrl::toLocalFile() const

Возвращает путь этого URL, отформатированный как путь к локальному файлу. Возвращённый путь будет использовать слэши, даже если он был первоначально создан с обратными слэшами.

Если этот URL содержит непустое имя хоста, он будет закодирован в возвращаемом значении в формате, найденном в SMB-сетях (например, "//servername/path/to/file.txt").

    qDebug() << QUrl("file:file.txt").toLocalFile();            // "file.txt"
    qDebug() << QUrl("file:/home/user/file.txt").toLocalFile(); // "/home/user/file.txt"
    qDebug() << QUrl("file.txt").toLocalFile();                 // ""; wasn't a local file as it had no scheme

Примечание: если компонент пути этого URL содержит не-UTF-8 двоичную последовательность (например, %80), поведение этой функции не определено.

См. также fromLocalFile() и isLocalFile().

[since 5.2] NSURL *QUrl::toNSURL() const

Создаёт NSURL из QUrl.

NSURL автоосвобождается.

Эта функция была добавлена в Qt 5.2.

[static] QByteArray QUrl::toPercentEncoding(const QString &input, const QByteArray &exclude = QByteArray(), const QByteArray &include = QByteArray())

Возвращает закодированную копию input. input сначала преобразуется в UTF-8, а все ASCII-символы, которые не входят в незарезервированную группу, кодируются посимвольно. Для предотвращения кодирования символов передайте их в exclude. Для принудительного кодирования символов передайте их в include.

Незарезервированными являются: ALPHA / DIGIT / "-" / "." / "_" / "~"

QByteArray ba = QUrl::toPercentEncoding("{a fishy string?}", "{}", "s");
qDebug(ba.constData());
// prints "{a fi%73hy %73tring%3F}"

QString QUrl::toString(QUrl::FormattingOptions options = FormattingOptions(PrettyDecoded)) const

Возвращает строковое представление URL. Выходные данные можно настроить, передавая флаги в options. Параметр QUrl::FullyDecoded недопустим в этой функции, так как он генерирует неоднозначные данные.

Параметр форматирования по умолчанию — PrettyDecoded.

См. также FormattingOptions, url() и setUrl().

[static, since 5.1] QStringList QUrl::toStringList(const QList<QUrl> &urls, QUrl::FormattingOptions options = FormattingOptions(PrettyDecoded))

Преобразует список urls в список объектов QString, используя toString(options).

Эта функция была добавлена в Qt 5.1.

QString QUrl::url(QUrl::FormattingOptions options = FormattingOptions(PrettyDecoded)) const

Возвращает строковое представление URL. Вывод можно настроить, передав флаги с помощью options. Опция QUrl::FullyDecoded недопустима в этой функции, так как она приведет к неоднозначным данным.

Полученный QString можно позднее передать в QUrl.

Синоним для toString(options).

См. также setUrl(), FormattingOptions, toEncoded(), и toString().

QString QUrl::userInfo(QUrl::ComponentFormattingOptions options = PrettyDecoded) const

Возвращает информацию о пользователе URL или пустую строку, если информация о пользователе не определена.

Эта функция возвращает однозначное значение, которое может содержать символы, ещё закодированные в процентах, а также некоторые управляющие последовательности, не представимые в декодированной форме в QString.

Аргумент options управляет тем, как форматировать компонент информации о пользователе. Значение QUrl::FullyDecoded недопустимо в этой функции. Если вам нужно получить полностью декодированные данные, вызовите userName() и password() индивидуально.

См. также setUserInfo(), userName(), password() и authority().

QString QUrl::userName(QUrl::ComponentFormattingOptions options = FullyDecoded) const

Возвращает имя пользователя URL, если оно определено; в противном случае возвращается пустая строка.

Аргумент options управляет тем, как форматировать компонент имени пользователя. Все значения дают однозначный результат. С QUrl::FullyDecoded все проценты-закодированные последовательности декодируются; в противном случае возвращаемое значение может содержать некоторые проценты-закодированные последовательности для некоторых управляющих последовательностей, не представимых в декодированной форме в QString.

Обратите внимание, что QUrl::FullyDecoded может привести к потере данных, если присутствуют непредставимые последовательности. Рекомендуется использовать это значение, когда результат будет использоваться в контексте, не являющемся URL, например, при установке в QAuthenticator или при согласовании входа в систему.

См. также setUserName() и userInfo().

bool QUrl::operator!=(const QUrl &url) const

Возвращает true если этот URL и заданный url не равны; в противном случае возвращает false.

См. также matches().

bool QUrl::operator==(const QUrl &url) const

Возвращает true если этот URL и заданный url равны; в противном случае возвращает false.

См. также matches().

url = filename; // probably not what you want

url = QUrl::fromLocalFile(filename);
url = baseurl.resolved(QUrl(filename));