이 페이지에서

QUrl Class

QUrl 클래스는 URL을 다루는 데 편리한 인터페이스를 제공합니다. 더 보기...

헤더: #include <QUrl>
CMake: find_package(Qt6 REQUIRED COMPONENTS Core)
target_link_libraries(mytarget PRIVATE Qt6::Core)
qmake: QT += core

참고: 이 클래스의 모든 함수는 재진입 가능합니다.

QUrl 비교

범주비교 가능한 유형
약한QUrl

공개 유형

(since 6.3) enum AceProcessingOption { IgnoreIDNWhitelist, AceTransitionalProcessing }
flags AceProcessingOptions
enum ComponentFormattingOption { PrettyDecoded, EncodeSpaces, EncodeUnicode, EncodeDelimiters, EncodeReserved, …, FullyDecoded }
flags ComponentFormattingOptions
flags FormattingOptions
enum ParsingMode { TolerantMode, StrictMode, DecodedMode }
enum UrlFormattingOption { None, RemoveScheme, RemovePassword, RemoveUserInfo, RemovePort, …, NormalizePathSegments }
enum UserInputResolutionOption { DefaultResolution, AssumeLocalFile }
flags UserInputResolutionOptions

공개 함수

QUrl()
QUrl(const QString &url, QUrl::ParsingMode parsingMode = TolerantMode)
QUrl(const QUrl &other)
QUrl(QUrl &&other)
~QUrl()
QUrl adjusted(QUrl::FormattingOptions options) const
QString authority(QUrl::ComponentFormattingOptions options = PrettyDecoded) const
void clear()
QString errorString() const
QString fileName(QUrl::ComponentFormattingOptions options = FullyDecoded) const
QString fragment(QUrl::ComponentFormattingOptions options = PrettyDecoded) const
bool hasFragment() const
bool hasQuery() const
QString host(QUrl::ComponentFormattingOptions options = FullyDecoded) const
bool isEmpty() const
bool isLocalFile() const
bool isParentOf(const QUrl &childUrl) const
bool isRelative() const
bool isValid() const
bool matches(const QUrl &url, QUrl::FormattingOptions options) const
QString password(QUrl::ComponentFormattingOptions options = FullyDecoded) const
QString path(QUrl::ComponentFormattingOptions options = FullyDecoded) const
int port(int defaultPort = -1) const
QString query(QUrl::ComponentFormattingOptions options = PrettyDecoded) const
QUrl resolved(const QUrl &relative) const
QString scheme() const
void setAuthority(const QString &authority, QUrl::ParsingMode mode = TolerantMode)
void setFragment(const QString &fragment, QUrl::ParsingMode mode = TolerantMode)
void setHost(const QString &host, QUrl::ParsingMode mode = DecodedMode)
void setPassword(const QString &password, QUrl::ParsingMode mode = DecodedMode)
void setPath(const QString &path, QUrl::ParsingMode mode = DecodedMode)
void setPort(int port)
void setQuery(const QString &query, QUrl::ParsingMode mode = TolerantMode)
void setQuery(const QUrlQuery &query)
void setScheme(const QString &scheme)
void setUrl(const QString &url, QUrl::ParsingMode parsingMode = TolerantMode)
void setUserInfo(const QString &userInfo, QUrl::ParsingMode mode = TolerantMode)
void setUserName(const QString &userName, QUrl::ParsingMode mode = DecodedMode)
void swap(QUrl &other)
CFURLRef toCFURL() const
QString toDisplayString(QUrl::FormattingOptions options = FormattingOptions(PrettyDecoded)) const
QByteArray toEncoded(QUrl::FormattingOptions options = FullyEncoded) const
QString toLocalFile() const
NSURL *toNSURL() const
QString toString(QUrl::FormattingOptions options = FormattingOptions(PrettyDecoded)) const
QString url(QUrl::FormattingOptions options = FormattingOptions(PrettyDecoded)) const
QString userInfo(QUrl::ComponentFormattingOptions options = PrettyDecoded) const
QString userName(QUrl::ComponentFormattingOptions options = FullyDecoded) const
QUrl &operator=(QUrl &&other)
QUrl &operator=(const QString &url)
QUrl &operator=(const QUrl &url)

정적 공용 멤버

(since 6.3) QString fromAce(const QByteArray &domain, QUrl::AceProcessingOptions options = {})
QUrl fromCFURL(CFURLRef url)
QUrl fromEncoded(QByteArrayView input, QUrl::ParsingMode mode = TolerantMode)
QUrl fromLocalFile(const QString &localFile)
QUrl fromNSURL(const NSURL *url)
QString fromPercentEncoding(const QByteArray &input)
QList<QUrl> fromStringList(const QStringList &urls, QUrl::ParsingMode mode = TolerantMode)
QUrl fromUserInput(const QString &userInput, const QString &workingDirectory = QString(), QUrl::UserInputResolutionOptions options = DefaultResolution)
QStringList idnWhitelist()
void setIdnWhitelist(const QStringList &list)
(since 6.3) QByteArray toAce(const QString &domain, QUrl::AceProcessingOptions options = {})
QByteArray toPercentEncoding(const QString &input, const QByteArray &exclude = QByteArray(), const QByteArray &include = QByteArray())
QStringList toStringList(const QList<QUrl> &urls, QUrl::FormattingOptions options = FormattingOptions(PrettyDecoded))
bool operator!=(const QUrl &lhs, const QUrl &rhs)
QDataStream &operator<<(QDataStream &out, const QUrl &url)
bool operator==(const QUrl &lhs, const QUrl &rhs)
QDataStream &operator>>(QDataStream &in, QUrl &url)

매크로

상세 설명

인코딩된 형태와 인코딩되지 않은 형태 모두에서 URL을 파싱하고 생성할 수 있습니다. 또한 QUrl은 국제화 도메인 이름(IDN)을 지원합니다.

QUrl을 사용하는 가장 일반적인 방법은 전체 URL이 포함된 ` QString `을 전달하여 생성자(constructor)를 통해 초기화하는 것입니다. 또한 ` QUrl::fromEncoded()`을 사용하여 전체 URL이 포함된 ` QByteArray `에서 QUrl 객체를 생성하거나, ` QUrl::fromUserInput()`을 사용하여 불완전한 URL로부터 휴리스틱 방식으로 객체를 생성할 수도 있습니다. URL 표현식은 ` QUrl::toString()` 또는 ` QUrl::toEncoded()`을 사용하여 QUrl에서 얻을 수 있습니다.

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을 수정하거나, setUrl()를 사용하여 새로운 URL을 파싱하여 다시 시작해야 합니다.

QUrlQuery 클래스와 그 메서드인 QUrlQuery::setQueryItems(), QUrlQuery::addQueryItem(), QUrlQuery::removeQueryItem()을 사용하면 쿼리 문자열을 구성하는 데 특히 편리합니다. QUrlQuery::setQueryDelimiters()을 사용하여 쿼리 문자열 생성에 사용되는 구분 기호를 사용자 정의할 수 있습니다.

인코딩된 URL 문자열이나 쿼리 문자열을 편리하게 생성할 수 있도록, QString 객체의 퍼센트 인코딩 및 디코딩을 처리하는 fromPercentEncoding() 및 toPercentEncoding()라는 두 가지 정적 함수가 제공됩니다.

fromLocalFile()는 로컬 파일 경로를 파싱하여 QUrl을 생성합니다. toLocalFile()는 URL을 로컬 파일 경로로 변환합니다.

toString()를 사용하면 사람이 읽을 수 있는 형식의 URL을 가져올 수 있습니다. 이 형식은 인코딩되지 않은 형태로 사용자에게 URL을 표시하는 데 적합합니다. 반면, toEncoded()이 반환하는 인코딩된 형식은 내부 사용, 웹 서버나 메일 클라이언트 등으로 전달하는 용도입니다. 두 형식 모두 기술적으로 정확하며 동일한 URL을 모호함 없이 나타냅니다. 실제로, QUrl의 생성자나 setUrl()에 두 형식 중 어느 것을 전달하더라도 동일한 QUrl 객체가 생성됩니다.

