Класс 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 (Uniform Resource Identifier: Generic Syntax), и включает расширения схемы из RFC 1738 (Uniform Resource Locators). Правила преобразования регистра в QUrl соответствуют RFC 3491 (Nameprep: A Stringprep Profile for Internationalized Domain Names (IDN)). Он также совместим со спецификацией файла URI с freedesktop.org, при условии, что имена файлов кодируются в локале с использованием UTF-8 (требуется для IDN).

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

Вызов isRelative() вернёт значение true или false в зависимости от того, является ли 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 — это псевдоним для QFlags<ComponentFormattingOption>. Он хранит логическое ИЛИ комбинацию значений ComponentFormattingOption.

См. также 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 является typedef для QFlags<UrlFormattingOption>. Он хранит результат операции OR над значениями UrlFormattingOption.

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

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

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

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

Тип UserInputResolutionOptions является typedef для QFlags<UserInputResolutionOption>. Он хранит результат операции OR над значениями 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 в юникод.

Примечание: При неверном вводе (например, строка, содержащая последовательность "%G5", которая не является допустимым шестнадцатеричным числом), выход будет неверным. Например, последовательность "%G5" может быть декодирована до 'W'.

[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-адрес file://, используя QUrl::fromLocalFile().

Если это не так, делается попытка преобразовать строку в http:// или ftp:// URL. Последнее в случае, если строка начинается с '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. Пароль является частью элемента 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. userName является частью элемента user info в авторизации 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. Она является частью спецификации IDNA (Internationalizing Domain Names in Applications), которая позволяет доменным именам (например, "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-символы, которые не находятся в группе unreserved, кодируются с процентами. Чтобы предотвратить кодирование символов с процентами, передайте их в exclude. Чтобы принудительно закодировать символы с процентами, передайте их в include.

Unreserved определяются как: 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

Возвращает часть user info URL, или пустую строку, если user info не определена.

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

Аргумент options управляет тем, как форматировать компонент user info. Значение 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.

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

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

url = filename; // probably not what you want

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