Класс QUrl

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

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

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

Открытые типы

Открытые функции

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

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

Макросы

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

Класс 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.

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

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

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

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

Проверка ошибок

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().

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

enum QUrl::ComponentFormattingOptionflags 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.

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

enum QUrl::UrlFormattingOptionflags QUrl::FormattingOptions

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

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

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

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

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

перечисление QUrl::UserInputResolutionOptionфлаги QUrl::UserInputResolutionOptions

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

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

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

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

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

QUrl::QUrl()

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

QUrl::QUrl(const QUrl &other)

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

QUrl::QUrl(const QString &url, 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(QUrl &&other)

Перемещающая конструкция объекта QUrl, указывая его на тот же объект, на который указывал other.

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

QUrl::~QUrl()

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

QUrl QUrl::adjusted(FormattingOptions options) const

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

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

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

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

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

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

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

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

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

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

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

QString QUrl::fileName(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(ComponentFormattingOptions options = PrettyDecoded) const

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

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

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

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

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

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

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

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

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

[static] QUrl QUrl::fromCFURL(CFURLRef url)

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

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

[static] QUrl QUrl::fromEncoded(const QByteArray &input, 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).

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

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

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

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

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

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

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

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

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

[static] QUrl QUrl::fromUserInput(const QString &userInput)

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

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

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

В случае, если строка соответствует допустимому пути к файлу в системе, создаётся URL file://, используя 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

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

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

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

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

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

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

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

bool QUrl::hasFragment() const

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

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

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

bool QUrl::hasQuery() const

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

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

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

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

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

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

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

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

[static] QStringList QUrl::idnWhitelist()

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

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

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

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

bool QUrl::isEmpty() const

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

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

bool QUrl::isLocalFile() const

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

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

Данная функция была добавлена в Qt 4.8.

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

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

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

bool QUrl::isRelative() const

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

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

bool QUrl::isValid() const

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

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

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

    return true;
}

bool QUrl::matches(const QUrl &url, FormattingOptions options) const

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Пример:

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

Данная функция была добавлена в Qt 4.1.

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

QString QUrl::query(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 является относительным.

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

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

void QUrl::setAuthority(const QString &authority, 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, 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, ParsingMode mode = DecodedMode)

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

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

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

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

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

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

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

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

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

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

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

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

void QUrl::setPassword(const QString &password, 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, 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, ParsingMode mode = TolerantMode)

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

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

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

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

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

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, ParsingMode parsingMode = TolerantMode)

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

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

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

void QUrl::setUserInfo(const QString &userInfo, 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, ParsingMode mode = DecodedMode)

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

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

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

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

void QUrl::swap(QUrl &other)

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

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

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

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

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

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

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

CFURLRef QUrl::toCFURL() const

Создаёт CFURL из QUrl. Вызывающий код владеет CFURL и несет ответственность за его освобождение.

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

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

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

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

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

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

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

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

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

QString QUrl::toLocalFile() const

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

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

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

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

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(FormattingOptions options = FormattingOptions( PrettyDecoded )) const

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

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

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

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

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

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

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

Возвращает домен верхнего уровня (TLD) URL (например, .co.uk, .net). Обратите внимание, что результат имеет префикс '.' за исключением случая, когда в URL нет допустимого TLD, в этом случае функция возвращает пустую строку.

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

• foo.co.uk и foo.com не имеют общий домен верхнего уровня
• foo.co.uk и bar.co.uk имеют общий домен .co.uk, но следующая метка отличается
• www.foo.co.uk и ftp.foo.co.uk имеют общий домен верхнего уровня и ещё одну метку, поэтому они считаются частью одного сайта

Если options включает EncodeUnicode, возвращаемая строка будет в ASCII-совместимой кодировке.

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

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

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

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

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

См. также setUrl(), ПараметрыФорматирования, toEncoded() и toString().

QString QUrl::userInfo(ПараметрыФорматированияКомпонентов options = PrettyDecoded) const

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

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

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

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

QString QUrl::userName(ПараметрыФорматированияКомпонентов options = FullyDecoded) const

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

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

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

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

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

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

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

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

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

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

QUrl &QUrl::operator=(QUrl &&other)

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

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

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

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

url = filename; // probably not what you want

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