QUrl은 RFC 3986 (Uniform Resource Identifier: Generic Syntax)의 URI 사양을 준수하며, RFC 1738 (Uniform Resource Locators)의 스키마 확장을 포함합니다. QUrl의 대소문자 변환 규칙은 RFC 3491 (Nameprep: 국제화 도메인 이름(IDN)을 위한 Stringprep 프로파일)을 따릅니다. 또한 로케일이 UTF-8을 사용하여 파일 이름을 인코딩하는 경우(IDN에서 요구됨), freedesktop.org의 파일 URI 사양과도 호환됩니다.

상대 URL 대 상대 경로

isRelative()를 호출하면 해당 URL이 상대 URL인지 여부를 반환합니다. 상대 URL에는 scheme 가 포함되지 않습니다. 예:

qDebug() << QUrl("main.qml").isRelative();          // true: 스키마 없음
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은 상대 경로를 포함하면서도 절대 URL이 될 수 있으며, 그 반대의 경우도 가능하다는 점에 유의하십시오:

// 절대 URL, 상대 경로
QUrl url("file:file.txt");
qDebug() << url.isRelative();                 // false: has "file" scheme
qDebug() << QDir::isAbsolutePath(url.path()); // false: relative path

// 상대 URL, 절대 경로
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이 다른 URL의 상위 URL인지 여부를 판단하는 데 사용됩니다.

오류 검사

QUrl은 URL을 파싱하는 동안이나 개별 세터 메서드( setScheme(), setHost(), setPath() 등)를 통해 URL의 구성 요소가 설정될 때 많은 오류를 감지할 수 있습니다. 파싱이나 세터 함수가 성공하면 이전에 기록된 오류 조건은 모두 무시됩니다.

기본적으로 QUrl의 세터 메서드는 QUrl::TolerantMode 모드로 작동하며, 이는 몇 가지 일반적인 오류나 데이터의 잘못된 표현을 허용함을 의미합니다. 추가 검증을 수행하는 대체 파싱 방법으로는 QUrl::StrictMode 모드가 있습니다. 파싱 모드 간의 차이점에 대한 설명은 QUrl::ParsingMode 를 참조하십시오.

QUrl은 URL 사양에 대한 준수 여부만 확인합니다. 상위 수준 프로토콜 URL이 다른 핸들러에서 기대하는 형식을 따르는지 여부는 검증하지 않습니다. 예를 들어, 다음 URI들은 사용 시 의미가 없더라도 QUrl에서는 모두 유효한 것으로 간주됩니다:

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

파서가 오류를 감지하면, ` isValid()`가 `false`를 반환하고 ` toString()` / ` toEncoded()`가 빈 문자열을 반환하도록 하여 이벤트를 알립니다. URL 파싱에 실패한 이유를 사용자에게 표시해야 하는 경우, ` errorString()`를 호출하여 QUrl에서 오류 상태를 확인할 수 있습니다. 이 메시지는 매우 기술적이어서 최종 사용자에게는 이해하기 어려울 수 있다는 점에 유의하십시오.

QUrl은 하나의 오류 조건만 기록할 수 있습니다. 오류가 두 개 이상 발견될 경우, 어떤 오류가 보고될지는 정의되지 않습니다.

문자 변환

URL 및 문자열을 다룰 때 잘못된 문자 변환을 방지하려면 다음 규칙을 따르십시오:

보안 고려 사항

신뢰할 수 없는 출처(네트워크, 파일 또는 문서, 다른 애플리케이션, 사용자)에서 온 URL은 악의적인 입력으로 간주하십시오.

  • 구문 분석된 URL을 검증하고, 원시 문자열은 절대 검증하지 마십시오. 허용/거부 목록, 출처 또는 리디렉션 검사는 원본 텍스트가 아닌 QUrl이 추출한 구성 요소에 대해 수행하십시오. 호스트 검사의 경우 url.host(QUrl::FullyEncoded) 을 사용하십시오. QUrl은 문자열 검사에서 놓치는 형식을 정규화합니다. http://0x7f.0.0.1 와 http://2130706433 는 모두 호스트 127.0.0.1 를 반환하고, http://good.com\\@evil.com/ 는 호스트 evil.com 를 반환합니다. 기본 디코딩 형식 대신 FullyEncoded 를 사용하면 국제화 도메인 이름(IDN) 호스트가 ASCII 형식으로 비교되므로, 유사하게 보이는 유니코드 문자로 위조될 수 없습니다.
  • 검증과 요청에 동일한 파싱된 URL을 사용하십시오. 나중에 원본 문자열을 다른 파서에게 전달하면, 검증 과정에서 해결된 불일치가 다시 발생하게 됩니다.
  • FullyDecoded 를 사용하여 구성 요소를 추출할 때는 각별히 주의하십시오. 결과에 따라 손실이 발생하거나, 추출된 구성 요소에 따라 의미가 달라질 수도 있습니다. 또한 NUL 를 포함한 제어 문자가 포함될 수도 있습니다. 자세한 내용은 Full decoding 를 참조하십시오.

멤버 유형 문서

[since 6.3] enum QUrl::AceProcessingOption
flags QUrl::AceProcessingOptions

ACE 처리 옵션은 URL이 ASCII 호환 인코딩으로 변환되거나 그 반대로 변환되는 방식을 제어합니다.

상수값설명
QUrl::IgnoreIDNWhitelist0x1URL을 유니코드로 변환할 때 IDN 허용 목록을 무시합니다.
QUrl::AceTransitionalProcessing0x2상수값설명URL을 유니코드로 변환할 때 IDN 화이트리스트를 무시합니다.

기본값은 비전환 처리를 사용하고, IDN 화이트리스트에 나열된 최상위 도메인을 가진 URL 내에서만 비 ASCII 문자를 허용하는 것입니다.

이 열거형은 Qt 6.3에서 도입되었습니다.

AceProcessingOptions 유형은 QFlags<AceProcessingOption>에 대한 typedef입니다. 이 유형은 AceProcessingOption 값들의 OR 조합을 저장합니다.

toAce(), fromAce() 및 idnWhitelist()도 참조하십시오 .

enum QUrl::ComponentFormattingOption
flags QUrl::ComponentFormattingOptions

QUrl::FormattingOptions 구성 요소 서식 지정 옵션은 URL의 구성 요소가 텍스트로 출력될 때 어떤 형식으로 표시될지를 정의합니다. 이 옵션들은 toString 의 옵션과 함께 () 및 toEncoded()에서 사용할 수 있습니다.

상수값설명
QUrl::PrettyDecoded0x000000구성 요소가 "예쁜 형식"으로 반환되며, 대부분의 퍼센트 인코딩된 문자가 디코딩됩니다. PrettyDecoded의 정확한 동작은 구성 요소마다 다르며, Qt 릴리스마다 달라질 수도 있습니다. 이것이 기본값입니다.
QUrl::EncodeSpaces0x100000공백 문자는 인코딩된 형태("%20")로 유지합니다.
QUrl::EncodeUnicode0x200000US-ASCII가 아닌 문자는 UTF-8 퍼센트 인코딩된 형태로 유지합니다(예: U+00E9 코드포인트, LATIN SMALL LETTER E WITH ACUTE의 경우 "%C3%A9").
QUrl::EncodeDelimiters0x400000 | 0x800000전체 URL이 텍스트로 표시될 때 URL에 나타나는 것과 같이 특정 구분자를 인코딩된 형태로 유지합니다. 이 옵션이 구분자에 미치는 영향은 구성 요소마다 다릅니다. 이 플래그는 toString() 또는 toEncoded()에서는 효과가 없습니다.
QUrl::EncodeReserved0x1000000사양에 따라 URL에 허용되지 않는 US-ASCII 문자는 인코딩된 형태로 유지합니다. 이는 toString() 및 toEncoded()에서 기본값입니다.
QUrl::DecodeReserved0x2000000URL 사양에서 URL에 포함하는 것을 허용하지 않는 US-ASCII 문자를 디코딩합니다. 이는 개별 컴포넌트의 게터에서 기본값으로 사용됩니다.
QUrl::FullyEncodedEncodeSpaces | EncodeUnicode | EncodeDelimiters | EncodeReserved이 컴포넌트가 URL의 일부로 표시될 때와 마찬가지로, 모든 문자를 올바르게 인코딩된 형태로 유지합니다. toString()와 함께 사용될 경우, 이는 QString 형식의 완전히 규격에 부합하는 URL을 생성하며, 이는 toEncoded()의 결과와 정확히 동일합니다.
QUrl::FullyDecodedFullyEncoded | DecodeReserved | 0x4000000가능한 한 많이 디코딩하도록 시도합니다. URL의 개별 구성 요소에 대해, 제어 문자(U+0000 ~ U+001F) 및 퍼센트 인코딩된 형태로 발견되는 UTF-8 시퀀스를 포함하여 모든 퍼센트 인코딩 시퀀스를 디코딩합니다. 이 모드를 사용하면 데이터 손실이 발생할 수 있습니다. 자세한 내용은 아래를 참조하십시오.

