QNetworkProxy Class
QNetworkProxy 클래스는 네트워크 계층 프록시를 제공합니다. 더 보기...
| 헤더: | #include <QNetworkProxy> |
| CMake: | find_package(Qt6 REQUIRED COMPONENTS Network) target_link_libraries(mytarget PRIVATE Qt6::Network) |
| qmake: | QT += network |
- 상속된 멤버를 포함한 모든 멤버 목록
- QNetworkProxy는 네트워크 프로그래밍 API 및 암시적 공유 클래스의 일부입니다.
참고: 이 클래스의 모든 함수는 재진입 가능합니다.
공개 유형
| flags | Capabilities |
| enum | Capability { TunnelingCapability, ListeningCapability, UdpTunnelingCapability, CachingCapability, HostNameLookupCapability, …, SctpListeningCapability } |
| enum | ProxyType { NoProxy, DefaultProxy, Socks5Proxy, HttpProxy, HttpCachingProxy, FtpCachingProxy } |
공개 함수
| QNetworkProxy() | |
| QNetworkProxy(QNetworkProxy::ProxyType type, const QString &hostName = QString(), quint16 port = 0, const QString &user = QString(), const QString &password = QString()) | |
| QNetworkProxy(const QNetworkProxy &other) | |
| ~QNetworkProxy() | |
| QNetworkProxy::Capabilities | capabilities() const |
| bool | hasRawHeader(const QByteArray &headerName) const |
| QVariant | header(QNetworkRequest::KnownHeaders header) const |
(since 6.8) QHttpHeaders | headers() const |
| QString | hostName() const |
| bool | isCachingProxy() const |
| bool | isTransparentProxy() const |
| QString | password() const |
| quint16 | port() const |
| QByteArray | rawHeader(const QByteArray &headerName) const |
| QList<QByteArray> | rawHeaderList() const |
| void | setCapabilities(QNetworkProxy::Capabilities capabilities) |
| void | setHeader(QNetworkRequest::KnownHeaders header, const QVariant &value) |
(since 6.8) void | setHeaders(QHttpHeaders &&newHeaders) |
(since 6.8) void | setHeaders(const QHttpHeaders &newHeaders) |
| void | setHostName(const QString &hostName) |
| void | setPassword(const QString &password) |
| void | setPort(quint16 port) |
| void | setRawHeader(const QByteArray &headerName, const QByteArray &headerValue) |
| void | setType(QNetworkProxy::ProxyType type) |
| void | setUser(const QString &user) |
| void | swap(QNetworkProxy &other) |
| QNetworkProxy::ProxyType | type() const |
| QString | user() const |
| bool | operator!=(const QNetworkProxy &other) const |
| QNetworkProxy & | operator=(const QNetworkProxy &other) |
| bool | operator==(const QNetworkProxy &other) const |
정적 공용 멤버
| QNetworkProxy | applicationProxy() |
| void | setApplicationProxy(const QNetworkProxy &networkProxy) |
상세 설명
QNetworkProxy는 Qt Network 클래스에 네트워크 계층 프록시 지원을 구성하는 메서드를 제공합니다. 현재 지원되는 클래스는 QAbstractSocket, QTcpSocket, QUdpSocket, QTcpServer 및 QNetworkAccessManager 입니다. 프록시 지원은 가능한 한 투명하게 설계되었습니다. 즉, 사용자가 작성한 기존의 네트워크 지원 애플리케이션은 다음 코드를 사용하여 네트워크 프록시를 자동으로 지원하게 됩니다.
QNetworkProxy proxy;
proxy.setType(QNetworkProxy::Socks5Proxy);
proxy.setHostName("proxy.example.com");
proxy.setPort(1080);
proxy.setUser("username");
proxy.setPassword("password");
QNetworkProxy::setApplicationProxy(proxy);애플리케이션 전체에 프록시를 설정하는 대신, QAbstractSocket::setProxy() 및 QTcpServer::setProxy()를 사용하여 개별 소켓에 대한 프록시를 지정할 수도 있습니다. 이러한 방식으로 다음 코드를 사용하여 특정 소켓에 대한 프록시 사용을 비활성화할 수 있습니다:
serverSocket->setProxy(QNetworkProxy::NoProxy);connectToHost(), bind() 또는 listen()에서 사용된 주소가 QHostAddress::LocalHost 또는 QHostAddress::LocalHostIPv6 과 동일할 경우 네트워크 프록시는 사용되지 않습니다.
각 프록시 지원 유형에는 특정 제한 사항이 따릅니다. 사용할 프록시 유형을 선택하기 전에 ProxyType 문서를 주의 깊게 읽어보시기 바랍니다.
참고: 현재 연결된 소켓에 대한변경 사항은 적용되지 않습니다. 연결된 소켓을 변경해야 하는 경우, 소켓을 다시 연결해야 합니다.
SOCKS5
Qt 4부터 지원되는 SOCKS5는 RFC 1928 및 RFC 1929를 기반으로 합니다. 지원되는 인증 방식은 인증 없음과 사용자 이름/비밀번호 인증입니다. IPv4와 IPv6가 모두 지원됩니다. QNetworkProxy::HostNameLookupCapability 가 활성화된 경우 도메인 이름은 SOCKS5 서버를 통해 확인되며, 그렇지 않은 경우 로컬에서 확인된 후 IP 주소가 서버로 전송됩니다. SOCKS5를 QUdpSocket 및 QTcpServer 와 함께 사용할 때 유의해야 할 사항이 몇 가지 있습니다:
QUdpSocket 를 사용할 경우, bind() 호출이 타임아웃 오류로 실패할 수 있습니다. bind()에 0 이외의 포트 번호가 전달되더라도, 지정된 포트가 실제로 사용될 것이라고 보장할 수 없습니다. localPort() 및 localAddress()를 사용하여 실제로 사용 중인 주소와 포트 번호를 확인하십시오. 프록시된 UDP는 두 개의 UDP 연결을 거치므로 패킷이 손실될 가능성이 더 높습니다.
QTcpServer 를 사용할 경우, ` listen()` 호출이 타임아웃 오류로 실패할 수 있습니다. ` listen()`에 0이 아닌 포트 번호를 전달하면, 지정된 포트가 사용될 것이라고 보장되지 않습니다. 연결 수신에 사용되는 실제 주소와 포트를 확인하려면 ` serverPort()` 및 ` serverAddress()`를 사용하십시오. SOCKS5는 listen() 호출당 하나의 수락된 연결만 지원하며, 호출할 때마다 서로 다른 serverPort()가 사용될 가능성이 높습니다.
QAbstractSocket 및 QTcpServer도 참조하십시오 .
멤버 유형 문서
enum QNetworkProxy::Capability
flags QNetworkProxy::Capabilities
이 플래그들은 특정 프록시 서버가 지원하는 기능을 나타냅니다.
QNetworkProxy 객체가 생성될 때 기본적으로 다양한 기능을 설정합니다(기본값 목록은 QNetworkProxy::ProxyType 참조). 그러나 setCapabilities()를 사용하여 객체가 생성된 후에도 기능을 변경할 수 있습니다.
QNetworkProxy 가 지원하는 기능은 다음과 같습니다.
| 상수 | 값 | 설명 |
|---|---|---|
QNetworkProxy::TunnelingCapability | 0x0001 | 원격 호스트에 대한 투명 터널링 TCP 연결을 열 수 있는 기능입니다. 프록시 서버는 전송 내용을 한쪽에서 다른 쪽으로 그대로 전달하며 캐싱을 수행하지 않습니다. |
QNetworkProxy::ListeningCapability | 0x0002 | 수신 소켓을 생성하고 원격 호스트로부터 들어오는 TCP 연결을 대기할 수 있는 기능입니다. |
QNetworkProxy::UdpTunnelingCapability | 0x0004 | 프록시 서버를 통해 원격 호스트와 UDP 데이터그램을 주고받을 수 있는 기능. |
QNetworkProxy::CachingCapability | 0x0008 | 전송 내용을 캐싱할 수 있는 기능. 이 기능은 각 프로토콜 및 프록시 유형에 따라 다릅니다. 예를 들어, HTTP 프록시는 "GET" 명령으로 전송된 웹 데이터의 내용을 캐싱할 수 있습니다. |
QNetworkProxy::HostNameLookupCapability | 0x0010 | 애플리케이션이 이름 조회를 수행하고 IP 주소에 대한 연결만 요청하도록 요구하는 것과는 달리, 원격 호스트 이름을 조회하고 해당 호스트에 연결할 수 있는 기능. |
QNetworkProxy::SctpTunnelingCapability | 0x00020 | 원격 호스트에 대한 투명한 터널링된 SCTP 연결을 열 수 있는 기능. |
QNetworkProxy::SctpListeningCapability | 0x00040 | 수신 대기 소켓을 생성하고 원격 호스트로부터 들어오는 SCTP 연결을 대기할 수 있는 기능. |
Capabilities 유형은 QFlags<Capability>에 대한 typedef입니다. 이 유형은 Capability 값들의 OR 조합을 저장합니다.
enum QNetworkProxy::ProxyType
이 열거형은 Qt Network에서 제공하는 네트워크 프록시 유형을 설명합니다.
Qt에서 인식하는 프록시에는 투명 프록시와 캐싱 프록시, 두 가지 유형이 있습니다. 첫 번째 그룹은 임의의 데이터 전송을 처리할 수 있는 프록시로 구성되는 반면, 두 번째 그룹은 특정 요청만 처리할 수 있습니다. 캐싱 프록시는 이를 사용할 수 있는 특정 클래스에서만 의미가 있습니다.
| 상수 | 값 | 설명 |
|---|---|---|
QNetworkProxy::NoProxy | 2 | 프록시 처리 없음 |
QNetworkProxy::DefaultProxy | 0 | setApplicationProxy()를 사용하여 설정된 애플리케이션 프록시에 따라 프록시가 결정됩니다 |
QNetworkProxy::Socks5Proxy | 1 | Socks5 프록시링이 사용됩니다 |
QNetworkProxy::HttpProxy | 3 | HTTP 투명 프록시 기능이 사용됩니다 |
QNetworkProxy::HttpCachingProxy | 4 | HTTP 요청에 대해서만 프록시 처리 |
QNetworkProxy::FtpCachingProxy | 5 | FTP 요청에 대해서만 프록시 적용 |
아래 표에는 다양한 프록시 유형과 각 유형의 기능이 나열되어 있습니다. 프록시 유형마다 기능이 다르므로, 프록시 유형을 선택하기 전에 이를 이해하는 것이 중요합니다.
| 프록시 유형 | 설명 | 기본 기능 |
|---|---|---|
| SOCKS 5 | 모든 종류의 연결에 사용할 수 있는 범용 프록시입니다. TCP, UDP, 포트 바인딩(수신 연결) 및 인증을 지원합니다. | TunnelingCapability, ListeningCapability, UdpTunnelingCapability, HostNameLookupCapability |
| HTTP | "CONNECT" 명령을 사용하여 구현되며, 발신 TCP 연결만 지원합니다. 인증을 지원합니다. | TunnelingCapability, CachingCapability, HostNameLookupCapability |
| 캐싱 전용 HTTP | 일반 HTTP 명령을 사용하여 구현되며, HTTP 요청의 맥락에서만 유용합니다( QNetworkAccessManager 참조) | CachingCapability, HostNameLookupCapability |
| 캐싱 전용 FTP | FTP 프록시를 사용하여 구현되며, FTP 요청의 맥락에서만 유용합니다( QNetworkAccessManager 참조). | CachingCapability, HostNameLookupCapability |
또한 애플리케이션 기본 프록시(setApplicationProxy())를 TunnelingCapability 기능을 지원하지 않는 프록시로 설정해서는 안 됩니다. 그렇게 설정할 경우, QTcpSocket 는 연결을 여는 방법을 알 수 없게 됩니다.
setType(), type(), capabilities(), setCapabilities()항목도 참조하십시오 .
멤버 함수 문서
QNetworkProxy::QNetworkProxy()
DefaultProxy 유형의 QNetworkProxy를 생성합니다.
프록시 유형은 ` applicationProxy()`에 의해 결정되며, 기본값은 ` NoProxy `이거나 시스템 전체 프록시가 설정된 경우 해당 프록시입니다.
setType() 및 setApplicationProxy()도 참조하십시오 .
QNetworkProxy::QNetworkProxy(QNetworkProxy::ProxyType type, const QString &hostName = QString(), quint16 port = 0, const QString &user = QString(), const QString &password = QString())
type, hostName, port, user 및 password 를 사용하여 QNetworkProxy를 생성합니다.
type 프록시 유형에 대한 기본 기능은 자동으로 설정됩니다.
capabilities()도 참조하십시오 .
QNetworkProxy::QNetworkProxy(const QNetworkProxy &other)
other 의 복사본을 생성합니다.
[noexcept] QNetworkProxy::~QNetworkProxy()
QNetworkProxy 객체를 삭제합니다.
[static] QNetworkProxy QNetworkProxy::applicationProxy()
애플리케이션 수준의 네트워크 프록시 기능을 반환합니다.
QAbstractSocket 또는 QTcpSocket 의 유형이 QNetworkProxy::DefaultProxy 인 경우, 이 함수가 반환하는 QNetworkProxy 가 사용됩니다.
QNetworkProxyFactory, setApplicationProxy(), QAbstractSocket::proxy(), QTcpServer::proxy()도 참조하십시오 .
QNetworkProxy::Capabilities QNetworkProxy::capabilities() const
이 프록시 서버의 기능을 반환합니다.
setCapabilities() 및 type()도 참조하십시오 .
bool QNetworkProxy::hasRawHeader(const QByteArray &headerName) const
이 프록시에 대해 원시 헤더 ` headerName `가 사용 중인 경우 ` true `를 반환합니다. 프록시가 ` HttpProxy ` 또는 ` HttpCachingProxy` 유형이 아닌 경우 ` false `를 반환합니다.
rawHeader() 및 setRawHeader()도 참조하십시오 .
QVariant QNetworkProxy::header(QNetworkRequest::KnownHeaders header) const
이 프록시에서 사용 중인 알려진 네트워크 헤더 header 의 값을 반환합니다. 해당 헤더가 없는 경우, QVariant() (즉, 유효하지 않은 변형)를 반환합니다.
QNetworkRequest::KnownHeaders, rawHeader() 및 setHeader()도 참조하십시오 .
[since 6.8] QHttpHeaders QNetworkProxy::headers() const
이 네트워크 요청에 설정된 헤더를 반환합니다.
프록시가 ` HttpProxy ` 또는 ` HttpCachingProxy` 유형이 아닌 경우, 기본 생성된 ` QHttpHeaders `가 반환됩니다.
이 함수는 Qt 6.8에서 도입되었습니다.
setHeaders()도 참조하십시오 .
QString QNetworkProxy::hostName() const
프록시 호스트의 호스트 이름을 반환합니다.
setHostName(), setPort() 및 port()도 참조하십시오 .
bool QNetworkProxy::isCachingProxy() const
이 프록시가 QNetworkProxy::CachingCapability 기능을 지원하는 경우 true 를 반환합니다.
Qt 4.4에서는 이 기능이 프록시 유형에 고정되어 있었으나, Qt 4.5부터는 setCapabilities()를 호출하여 프록시에서 캐싱 기능을 제거할 수 있습니다.
capabilities(), type(), isTransparentProxy()도 참조하십시오 .
bool QNetworkProxy::isTransparentProxy() const
이 프록시가 TCP 연결의 투명 터널링을 지원하는 경우 ` true `를 반환합니다. 이는 ` QNetworkProxy::TunnelingCapability ` 기능과 일치합니다.
Qt 4.4에서는 이 기능이 프록시 유형에 연동되어 있었으나, Qt 4.5부터는 setCapabilities()를 호출하여 프록시에서 캐싱 기능을 제거할 수 있습니다.
capabilities(), type(), isCachingProxy()도 참조하십시오 .
QString QNetworkProxy::password() const
인증에 사용된 비밀번호를 반환합니다.
user(), setPassword() 및 setUser()도 참조하십시오 .
quint16 QNetworkProxy::port() const
프록시 호스트의 포트를 반환합니다.
setHostName(), setPort(), hostName()도 참조하십시오 .
QByteArray QNetworkProxy::rawHeader(const QByteArray &headerName) const
headerName 헤더의 원시 형식을 반환합니다. 해당 헤더가 없거나 프록시가 HttpProxy 또는 HttpCachingProxy 유형이 아닌 경우, 빈 QByteArray 가 반환되는데, 이는 존재하지만 내용이 없는 헤더와 구별되지 않을 수 있습니다(헤더의 존재 여부를 확인하려면 hasRawHeader()를 사용하십시오).
생 헤더는 setRawHeader() 또는 setHeader()을 사용하여 설정할 수 있습니다.
header() 및 setRawHeader()도 참조하십시오 .
QList<QByteArray> QNetworkProxy::rawHeaderList() const
이 네트워크 프록시에 설정된 모든 원시 헤더의 목록을 반환합니다. 목록은 헤더가 설정된 순서대로 정렬됩니다.
프록시가 HttpProxy 또는 HttpCachingProxy 유형이 아닌 경우, 빈 QList 가 반환됩니다.
hasRawHeader() 및 rawHeader()도 참조하십시오 .
[static] void QNetworkProxy::setApplicationProxy(const QNetworkProxy &networkProxy)
애플리케이션 수준의 네트워크 프록시 설정을 ‘ networkProxy ’로 설정합니다.
QAbstractSocket 또는 QTcpSocket 의 유형이 QNetworkProxy::DefaultProxy 인 경우, 이 함수로 설정된 QNetworkProxy 가 사용됩니다. 사용할 프록시를 결정하는 데 더 많은 유연성을 원한다면 QNetworkProxyFactory 클래스를 사용하십시오.
이 함수를 사용하여 기본 프록시 값을 설정하면 QNetworkProxyFactory::setApplicationProxyFactory 로 설정된 애플리케이션 프록시 팩토리가 재정의되고, 시스템 프록시의 사용이 비활성화됩니다.
QNetworkProxyFactory, applicationProxy(), QAbstractSocket::setProxy(), QTcpServer::setProxy()도 참조하십시오 .
void QNetworkProxy::setCapabilities(QNetworkProxy::Capabilities capabilities)
이 프록시의 기능을 capabilities 로 설정합니다.
setType() 및 capabilities()도 참조하십시오 .
void QNetworkProxy::setHeader(QNetworkRequest::KnownHeaders header, const QVariant &value)
' header ' 헤더의 값을 ' value'로 설정하며, 이전에 설정된 헤더는 모두 덮어씁니다. 이 작업은 이에 상응하는 원시 HTTP 헤더도 함께 설정합니다.
프록시가 HttpProxy 또는 HttpCachingProxy 유형이 아닌 경우, 이 작업은 아무런 영향을 미치지 않습니다.
QNetworkRequest::KnownHeaders, setRawHeader(), header()도 참조하십시오 .
[since 6.8] void QNetworkProxy::setHeaders(QHttpHeaders &&newHeaders)
이 네트워크 요청의 헤더로 newHeaders 를 설정하며, 이전에 설정된 헤더는 모두 덮어씁니다.
일부 헤더가 알려진 헤더와 일치하는 경우, 해당 값이 파싱되며 파싱된 결과도 함께 설정됩니다.
프록시가 HttpProxy 또는 HttpCachingProxy 유형이 아닌 경우, 이 함수는 아무런 효과도 미치지 않습니다.
이 함수는 Qt 6.8에서 도입되었습니다.
headers() 및 QNetworkRequest::KnownHeaders도 참조하십시오 .
[since 6.8] void QNetworkProxy::setHeaders(const QHttpHeaders &newHeaders)
이 함수는 오버로드된 함수입니다.
이 함수는 Qt 6.8에서 도입되었습니다.
void QNetworkProxy::setHostName(const QString &hostName)
프록시 호스트의 호스트 이름을 hostName 로 설정합니다.
hostName(), setPort() 및 port()도 참조하십시오 .
void QNetworkProxy::setPassword(const QString &password)
프록시 인증에 사용할 비밀번호를 password 로 설정합니다.
user(), setUser(), password()도 참조하십시오 .
void QNetworkProxy::setPort(quint16 port)
프록시 호스트의 포트를 port 로 설정합니다.
hostName(), setHostName() 및 port()도 참조하십시오 .
void QNetworkProxy::setRawHeader(const QByteArray &headerName, const QByteArray &headerValue)
headerName 헤더의 값을 headerValue 로 설정합니다. headerName 가 알려진 헤더( QNetworkRequest::KnownHeaders 참조)에 해당할 경우, 원시 형식이 파싱되고 이에 상응하는 “가공된” 헤더도 함께 설정됩니다.
예를 들어:
request.setRawHeader(QByteArray("Last-Modified"), QByteArray("Sun, 06 Nov 1994 08:49:37 GMT"));이 경우 알려진 헤더인 LastModifiedHeader도 구문 분석된 날짜의 QDateTime 객체로 설정됩니다.
참고: 동일한 헤더를 두 번설정하면 이전 설정이 덮어쓰입니다. 동일한 이름의 여러 HTTP 헤더 동작을 구현하려면 두 값을 쉼표(",")로 구분하여 연결한 후, 하나의 원시 헤더로 설정해야 합니다.
프록시가 HttpProxy 또는 HttpCachingProxy 유형이 아닌 경우, 이 설정은 효과가 없습니다.
QNetworkRequest::KnownHeaders, setHeader(), hasRawHeader() 및 rawHeader()도 참조하십시오 .
void QNetworkProxy::setType(QNetworkProxy::ProxyType type)
이 인스턴스의 프록시 유형을 type 로 설정합니다.
setCapabilities()를 통해 기능이 설정된 경우, 프록시 유형을 변경하더라도 이 QNetworkProxy 객체가 보유한 기능 집합은 변경되지 않는다는 점에 유의하십시오.
type() 및 setCapabilities()도 참조하십시오 .
void QNetworkProxy::setUser(const QString &user)
프록시 인증에 사용할 사용자 이름을 user 로 설정합니다.
user(), setPassword() 및 password()도 참조하십시오 .
[noexcept] void QNetworkProxy::swap(QNetworkProxy &other)
이 네트워크 프록시 인스턴스를 other 로 교체합니다. 이 작업은 매우 빠르게 진행되며 절대 실패하지 않습니다.
QNetworkProxy::ProxyType QNetworkProxy::type() const
이 인스턴스의 프록시 유형을 반환합니다.
setType()도 참조하십시오 .
QString QNetworkProxy::user() const
인증에 사용된 사용자 이름을 반환합니다.
setUser(), setPassword() 및 password()도 참조하십시오 .
bool QNetworkProxy::operator!=(const QNetworkProxy &other) const
이 네트워크 프록시의 값을 other 와 비교하고, 둘이 다를 경우 true 를 반환합니다.
QNetworkProxy &QNetworkProxy::operator=(const QNetworkProxy &other)
이 네트워크 프록시에 네트워크 프록시 other 의 값을 할당합니다.
bool QNetworkProxy::operator==(const QNetworkProxy &other) const
이 네트워크 프록시의 값을 other 와 비교하여, 두 값이 동일할 경우(프록시 유형, 서버, 사용자 이름 및 비밀번호가 모두 일치할 경우) true 를 반환합니다.
© 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.