EncodeReserved와 DecodeReserved 값은 하나의 호출에서 함께 사용해서는 안 됩니다. 그렇게 할 경우 동작이 정의되지 않습니다. 이 두 값이 별도로 제공되는 이유는, 예약된 문자에 대한 "pretty mode"의 동작이 특정 구성 요소, 특히 전체 URL에서 다르게 나타나기 때문입니다.

전체 디코딩

FullyDecoded 모드는 Qt 4.x에서 ` QString `를 반환하는 함수의 동작과 유사합니다. 즉, 모든 문자는 그 자체를 나타내며 어떠한 특별한 의미도 갖지 않습니다. 이는 퍼센트 문자('%')의 경우에도 마찬가지이며, 이 문자는 퍼센트 인코딩된 시퀀스의 시작이 아니라 리터럴 퍼센트로 해석되어야 합니다. 다른 모든 디코딩 모드에서는 동일한 실제 문자가 "%25" 시퀀스로 표현됩니다.

QUrl::FullyDecoded를 통해 얻은 데이터를 QUrl 로 다시 적용할 때는, setPath() 및 setUserName()와 같은 세터 함수에 QUrl::DecodedMode 매개변수를 반드시 사용해야 합니다. 이를 준수하지 않을 경우, 퍼센트 문자('%')가 퍼센트 인코딩된 시퀀스의 시작 부분으로 재해석될 수 있습니다.

이 모드는 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"이지만 값이 없는 매개변수 하나로 해석될 가능성이 높습니다.

ComponentFormattingOptions 유형은 QFlags<ComponentFormattingOption>에 대한 typedef입니다. 이 유형은 ComponentFormattingOption 값들의 OR 조합을 저장합니다.

QUrl::FormattingOptions도 참조하십시오 .

enum QUrl::ParsingMode

구문 분석 모드는 QUrl 가 문자열을 구문 분석하는 방식을 제어합니다.

상수값설명
QUrl::TolerantMode0QUrl 는 URL에서 흔히 발생하는 오류를 수정하려고 시도합니다. 이 모드는 표준을 엄격하게 준수한다고 알려져 있지 않은 출처에서 온 URL을 파싱할 때 유용합니다.
QUrl::StrictMode1유효한 URL만 허용됩니다. 이 모드는 일반적인 URL 유효성 검사에 유용합니다.
QUrl::DecodedMode2QUrl URL 구성 요소를 완전히 디코딩된 형태로 해석하며, 이때 퍼센트 문자는 퍼센트 인코딩 시퀀스의 시작이 아닌 그 자체로 해석됩니다. 이 모드는 URL의 구성 요소를 설정하는 세터에서만 유효하며, ` QUrl ` 생성자, ` fromEncoded()` 또는 ` setUrl()`에서는 허용되지 않습니다. 이 모드에 대한 자세한 내용은 ` QUrl::FullyDecoded` 문서를 참조하십시오.

TolerantMode에서 파서는 다음과 같은 동작을 보입니다:

  • 공백 및 "%20": 인코딩되지 않은 공백 문자는 허용되며 "%20"과 동일하게 처리됩니다.
  • 단일 "%" 문자: "%" 문자가 16진수 두 자리가 뒤따르지 않는 경우(예: "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::UrlFormattingOption
flags QUrl::FormattingOptions

서식 옵션은 URL이 텍스트로 출력될 때의 서식 지정 방식을 정의합니다.

상수값설명
QUrl::None0x0URL의 형식은 변경되지 않습니다.
QUrl::RemoveScheme0x1URL에서 스키마가 제거됩니다.
QUrl::RemovePassword0x2URL에 포함된 모든 비밀번호가 제거됩니다.
QUrl::RemoveUserInfoRemovePassword | 0x4URL에 포함된 모든 사용자 정보가 제거됩니다.
QUrl::RemovePort0x8URL에서 지정된 포트는 제거됩니다.
QUrl::RemoveAuthorityRemoveUserInfo | RemovePort | 0x10사용자 이름, 비밀번호, 호스트 및 포트를 제거합니다.
QUrl::RemovePath0x20URL의 경로가 제거되고, 스키마, 호스트 주소 및 포트(있는 경우)만 남습니다.
QUrl::RemoveQuery0x40URL의 쿼리 부분('?' 문자 뒤)이 제거됩니다.
QUrl::RemoveFragment0x80URL의 프래그먼트 부분('#' 문자를 포함)이 제거됩니다.
QUrl::RemoveFilename0x800파일 이름(즉, 경로에서 마지막 '/' 이후의 모든 부분)이 제거됩니다. StripTrailingSlash가 설정되어 있지 않은 한, 끝의 '/'는 유지됩니다. RemovePath가 설정되어 있지 않은 경우에만 유효합니다.
QUrl::PreferLocalFile0x200URL이 isLocalFile()에 따라 로컬 파일이며 쿼리나 프래그먼트가 포함되어 있지 않은 경우, 로컬 파일 경로가 반환됩니다.
QUrl::StripTrailingSlash0x400경로에 끝 '/'가 있으면 제거됩니다.
QUrl::NormalizePathSegments0x1000경로를 수정하여 불필요한 디렉터리 구분자를 제거하고, "." 및 ".."을 (가능한 한) 해결합니다. 로컬이 아닌 경로의 경우, 인접한 슬래시는 유지됩니다.

QUrl 이 준수하는 Nameprep의 대소문자 변환 규칙에 따라, 사용된 Qt::FormattingOptions에 관계없이 호스트 이름은 항상 소문자로 변환된다는 점에 유의하십시오.

QUrl::ComponentFormattingOptions 의 옵션도 사용할 수 있습니다.

FormattingOptions 유형은 QFlags<UrlFormattingOption>에 대한 typedef입니다. 이 유형은 UrlFormattingOption 값들의 OR 조합을 저장합니다.

QUrl::ComponentFormattingOptions도 참조하십시오 .

enum QUrl::UserInputResolutionOption
flags QUrl::UserInputResolutionOptions

사용자 입력 해상도 옵션은 ` fromUserInput()` 함수가 상대 경로이거나 HTTP URL의 축약형일 수 있는 문자열을 어떻게 해석해야 하는지를 정의합니다. 예를 들어, ` file.pl `는 로컬 파일일 수도 있고, ` http://file.pl`라는 URL일 수도 있습니다.

상수값설명
QUrl::DefaultResolution0기본 해석 방식은 fromUserInput 에 지정된 작업 디렉터리에서 로컬 파일이 존재하는지 확인하고, 해당 파일이 있을 경우에만 로컬 경로를 반환하는 것입니다. 그렇지 않은 경우 URL로 간주됩니다.
QUrl::AssumeLocalFile1이 옵션을 사용하면, 입력에 http://file.pl 와 같은 스키마가 포함되어 있지 않은 한 fromUserInput()가 항상 로컬 경로를 반환합니다. 이는 파일이 존재하지 않을 경우 파일을 생성할 수 있는 텍스트 편집기와 같은 응용 프로그램에 유용합니다.

UserInputResolutionOptions 유형은 QFlags<UserInputResolutionOption>에 대한 typedef입니다. 이 유형은 UserInputResolutionOption 값들의 OR 조합을 저장합니다.

fromUserInput()도 참조하십시오 .

멤버 함수 문서

QUrl::QUrl()

빈 QUrl 객체를 생성합니다.

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

url 을 파싱하여 URL을 생성합니다. 이 생성자는 올바른 URL 또는 URL 참조를 기대하며, 의도를 추측하려고 시도하지 않는다는 점에 유의하십시오. 예를 들어, 다음 선언:

QUrl url("example.com");

유효한 URL을 생성하지만, 입력에서 scheme() 부분이 누락되어 있어 사용자가 기대하는 것과 다를 수 있습니다. 위와 같은 문자열의 경우, 애플리케이션에서는 fromUserInput()를 사용하는 것이 좋습니다. 이 생성자나 setUrl()를 사용할 때, 다음과 같은 형태가 의도된 것일 가능성이 높습니다:

QUrl url("https://example.com");

QUrl은 URL에서 허용되지 않는 모든 문자를 자동으로 퍼센트 인코딩하고, 비예약 문자(문자, 숫자, 하이픈, 밑줄, 점, 물결표)를 나타내는 퍼센트 인코딩된 시퀀스를 디코딩합니다. 그 외의 모든 문자는 원래 형태로 유지됩니다.

파서 모드 ` parsingMode`을 사용하여 ` url `을 파싱합니다. ` TolerantMode `(기본값)에서 QUrl은 특정 오류를 수정합니다. 특히, 퍼센트 기호('%') 뒤에 16진수 두 자리가 따르지 않는 경우를 수정하며, 어떤 위치에든 어떤 문자라도 허용합니다. 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도 참조하십시오 .

[noexcept] QUrl::QUrl(const QUrl &other)

other 의 복사본을 생성합니다.

[noexcept] QUrl::QUrl(QUrl &&other)

other 가 가리키던 것과 동일한 객체를 가리키도록 QUrl 인스턴스를 생성합니다.

[noexcept] QUrl::~QUrl()

소멸자; 객체가 삭제되기 직전에 호출됩니다.

QUrl QUrl::adjusted(QUrl::FormattingOptions options) const

조정된 URL을 반환합니다. options 에 플래그를 전달하여 출력을 사용자 정의할 수 있습니다.

QUrl::ComponentFormattingOption 의 인코딩 옵션은 이 메서드에서는 큰 의미가 없으며, QUrl::PreferLocalFile 도 마찬가지입니다.

이 메서드는 항상 QUrl(url.toString(options))와 동일합니다.

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도 참조하십시오 .

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 에서 디코딩된 형태로 표현할 수 없는 일부 제어 시퀀스에 대한 퍼센트 인코딩된 시퀀스가 포함될 수 있습니다.

path()도 참조하십시오 .

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

URL의 프래그먼트를 반환합니다. 구문 분석된 URL에 프래그먼트가 포함되어 있는지 확인하려면 ` hasFragment()`를 사용하십시오.

options 인자는 프래그먼트 구성 요소의 형식 지정 방식을 제어합니다. 모든 값은 모호함이 없는 결과를 생성합니다. QUrl::FullyDecoded 을 사용하면 모든 퍼센트 인코딩된 시퀀스가 디코딩됩니다. 그렇지 않은 경우, 반환된 값에는 QString 에서 디코딩된 형태로 표현할 수 없는 일부 제어 시퀀스에 대한 퍼센트 인코딩된 시퀀스가 포함될 수 있습니다.

QUrl::FullyDecoded 를 사용하면 표현할 수 없는 시퀀스가 존재할 경우 데이터 손실이 발생할 수 있습니다. 결과가 URL이 아닌 컨텍스트에서 사용될 때 이 값을 사용하는 것이 권장됩니다.

setFragment() 및 hasFragment()도 참조하십시오 .

[static, since 6.3] QString QUrl::fromAce(const QByteArray &domain, QUrl::AceProcessingOptions options = {})

ASCII 호환 인코딩(ACE)으로 인코딩된 주어진 도메인 이름 domain 의 유니코드 형태를 반환합니다. options 에 플래그를 전달하여 출력 결과를 사용자 정의할 수 있습니다. 이 함수의 결과는 domain 와 동등한 것으로 간주됩니다.

domain 의 값을 인코딩할 수 없는 경우, 해당 값은 QString 로 변환되어 반환됩니다.

ASCII 호환 인코딩(ACE)은 RFC 3490, RFC 3491 및 RFC 3492에 정의되어 있으며, 유니코드 기술 표준 #46에 의해 업데이트되었습니다. 이는 IDNA(Internationalizing Domain Names in Applications) 사양의 일부로, "example.com" 과 같은 도메인 이름을 비 US-ASCII 문자로 표기할 수 있게 해줍니다.

이 함수는 Qt 6.3에서 도입되었습니다.

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

CFURL url 의 복사본을 포함하는 QUrl 객체를 생성합니다.

[static] QUrl QUrl::fromEncoded(QByteArrayView input, QUrl::ParsingMode mode = TolerantMode)

input 을 파싱하여 해당 QUrl 을 반환합니다. input 은 인코딩된 형식이며, ASCII 문자만 포함된 것으로 간주됩니다.

mode 를 사용하여 URL을 파싱합니다. 이 매개변수에 대한 자세한 내용은 setUrl()을 참조하십시오. 이 맥락에서는 QUrl::DecodedMode 를 사용할 수 없습니다.

참고: Qt 6.7 이전버전에서는 이 함수가 QByteArrayView 가 아닌 QByteArray 를 인수로 받았습니다. 컴파일 오류가 발생하는 경우, 코드에서 QByteArray 로는 암시적으로 변환될 수 있지만 QByteArrayView 로는 변환될 수 없는 객체를 전달하고 있기 때문입니다. 해당 인수를 QByteArray{~~~} 로 감싸서 형 변환을 명시적으로 수행하십시오. 이는 이전 Qt 버전과 하위 호환됩니다.

toEncoded() 및 setUrl()도 참조하십시오 .

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

localFile 를 로컬 파일로 해석한 ` QUrl ` 표현을 반환합니다. 이 함수는 슬래시로 구분된 경로뿐만 아니라 해당 플랫폼의 기본 구분 기호로 구분된 경로도 받아들입니다.

또한 이 함수는 "//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/");
// 잘못된 예: url에 이미 스킴이 포함되어 있으므로 QUrl("file:file.txt")가 출력됩니다.
qDebug() << baseUrl.resolved(url);

이러한 URL을 해석하려면 먼저 스키마를 제거해야 합니다:

// 올바른 예: QUrl("file:///home/user/file.txt")를 출력함
url.setScheme(QString());
qDebug() << baseUrl.resolved(url);

따라서 상대 파일 경로에는 상대 URL(즉, 스키마가 없는 URL)을 사용하는 것이 좋습니다:

QUrl url = QUrl("file.txt");
QUrl baseUrl = QUrl("file:/home/user/");
// QUrl("file:///home/user/file.txt")를 출력합니다
qDebug() << baseUrl.resolved(url);

toLocalFile(), isLocalFile() 및 QDir::toNativeSeparators()도 참조하십시오 .

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

NSURL url 의 복사본을 포함하는 QUrl 객체를 생성합니다.

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

input 의 디코딩된 사본을 반환합니다. input 는 먼저 퍼센트 인코딩에서 디코딩된 후, UTF-8에서 유니코드로 변환됩니다.

참고: 유효하지 않은 입력(예: 유효한 16진수가 아닌 "%G5" 시퀀스를 포함하는 문자열)이주어지면 출력도 유효하지 않게 됩니다. 예를 들어, "%G5" 시퀀스는 'W'로 디코딩될 수 있습니다.

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

QUrl(str, mode)를 사용하여, urls 를 나타내는 문자열 목록을 URL 목록으로 변환합니다. 이때 모든 문자열은 URL이어야 하며, 예를 들어 로컬 경로 등은 허용되지 않는다는 점에 유의하십시오.

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

사용자가 제공한 userInput 문자열에서 유효한 URL을 추론할 수 있는 경우 이를 반환합니다. 추론이 불가능한 경우에는 유효하지 않은 QUrl()를 반환합니다.

이를 통해 사용자는 일반 문자열 형식으로 URL이나 로컬 파일 경로를 입력할 수 있습니다. 이 문자열은 주소 표시줄에 직접 입력하거나, 클립보드에서 가져오거나, 명령줄 인수를 통해 전달할 수 있습니다.

문자열이 이미 유효한 URL이 아닌 경우, 다양한 가정을 바탕으로 가장 타당한 추정을 수행합니다.

문자열이 시스템상의 유효한 파일 경로에 해당하는 경우, ` QUrl::fromLocalFile()`를 사용하여 `file://` URL이 생성됩니다.

그렇지 않은 경우, 문자열을 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 가 비어 있으면 상대 경로에 대한 처리는 수행되지 않습니다.

기본적으로, 상대 경로처럼 보이는 입력 문자열은 해당 파일이 지정된 작업 디렉터리에 실제로 존재하는 경우에만 상대 경로로 처리됩니다. 애플리케이션이 아직 존재하지 않는 파일을 처리할 수 있다면, options 에 AssumeLocalFile 플래그를 전달해야 합니다.

bool QUrl::hasFragment() const

이 URL에 프래그먼트가 포함되어 있는 경우(즉, URL에 #이 있는 경우) true 를 반환합니다.

fragment() 및 setFragment()도 참조하십시오 .

bool QUrl::hasQuery() const

이 URL에 쿼리가 포함되어 있는 경우(즉, URL에 ‘?’가 포함된 경우), true 를 반환합니다.

setQuery(), query(), hasFragment()도 참조하십시오 .

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

URL에 호스트가 정의되어 있으면 해당 호스트를 반환하고, 그렇지 않으면 빈 문자열을 반환합니다.

options 인수는 호스트명의 서식 지정 방식을 제어합니다. QUrl::EncodeUnicode 옵션을 사용하면 이 함수는 ASCII 호환 인코딩(ACE) 형식의 호스트명을 반환하게 되며, 이는 8비트 호환이 되지 않거나 레거시 호스트명이 필요한 채널(예: DNS 요청이나 HTTP 요청 헤더)에서 사용하기에 적합합니다. 이 플래그가 없으면, 이 함수는 허용되는 최상위 도메인 목록( idnWhitelist() 참조)에 따라 유니코드 형식의 국제 도메인 이름(IDN)을 반환합니다.

그 외의 모든 플래그는 무시됩니다. 호스트 이름에는 제어 문자나 퍼센트 기호가 포함될 수 없으므로, 반환된 값은 완전히 디코딩된 것으로 간주할 수 있습니다.

setHost(), idnWhitelist(), setIdnWhitelist(), authority()도 참조하십시오 .

[static] QStringList QUrl::idnWhitelist()

구성에 비-ASCII 문자를 포함할 수 있도록 허용된 최상위 도메인의 현재 허용 목록을 반환합니다.

이 목록의 근거에 대해서는 setIdnWhitelist()을 참조하십시오.

setIdnWhitelist() 및 AceProcessingOption도 참조하십시오 .

bool QUrl::isEmpty() const

URL에 데이터가 없으면 true 를 반환하고, 그렇지 않으면 false 를 반환합니다.

clear()도 참조하십시오 .

bool QUrl::isLocalFile() const

이 URL이 로컬 파일 경로를 가리키는 경우 ` true `를 반환합니다. 스키마가 “file”인 경우 해당 URL은 로컬 파일 경로로 간주됩니다.

이 함수는 호스트명이 포함된 URL의 경우, 최종 파일 경로를 QFile::open()로 열 수 없더라도 로컬 파일 경로로 간주한다는 점에 유의하십시오.

fromLocalFile() 및 toLocalFile()도 참조하십시오 .

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

이 URL이 childUrl 의 상위 URL인 경우 true 를 반환합니다. 두 URL이 동일한 스키마와 권한을 공유하고, 이 URL의 경로가 childUrl 의 경로보다 상위인 경우, childUrl 는 이 URL의 하위 URL입니다.

bool QUrl::isRelative() const

URL이 상대 URL인 경우 true 을 반환하고, 그렇지 않은 경우 false 을 반환합니다. 스키마가 정의되지 않은 URL은 상대 참조로 간주되므로, 이 함수는 scheme()을 호출하는 것과 동일합니다.isEmpty().

상대 참조는 RFC 3986 4.2절에 정의되어 있습니다.

Relative URLs vs Relative Paths도 참조하십시오 .

bool QUrl::isValid() const

URL이 비어 있지 않고 유효한 경우 ` true `을 반환하고, 그렇지 않은 경우 ` false`을 반환합니다.

URL에 대한 적합성 검사가 수행됩니다. URL이 유효한 것으로 판정되려면 URL의 모든 부분이 URI 표준의 표준 인코딩 규칙을 준수해야 합니다.

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

    return true;
}

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

이 URL과 주어진 url 에 모두 options 를 적용한 후 두 URL이 동일하면 true 를 반환하고, 그렇지 않으면 false 를 반환합니다.

이는 두 URL 모두에 adjusted(options)를 호출한 후 결과 URL을 비교하는 것과 동일하지만, 더 빠르게 수행됩니다.

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

URL에 비밀번호가 정의되어 있으면 해당 비밀번호를 반환하고, 그렇지 않으면 빈 문자열을 반환합니다.

options 인수는 사용자 이름 구성 요소의 서식 지정 방식을 제어합니다. 모든 값은 모호함이 없는 결과를 생성합니다. QUrl::FullyDecoded 를 사용하면 모든 퍼센트 인코딩된 시퀀스가 디코딩됩니다. 그렇지 않은 경우, QString 에서 디코딩된 형태로 표현할 수 없는 일부 제어 시퀀스에 대해 반환된 값에 퍼센트 인코딩된 시퀀스가 포함될 수 있습니다.

QUrl::FullyDecoded 를 사용할 경우, 표현할 수 없는 시퀀스가 존재하면 데이터 손실이 발생할 수 있습니다. 이 값은 결과가 QAuthenticator 설정이나 로그인 협상 등 URL이 아닌 컨텍스트에서 사용될 때 사용하는 것이 권장됩니다.

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 를 사용하면 표현할 수 없는 시퀀스가 존재할 경우 데이터 손실이 발생할 수 있습니다. 이 값은 결과가 FTP 서버로 전송하는 등 URL이 아닌 맥락에서 사용될 때 사용하는 것이 좋습니다.

데이터 손실의 예로는, 유니코드가 아닌 퍼센트 인코딩된 시퀀스가 존재할 때 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 에서 디코딩된 형태로 표현할 수 없는 일부 제어 시퀀스에 대해 반환된 값에 퍼센트 인코딩된 시퀀스가 포함될 수 있습니다.

쿼리에서는 "%2B" 시퀀스를 사용하여 더하기 기호('+')를 표현하는 경우를 포함하여, 퍼센트 인코딩된 상태로 유지되어야 하는 데이터가 자주 포함되므로, QUrl::FullyDecoded 의 사용은 권장되지 않습니다.

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(qUtf8Printable(baseUrl.resolved(relativeUrl).toString()));
// “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, QUrl::ParsingMode mode = TolerantMode)

URL의 권한을 authority 로 설정합니다.

URL의 권한은 사용자 정보, 호스트 이름 및 포트의 조합입니다. 이 요소들은 모두 선택 사항이므로, 빈 권한도 유효합니다.

사용자 정보와 호스트는 '@'로 구분되며, 호스트와 포트는 ':'로 구분됩니다. 사용자 정보가 비어 있는 경우 '@'를 생략해야 하지만, 포트가 비어 있는 경우에는 불필요한 ':'가 허용됩니다.

다음 예시는 유효한 권한 문자열을 보여줍니다:

‘스킴’, ‘인증 기관’, ‘사용자 정보(사용자 이름 및 비밀번호)’, ‘호스트’, ‘포트’로 표시된 URL의 스크린샷.

authority 데이터는 mode 에 따라 해석됩니다. StrictMode 에 따르면, 모든 '%' 문자 뒤에는 정확히 두 개의 16진수 문자가 따라와야 하며, 일부 문자(공백 포함)는 디코딩되지 않은 형태로 사용할 수 없습니다. TolerantMode (기본값)에서는 모든 문자가 디코딩되지 않은 형태로 허용되며, 관용적인 파서가 16진수 두 자리가 뒤따르지 않는 불필요한 '%'를 수정합니다.

이 함수는 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의 스크린샷

프래그먼트는 때때로 URL "참조"라고도 불립니다.

QString() 인자(null인 QString)를 전달하면 프래그먼트가 해제됩니다. QString("") 인자(비어 있지만 null이 아닌 QString)를 전달하면 프래그먼트가 빈 문자열로 설정됩니다(마치 원래 URL에 "#" 하나만 있는 것처럼).

fragment 데이터는 mode 에 따라 해석됩니다. StrictMode 에서는 모든 '%' 문자의 뒤에 정확히 두 개의 16진수 문자가 따라와야 하며, 일부 문자(공백 포함)는 인코딩되지 않은 형태로 허용되지 않습니다. TolerantMode 에서는 모든 문자가 인코딩되지 않은 형태로 허용되며, 관대한 파서가 두 개의 16진수 문자가 뒤따르지 않는 불필요한 '%'를 수정합니다. DecodedMode 에서는 '%'가 그 자체를 나타내며, 인코딩된 문자는 사용할 수 없습니다.

QUrl::DecodedMode URL이 아닌 데이터 소스에서 프래그먼트를 설정하거나, QUrl::FullyDecoded 서식 옵션을 사용하여 fragment()를 호출하여 얻은 프래그먼트를 설정할 때 사용해야 합니다.

fragment() 및 hasFragment()도 참조하십시오 .

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

URL의 호스트를 host 로 설정합니다. 호스트는 권한(authority)의 일부입니다.

host 데이터는 mode 에 따라 해석됩니다. StrictMode 에서는 모든 '%' 문자 뒤에 정확히 두 개의 16진수 문자가 따라와야 하며, 일부 문자(공백 포함)는 인코딩되지 않은 형태로 사용할 수 없습니다. TolerantMode 에서는 모든 문자가 인코딩되지 않은 형태로 허용되며, 관대한 파서는 두 개의 16진수 문자가 뒤따르지 않는 불필요한 '%'를 수정합니다. DecodedMode 에서는 '%'가 그 자체를 나타내며, 인코딩된 문자는 사용할 수 없습니다.

모든 경우에 있어, 구문 분석 결과는 국제화된 리소스 식별자(RFC 3987) 사양에 따라 수정된 STD 3 규칙에 부합하는 유효한 호스트 이름이어야 합니다. 유효하지 않은 호스트 이름은 허용되지 않으며, 이 경우 isValid()의 반환값이 false가 됩니다.

host() 및 setAuthority()도 참조하십시오 .

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

도메인에 비-ASCII 문자를 포함할 수 있도록 허용된 최상위 도메인(TLD)의 허용 목록을 list 값으로 설정합니다.

이 함수를 호출하는 경우, idnWhitelist()에 접근할 가능성이 있는 스레드를 시작하기 전에 호출해야 합니다.

Qt에는 국제화 도메인 이름(IDN)을 공식적으로 지원하는 인터넷 최상위 도메인과, 겉보기에는 비슷해 보이는 문자(예: 라틴 소문자 'a' 와 대부분의 글꼴에서 시각적으로 동일한 키릴 문자) 간에 혼동이 발생하지 않도록 보장하는 규칙이 포함된 기본 목록이 함께 제공됩니다.

이 목록은 등록 기관이 새로운 규칙을 발표함에 따라 주기적으로 관리됩니다.

이 함수는 TLD를 추가하거나 제거하기 위해 목록을 조작해야 하는 사용자를 위해 제공됩니다. 테스트 목적 이외에 이 값을 변경하는 것은 사용자를 보안 위험에 노출시킬 수 있으므로 권장되지 않습니다.

idnWhitelist()도 참조하십시오 .

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

URL의 비밀번호를 password 로 설정합니다. password 는 setUserInfo()에 설명된 대로, 해당 URL의 권한(authority) 내 사용자 정보(user info) 요소의 일부입니다.

password 데이터는 mode 에 따라 해석됩니다. StrictMode 에서는 '%' 문자가 나오면 반드시 그 뒤에 정확히 두 개의 16진수 문자가 따라와야 하며, 일부 문자(공백 포함)는 인코딩되지 않은 형태로 사용할 수 없습니다. TolerantMode 에서는 모든 문자가 인코딩되지 않은 형태로 허용되며, 관대한 파서(tolerant parser)는 두 개의 16진수 문자가 뒤따르지 않는 불필요한 '%'를 수정합니다. DecodedMode 에서는 '%'가 그 자체를 나타내며, 인코딩된 문자는 사용할 수 없습니다.

QUrl::DecodedMode URL이 아닌 데이터 소스(예: 사용자에게 표시되는 비밀번호 대화 상자 또는 QUrl::FullyDecoded 서식 옵션을 사용하여 password()를 호출하여 얻은 비밀번호)에서 비밀번호를 설정할 때 사용해야 합니다.

password() 및 setUserInfo()도 참조하십시오 .

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

URL의 경로를 path 로 설정합니다. 경로는 URL에서 도메인 이름 뒤, 쿼리 문자열 앞에 오는 부분을 말합니다.

경로가 강조 표시된 URL이 담긴 스크린샷

비계층적 스키마의 경우, 경로는 다음 예시와 같이 스키마 선언 뒤에 오는 모든 부분입니다:

메일 경로가 강조 표시된 URL의 스크린샷

path 데이터는 mode 에 따라 해석됩니다. StrictMode 에서 '%' 문자가 나오면 반드시 그 뒤에 정확히 두 개의 16진수 문자가 따라와야 하며, 일부 문자(공백 포함)는 인코딩되지 않은 형태로 사용할 수 없습니다. TolerantMode 에서는 모든 문자가 인코딩되지 않은 형태로 허용되며, 관용적인 파서는 두 개의 16진수 문자가 뒤따르지 않는 불필요한 '%'를 수정합니다. DecodedMode 에서는 '%'가 그 자체를 나타내며, 인코딩된 문자는 사용할 수 없습니다.

QUrl::DecodedMode 사용자에게 표시되는 대화 상자나 QUrl::FullyDecoded 포맷팅 옵션을 사용하여 path()를 호출해 얻은 경로와 같이, URL이 아닌 데이터 소스에서 경로를 설정할 때 사용해야 합니다.

path()도 참조하십시오 .

void QUrl::setPort(int port)

URL의 포트를 port 로 설정합니다. setAuthority()에 설명된 바와 같이, 포트는 URL의 권한 부분입니다.

port 값은 0부터 65535까지(이 두 값 포함)여야 합니다. 포트를 -1로 설정하면 포트가 지정되지 않았음을 나타냅니다.

port()도 참조하십시오 .

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

URL의 쿼리 문자열을 query 로 설정합니다.

이 함수는 키-값 패턴에 맞지 않는 쿼리 문자열을 전달해야 하거나, QUrl 에서 권장하는 방식과 다른 특수 문자 인코딩 방식을 사용하는 쿼리 문자열을 전달해야 할 때 유용합니다.

query 에 QString() 값( QString 의 null 값)을 전달하면 쿼리가 완전히 제거됩니다. 그러나 QString("") 값을 전달하면, 마치 원래 URL에 "?" 하나만 있는 것처럼 쿼리가 빈 값으로 설정됩니다.

query 데이터는 mode 에 따라 해석됩니다. StrictMode 에서는 모든 '%' 문자 뒤에 정확히 두 개의 16진수 문자가 따라와야 하며, 일부 문자(공백 포함)는 인코딩되지 않은 형태로 사용할 수 없습니다. TolerantMode 에서는 모든 문자가 인코딩되지 않은 형태로 허용되며, 허용 범위가 넓은 파서가 두 개의 16진수 문자가 뒤따르지 않는 불필요한 '%'를 수정합니다. DecodedMode 에서는 '%'가 그 자체를 나타내며, 인코딩된 문자는 사용할 수 없습니다.

쿼리 문자열에는 종종 퍼센트 인코딩된 시퀀스가 포함되므로, DecodedMode 의 사용은 권장되지 않습니다. 주의해야 할 특별한 시퀀스 중 하나는 더하기 기호('+')입니다. QUrl 는 웹 브라우저가 전송하는 HTML 양식에서 공백을 더하기 기호로 변환하더라도, 공백을 더하기 기호로 변환하지 않습니다. 쿼리에서 실제 더하기 기호를 표현하기 위해서는 일반적으로 "%2B" 시퀀스가 사용됩니다. 이 함수는 TolerantMode 또는 StrictMode 에서 "%2B" 시퀀스를 변경하지 않습니다.

query() 및 hasQuery()도 참조하십시오 .

void QUrl::setQuery(const QUrlQuery &query)

URL의 쿼리 문자열을 query 로 설정합니다.

이 함수는 QUrlQuery 객체에서 쿼리 문자열을 재구성하여 이 QUrl 객체에 설정합니다. QUrlQuery 에는 이미 파싱된 데이터가 포함되어 있으므로 이 함수에는 파싱 매개변수가 없습니다.

이 함수는 오버로드된 함수입니다.

query() 및 hasQuery()도 참조하십시오 .

void QUrl::setScheme(const QString &scheme)

URL의 스키마를 scheme 로 설정합니다. 스키마는 ASCII 문자만 포함할 수 있으므로, 입력값에 대한 변환이나 디코딩은 수행되지 않습니다. 또한 스키마는 반드시 ASCII 영문자로 시작해야 합니다.

스키마는 URL의 유형(또는 프로토콜)을 나타냅니다. 이는 URL의 시작 부분에 하나 이상의 ASCII 문자로 표시됩니다.

스키마는 RFC 3986을 엄격히 준수합니다: scheme = ALPHA *( ALPHA / DIGIT / "+" / "-" / "." )

다음 예제는 스키마가 "ftp"인 URL을 보여줍니다:

'ftp://'로 시작하는 예시 URL에서 'ftp'를 스키마로 강조한 그림.

스키마를 설정하려면 다음 호출을 사용합니다:

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

스키마가 비어 있을 수도 있으며, 이 경우 URL은 상대 경로로 해석됩니다.

scheme() 및 isRelative()도 참조하십시오 .

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

url 를 파싱하고 이 객체를 해당 값으로 설정합니다. QUrl 는 URL에서 허용되지 않는 모든 문자를 자동으로 퍼센트 인코딩하고, 비예약 문자(문자, 숫자, 하이픈, 밑줄, 점, 물결표)를 나타내는 퍼센트 인코딩된 문자열을 디코딩합니다. 그 외의 모든 문자는 원래 형태로 유지됩니다.

parsingMode 파서 모드를 사용하여 url 을 파싱합니다. TolerantMode (기본값)에서는 QUrl 가 특정 오류를 수정하며, 특히 퍼센트 기호('%') 뒤에 16진수 두 자리가 따르지 않는 경우를 수정하고, 어떤 위치에든 어떤 문자든 허용합니다. StrictMode 에서는 인코딩 오류가 허용되지 않으며, QUrl 는 인코딩되지 않은 형태로 특정 금지 문자가 포함되어 있지 않은지도 확인합니다. StrictMode 에서 오류가 감지되면, isValid()는 false를 반환합니다. 파싱 모드 DecodedMode 는 이 컨텍스트에서 허용되지 않으며, 런타임 경고를 발생시킵니다.

url() 및 toString()도 참조하십시오 .

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

URL의 사용자 정보를 userInfo 로 설정합니다. setAuthority()에 설명된 바와 같이, 사용자 정보는 URL의 권한(authority)에서 선택적 부분입니다.

사용자 정보는 사용자 이름과 선택적으로 비밀번호로 구성되며, ':'로 구분됩니다. 비밀번호가 없는 경우 콜론은 생략해야 합니다. 다음 예제는 유효한 사용자 정보 문자열을 보여줍니다:

사용자 정보가 강조 표시된 URL의 스크린샷

userInfo 데이터는 mode 에 따라 해석됩니다. StrictMode 에 따르면, 모든 '%' 문자 뒤에는 정확히 두 개의 16진수 문자가 따라와야 하며, 일부 문자(공백 포함)는 디코딩되지 않은 형태로는 허용되지 않습니다. TolerantMode (기본값)에서는 모든 문자가 인코딩되지 않은 형태로 허용되며, 관대한 파서(tolerant parser)가 16진수 두 자리가 뒤따르지 않는 불필요한 '%'를 자동으로 수정합니다.

이 함수는 mode 가 QUrl::DecodedMode 가 되는 것을 허용하지 않습니다. 완전히 디코딩된 데이터를 설정하려면 setUserName()과 setPassword()을 개별적으로 호출하십시오.

userInfo(), setUserName(), setPassword() 및 setAuthority()도 참조하십시오 .

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

URL의 사용자 이름을 userName 으로 설정합니다. userName 는 setUserInfo()에 설명된 대로, URL의 권한(authority) 내 사용자 정보(user info) 요소의 일부입니다.

userName 데이터는 mode 에 따라 해석됩니다. StrictMode 에 따르면, 모든 '%' 문자 뒤에는 정확히 두 개의 16진수 문자가 따라와야 하며, 일부 문자(공백 포함)는 디코딩되지 않은 형태로 사용할 수 없습니다. TolerantMode (기본값)에서는 모든 문자가 인코딩되지 않은 형태로 허용되며, 허용 범위가 넓은 파서가 16진수 문자 두 개가 뒤따르지 않는 불필요한 '%'를 수정합니다. DecodedMode 에서는 '%'가 그 자체를 나타내며, 인코딩된 문자는 사용할 수 없습니다.

QUrl::DecodedMode 이 설정은 사용자에게 표시되는 비밀번호 대화 상자와 같이 URL이 아닌 데이터 소스에서 사용자 이름을 설정할 때, 또는 QUrl::FullyDecoded 서식 지정 옵션을 사용하여 userName()를 호출하여 얻은 사용자 이름을 설정할 때 사용해야 합니다.

userName() 및 setUserInfo()도 참조하십시오 .

[noexcept] void QUrl::swap(QUrl &other)

이 URL을 other 로 바꿉니다. 이 작업은 매우 빠르며 절대 실패하지 않습니다.

[static, since 6.3] QByteArray QUrl::toAce(const QString &domain, QUrl::AceProcessingOptions options = {})

주어진 도메인 이름 domain 의 ASCII 호환 인코딩을 반환합니다. options 를 사용하여 플래그를 전달함으로써 출력 결과를 사용자 정의할 수 있습니다. 이 함수의 결과는 domain 와 동등한 것으로 간주됩니다.

ASCII 호환 인코딩(ACE)은 RFC 3490, RFC 3491 및 RFC 3492에 정의되어 있으며, 유니코드 기술 표준 #46을 통해 업데이트되었습니다. 이는 애플리케이션 내 도메인 이름 국제화(IDNA) 사양의 일부로, 이를 통해 "example.com" 과 같은 도메인 이름을 비-US-ASCII 문자로 표기할 수 있습니다.

domain 가 유효한 호스트 이름이 아닌 경우, 이 함수는 빈 QByteArray 을 반환합니다. 특히, IPv6 리터럴은 유효한 도메인 이름이 아니라는 점에 유의하십시오.

이 함수는 Qt 6.3에서 도입되었습니다.

CFURLRef QUrl::toCFURL() const

QUrl 를 기반으로 CFURL을 생성합니다.

호출자가 CFURL을 소유하며, 이를 해제할 책임이 있습니다.

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

URL을 사람이 읽을 수 있는 문자열 형식으로 반환합니다. options 를 통해 플래그를 전달하여 출력 형식을 사용자 정의할 수 있습니다. 비밀번호는 절대로 사용자에게 노출되어서는 안 되므로, RemovePassword 옵션은 항상 활성화되어 있습니다.

기본 옵션으로 반환된 QString 는 나중에 QUrl 에 다시 전달할 수 있지만, 초기 상태에 포함되었던 비밀번호는 모두 사라집니다.

FormattingOptions, toEncoded(), toString()도 참조하십시오 .

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

URL이 유효한 경우 인코딩된 표현을 반환하고, 그렇지 않은 경우 빈 QByteArray 을 반환합니다. options 을 통해 플래그를 전달하여 출력 결과를 사용자 정의할 수 있습니다.

사용자 정보, 경로 및 프래그먼트는 모두 UTF-8로 변환된 후, 모든 비 ASCII 문자는 퍼센트 인코딩 처리됩니다. 호스트 이름은 Punycode를 사용하여 인코딩됩니다.

QString QUrl::toLocalFile() const

이 URL의 경로를 로컬 파일 경로 형식으로 변환하여 반환합니다. 반환된 경로에는 원래 역슬래시(\)로 구성된 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()도 참조하십시오 .

NSURL *QUrl::toNSURL() const

QUrl 에서 NSURL을 생성합니다.

NSURL은 자동 해제됩니다.

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

input 의 인코딩된 사본을 반환합니다. input 는 먼저 UTF-8로 변환되며, 비예약 그룹에 속하지 않는 모든 ASCII 문자는 퍼센트 인코딩됩니다. 문자가 퍼센트 인코딩되는 것을 방지하려면 해당 문자를 exclude 에 전달하십시오. 문자가 퍼센트 인코딩되도록 강제하려면 해당 문자를 include 에 전달하십시오.

'Unreserved'는 다음과 같이 정의됩니다: ALPHA / DIGIT / "-" / "." / "_" / "~"

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

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

URL을 문자열로 변환하여 반환합니다. ` options`을 사용하여 플래그를 전달하면 출력 형식을 사용자 정의할 수 있습니다. ` QUrl::FullyDecoded ` 옵션은 모호한 데이터를 생성할 수 있으므로 이 함수에서는 사용할 수 없습니다.

기본 서식 지정 옵션은 PrettyDecoded 입니다.

FormattingOptions, url(), setUrl()도 참조하십시오 .

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

toString(options)를 사용하여 ` urls ` 목록을 ` QString ` 객체 목록으로 변환합니다.

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

URL을 문자열로 변환하여 반환합니다. ` options`에 플래그를 전달하여 출력 형식을 사용자 정의할 수 있습니다. ` QUrl::FullyDecoded ` 옵션은 모호한 데이터를 생성할 수 있으므로 이 함수에서는 사용할 수 없습니다.

생성된 QString 는 나중에 QUrl 에 다시 전달할 수 있습니다.

toString(options)의 동의어입니다.

setUrl(), FormattingOptions, toEncoded() 및 toString()도 참조하십시오 .

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

URL의 사용자 정보를 반환하며, 사용자 정보가 정의되지 않은 경우에는 빈 문자열을 반환합니다.

이 함수는 모호성이 없는 값을 반환하며, 이 값에는 여전히 퍼센트 인코딩된 문자와 함께 QString 에서 디코딩된 형태로 표현할 수 없는 일부 제어 시퀀스가 포함될 수 있습니다.

options 매개변수는 사용자 정보 구성 요소의 서식 지정 방식을 제어합니다. 이 함수에서는 QUrl::FullyDecoded 값을 사용할 수 없습니다. 완전히 디코딩된 데이터를 얻어야 하는 경우, userName() 및 password()를 각각 호출하십시오.

setUserInfo(), userName(), password(), authority()도 참조하십시오 .

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

URL에 사용자 이름이 정의되어 있으면 이를 반환하고, 그렇지 않으면 빈 문자열을 반환합니다.

options 인수는 사용자 이름 구성 요소의 형식 지정 방식을 제어합니다. 모든 값은 모호함이 없는 결과를 생성합니다. QUrl::FullyDecoded 를 사용하면 모든 퍼센트 인코딩된 시퀀스가 디코딩됩니다. 그렇지 않은 경우, QString 에서 디코딩된 형태로 표현할 수 없는 일부 제어 시퀀스에 대해 반환된 값에 퍼센트 인코딩된 시퀀스가 포함될 수 있습니다.

QUrl::FullyDecoded 를 사용할 경우, 표현할 수 없는 시퀀스가 존재하면 데이터 손실이 발생할 수 있습니다. 이 값은 QAuthenticator 설정이나 로그인 협상 등 URL이 아닌 맥락에서 결과를 사용할 때 사용하는 것이 좋습니다.

setUserName() 및 userInfo()도 참조하십시오 .

[noexcept] QUrl &QUrl::operator=(QUrl &&other)

other 를 이 QUrl 인스턴스에 할당합니다.

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

지정된 url 를 이 객체에 할당합니다.

QT_NO_URL_CAST_FROM_STRING 매크로가 정의된 경우 이 연산자를 사용할 수 없습니다.

[noexcept] QUrl &QUrl::operator=(const QUrl &url)

지정된 url 을 이 객체에 할당합니다.

관련 비멤버

[noexcept] bool operator!=(const QUrl &lhs, const QUrl &rhs)

lhs 와 rhs URL이 서로 다를 경우 true 를 반환하고, 그렇지 않으면 false 를 반환합니다.

matches()도 참조하십시오 .

QDataStream &operator<<(QDataStream &out, const QUrl &url)

URL url 을 스트림 out 에 기록하고, 해당 스트림에 대한 참조를 반환합니다.

QDataStream 연산자의 형식항목도 참조하십시오 .

[noexcept] bool operator==(const QUrl &lhs, const QUrl &rhs)

lhs 및 rhs URL이 동일할 경우 true 을 반환하고, 그렇지 않은 경우 false 을 반환합니다.

matches()도 참조하십시오 .

QDataStream &operator>>(QDataStream &in, QUrl &url)

in 스트림에서 URL을 읽어와 url 로 전송하고, 해당 스트림에 대한 참조를 반환합니다.

QDataStream 연산자의 형식도참조하십시오 .

매크로 문서

QT_NO_URL_CAST_FROM_STRING

QString (또는 char *)에서 QUrl 로의 자동 변환을 비활성화합니다.

파일 이름에 QString 를 사용하는 코드가 많고, 네트워크 투명성을 위해 이를 QUrl 로 변환하고자 할 때 이 정의와 함께 코드를 컴파일하는 것이 유용합니다. QUrl 를 사용하는 모든 코드에서, 이 정의는 QUrl::resolved() 호출 누락이나 QString 에서 QUrl 로의 변환과 관련된 기타 오용을 방지하는 데 도움이 될 수 있습니다.

예를 들어, 다음과 같은 코드가 있다면

url = filename; // probably not what you want

다음과 같이 다시 작성할 수 있습니다.

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

QT_NO_CAST_FROM_ASCII도 참조하십시오 .

© 2026 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.