En esta página

QNetworkProxy Class

La clase QNetworkProxy proporciona un proxy de capa de red. Más información...

Encabezado: #include <QNetworkProxy>
CMake: find_package(Qt6 REQUIRED COMPONENTS Network)
target_link_libraries(mytarget PRIVATE Qt6::Network)
qmake: QT += network

Nota: Todas las funciones de esta clase son reentrantes.

Tipos públicos

flags Capabilities
enum Capability { TunnelingCapability, ListeningCapability, UdpTunnelingCapability, CachingCapability, HostNameLookupCapability, …, SctpListeningCapability }
enum ProxyType { NoProxy, DefaultProxy, Socks5Proxy, HttpProxy, HttpCachingProxy, FtpCachingProxy }

Funciones públicas

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

Miembros públicos estáticos

QNetworkProxy applicationProxy()
void setApplicationProxy(const QNetworkProxy &networkProxy)

Descripción detallada

QNetworkProxy proporciona el método para configurar la compatibilidad con el proxy de la capa de red en las clases de red de Qt. Las clases compatibles actualmente son QAbstractSocket, QTcpSocket, QUdpSocket, QTcpServer y QNetworkAccessManager. La compatibilidad con el proxy está diseñada para ser lo más transparente posible. Esto significa que las aplicaciones con capacidades de red que ya hayas escrito deberían ser compatibles automáticamente con el proxy de red utilizando el siguiente código.

QNetworkProxy proxy;
proxy.setType(QNetworkProxy::Socks5Proxy);
proxy.setHostName("proxy.example.com");
proxy.setPort(1080);
proxy.setUser("username");
proxy.setPassword("password");
QNetworkProxy::setApplicationProxy(proxy);

Una alternativa a configurar un proxy para toda la aplicación es especificar el proxy para cada socket individual mediante QAbstractSocket::setProxy() y QTcpServer::setProxy(). De este modo, es posible desactivar el uso de un proxy para sockets específicos utilizando el siguiente código:

serverSocket->setProxy(QNetworkProxy::NoProxy);

El proxy de red no se utiliza si la dirección utilizada en connectToHost(), bind() o listen() es equivalente a QHostAddress::LocalHost o QHostAddress::LocalHostIPv6.

Cada tipo de soporte de proxy tiene ciertas restricciones asociadas. Debes leer atentamente la documentación de ProxyType antes de seleccionar el tipo de proxy que vas a utilizar.

Nota: Los cambios realizados en los sockets actualmente conectados no surten efecto. Si necesitas modificar un socket conectado, debes volver a conectarlo.

SOCKS5

La compatibilidad con SOCKS5 desde Qt 4 se basa en los estándares RFC 1928 y RFC 1929. Los métodos de autenticación admitidos son «sin autenticación» y «autenticación con nombre de usuario y contraseña». Se admiten tanto IPv4 como IPv6. Los nombres de dominio se resuelven a través del servidor SOCKS5 si está activada la opción « QNetworkProxy::HostNameLookupCapability »; de lo contrario, se resuelven localmente y la dirección IP se envía al servidor. Hay varios aspectos que hay que tener en cuenta al utilizar SOCKS5 con « QUdpSocket » y « QTcpServer »:

Con QUdpSocket, una llamada a bind() puede fallar con un error de tiempo de espera. Si se pasa un número de puerto distinto de 0 a bind(), no se garantiza que se utilice el puerto especificado. Utiliza localPort() y localAddress() para obtener la dirección y el número de puerto reales que se están utilizando. Dado que el UDP por proxy pasa por dos conexiones UDP, es más probable que se pierdan paquetes.

Con QTcpServer, una llamada a listen() puede fallar con un error de tiempo de espera. Si se pasa un número de puerto distinto de 0 a listen(), no se garantiza que se utilice el puerto especificado. Utiliza serverPort() y serverAddress() para obtener la dirección y el puerto reales que se utilizan para escuchar conexiones. SOCKS5 solo admite una conexión aceptada por cada llamada a listen(), y es probable que cada llamada dé lugar a que se utilice un serverPort() diferente.

Véase también QAbstractSocket y QTcpServer.

Documentación sobre los tipos de miembro

enum QNetworkProxy::Capability
flags QNetworkProxy::Capabilities

Estas opciones indican las capacidades que admite un servidor proxy determinado.

QNetworkProxy Establece diferentes capacidades por defecto al crear el objeto (consulta QNetworkProxy::ProxyType para ver una lista de los valores por defecto). Sin embargo, es posible modificar las capacidades una vez creado el objeto mediante setCapabilities().

Las capacidades que admite QNetworkProxy son:

ConstanteValorDescripción
QNetworkProxy::TunnelingCapability0x0001Capacidad para abrir conexiones TCP transparentes y tunelizadas con un host remoto. El servidor proxy retransmite la transmisión tal cual de un lado a otro y no realiza almacenamiento en caché.
QNetworkProxy::ListeningCapability0x0002Capacidad para crear un socket de escucha y esperar una conexión TCP entrante desde un host remoto.
QNetworkProxy::UdpTunnelingCapability0x0004Capacidad para retransmitir datagramas UDP a través del servidor proxy hacia y desde un host remoto.
QNetworkProxy::CachingCapability0x0008Capacidad para almacenar en caché el contenido de la transferencia. Esta capacidad es específica de cada protocolo y tipo de proxy. Por ejemplo, los proxies HTTP pueden almacenar en caché el contenido de los datos web transferidos con comandos «GET».
QNetworkProxy::HostNameLookupCapability0x0010Capacidad para realizar la búsqueda de un nombre de host remoto y conectarse a él, en lugar de que sea la aplicación la que tenga que realizar la búsqueda del nombre y solicitar la conexión únicamente a direcciones IP.
QNetworkProxy::SctpTunnelingCapability0x00020Capacidad para abrir conexiones SCTP transparentes y en túnel con un host remoto.
QNetworkProxy::SctpListeningCapability0x00040Capacidad para crear un socket de escucha y esperar una conexión SCTP entrante desde un host remoto.

El tipo «Capabilities» es una definición de tipo (typedef) para QFlags<Capability>. Almacena una combinación OR de valores de Capability.

enum QNetworkProxy::ProxyType

Esta enumeración describe los tipos de proxy de red que ofrece Qt Network.

Hay dos tipos de proxies que Qt reconoce: los proxies transparentes y los proxies de almacenamiento en caché. El primer grupo está formado por proxies que pueden gestionar cualquier transferencia de datos arbitraria, mientras que el segundo solo puede gestionar solicitudes específicas. Los proxies de almacenamiento en caché solo tienen sentido para las clases específicas en las que se pueden utilizar.

ConstanteValorDescripción
QNetworkProxy::NoProxy2No se utiliza ningún proxy
QNetworkProxy::DefaultProxy0El proxy se determina en función del proxy de la aplicación establecido mediante setApplicationProxy()
QNetworkProxy::Socks5Proxy1Socks5 Se utiliza el proxy
QNetworkProxy::HttpProxy3Se utiliza un proxy HTTP transparente
QNetworkProxy::HttpCachingProxy4Se utiliza un proxy solo para las solicitudes HTTP
QNetworkProxy::FtpCachingProxy5Proxy solo para solicitudes FTP

La tabla siguiente enumera los diferentes tipos de proxy y sus capacidades. Dado que cada tipo de proxy tiene capacidades diferentes, es importante comprenderlas antes de elegir un tipo de proxy.

Tipo de proxyDescripciónFuncionalidades predeterminadas
SOCKS 5Proxy genérico para cualquier tipo de conexión. Admite TCP, UDP, la asignación a un puerto (conexiones entrantes) y la autenticación.TunnelingCapability, ListeningCapability, UdpTunnelingCapability, HostNameLookupCapability
HTTPImplementado mediante el comando «CONNECT», solo admite conexiones TCP salientes; admite autenticación.TunnelingCapability, CachingCapability, HostNameLookupCapability
HTTP solo de almacenamiento en cachéImplementado mediante comandos HTTP normales; solo resulta útil en el contexto de las solicitudes HTTP (véase QNetworkAccessManager)CachingCapability, HostNameLookupCapability
FTP de almacenamiento en cachéImplementado mediante un proxy FTP, resulta útil únicamente en el contexto de las solicitudes FTP (véase QNetworkAccessManager)CachingCapability, HostNameLookupCapability

Ten en cuenta también que no debes configurar el proxy predeterminado de la aplicación (setApplicationProxy()) en un proxy que no disponga de la capacidad TunnelingCapability. Si lo haces, QTcpSocket no sabrá cómo establecer conexiones.

Véase también setType(), type(), capabilities() y setCapabilities().

Documentación de funciones miembro

QNetworkProxy::QNetworkProxy()

Crea un objeto `QNetworkProxy` con el tipo ` DefaultProxy `.

El tipo de proxy viene determinado por ` applicationProxy()`, cuyo valor por defecto es ` NoProxy ` o un proxy para todo el sistema, si se ha configurado alguno.

Véase también setType() y setApplicationProxy().

QNetworkProxy::QNetworkProxy(QNetworkProxy::ProxyType type, const QString &hostName = QString(), quint16 port = 0, const QString &user = QString(), const QString &password = QString())

Crea un objeto `QNetworkProxy` con ` type`, ` hostName`, ` port`, ` user ` y ` password`.

Las capacidades predeterminadas para el tipo de proxy type se establecen automáticamente.

Véase también ` capabilities()`.

QNetworkProxy::QNetworkProxy(const QNetworkProxy &other)

Crea una copia de other.

[noexcept] QNetworkProxy::~QNetworkProxy()

Elimina el objeto « QNetworkProxy ».

[static] QNetworkProxy QNetworkProxy::applicationProxy()

Devuelve el proxy de red a nivel de aplicación.

Si un ` QAbstractSocket ` o un ` QTcpSocket ` tiene el tipo ` QNetworkProxy::DefaultProxy `, se utiliza el ` QNetworkProxy ` devuelto por esta función.

Véase también QNetworkProxyFactory, setApplicationProxy(), QAbstractSocket::proxy() y QTcpServer::proxy().

QNetworkProxy::Capabilities QNetworkProxy::capabilities() const

Devuelve las capacidades de este servidor proxy.

Véase también setCapabilities() y type().

bool QNetworkProxy::hasRawHeader(const QByteArray &headerName) const

Devuelve « true » si se está utilizando la cabecera sin procesar « headerName » para este proxy. Devuelve « false » si el proxy no es de tipo « HttpProxy » o « HttpCachingProxy ».

Véase también rawHeader() y setRawHeader().

Devuelve el valor del encabezado de red conocido header si se está utilizando para este proxy. Si no está presente, devuelve QVariant() (es decir, una variante no válida).

Véase también QNetworkRequest::KnownHeaders, rawHeader() y setHeader().

[since 6.8] QHttpHeaders QNetworkProxy::headers() const

Devuelve los encabezados que se han establecido en esta solicitud de red.

Si el proxy no es de tipo « HttpProxy » o « HttpCachingProxy », se devuelve un objeto « QHttpHeaders » creado por defecto.

Esta función se introdujo en Qt 6.8.

Véase también setHeaders().

QString QNetworkProxy::hostName() const

Devuelve el nombre de host del servidor proxy.

Véase también setHostName(), setPort() y port().

bool QNetworkProxy::isCachingProxy() const

Devuelve « true » si este proxy admite la capacidad « QNetworkProxy::CachingCapability ».

En Qt 4.4, esta capacidad estaba vinculada al tipo de proxy, pero a partir de Qt 4.5 es posible eliminar la capacidad de almacenamiento en caché de un proxy llamando a setCapabilities().

Véanse también capabilities(), type() y isTransparentProxy().

bool QNetworkProxy::isTransparentProxy() const

Devuelve « true » si este proxy admite el tunelizado transparente de conexiones TCP. Esto se corresponde con la capacidad « QNetworkProxy::TunnelingCapability ».

En Qt 4.4, esta capacidad estaba vinculada al tipo de proxy, pero a partir de Qt 4.5 es posible eliminar la capacidad de almacenamiento en caché de un proxy llamando a setCapabilities().

Véanse también capabilities(), type() y isCachingProxy().

QString QNetworkProxy::password() const

Devuelve la contraseña utilizada para la autenticación.

Véase también user(), setPassword() y setUser().

quint16 QNetworkProxy::port() const

Devuelve el puerto del host proxy.

Véanse también setHostName(), setPort() y hostName().

QByteArray QNetworkProxy::rawHeader(const QByteArray &headerName) const

Devuelve la forma sin procesar del encabezado headerName. Si no existe dicho encabezado o si el proxy no es de tipo HttpProxy o HttpCachingProxy, se devuelve un QByteArray vacío, que puede resultar indistinguible de un encabezado que sí existe pero que carece de contenido (utiliza hasRawHeader() para comprobar si el encabezado existe o no).

Los encabezados sin procesar se pueden establecer con setRawHeader() o con setHeader().

Véase también header() y setRawHeader().

QList<QByteArray> QNetworkProxy::rawHeaderList() const

Devuelve una lista de todos los encabezados sin procesar que se han configurado en este proxy de red. La lista aparece en el orden en que se configuraron los encabezados.

Si el proxy no es de tipo HttpProxy o HttpCachingProxy, se devuelve una lista vacía QList.

Véanse también hasRawHeader() y rawHeader().

[static] void QNetworkProxy::setApplicationProxy(const QNetworkProxy &networkProxy)

Establece el proxy de red a nivel de aplicación en networkProxy.

Si un QAbstractSocket o un QTcpSocket tiene el tipo QNetworkProxy::DefaultProxy, se utilizará el QNetworkProxy establecido con esta función. Si deseas mayor flexibilidad a la hora de determinar qué proxy se utiliza, utiliza la clase QNetworkProxyFactory.

Establecer un valor de proxy por defecto con esta función anulará la fábrica de proxies de la aplicación configurada con QNetworkProxyFactory::setApplicationProxyFactory y desactivará el uso de un proxy del sistema.

Véanse también QNetworkProxyFactory, applicationProxy(), QAbstractSocket::setProxy() y QTcpServer::setProxy().

void QNetworkProxy::setCapabilities(QNetworkProxy::Capabilities capabilities)

Establece las capacidades de este proxy en capabilities.

Véanse también setType() y capabilities().

void QNetworkProxy::setHeader(QNetworkRequest::KnownHeaders header, const QVariant &value)

Establece el valor del encabezado conocido « header » en « value », anulando cualquier encabezado establecido anteriormente. Esta operación también establece el encabezado HTTP sin procesar equivalente.

Si el proxy no es de tipo HttpProxy o HttpCachingProxy, esto no tiene ningún efecto.

Véase también QNetworkRequest::KnownHeaders, setRawHeader() y header().

[since 6.8] void QNetworkProxy::setHeaders(QHttpHeaders &&newHeaders)

Establece « newHeaders » como encabezados en esta solicitud de red, sustituyendo cualquier encabezado establecido anteriormente.

Si algunos encabezados coinciden con los encabezados conocidos, se analizarán los valores y también se establecerá el formulario analizado correspondiente.

Si el proxy no es de tipo HttpProxy o HttpCachingProxy, esto no tendrá ningún efecto.

Esta función se introdujo en Qt 6.8.

Véase también headers() y QNetworkRequest::KnownHeaders.

[since 6.8] void QNetworkProxy::setHeaders(const QHttpHeaders &newHeaders)

Esta es una función sobrecargada.

Esta función se introdujo en Qt 6.8.

void QNetworkProxy::setHostName(const QString &hostName)

Establece el nombre de host del servidor proxy como hostName.

Véase también hostName(), setPort() y port().

void QNetworkProxy::setPassword(const QString &password)

Establece la contraseña para la autenticación del proxy como password.

Véase también user(), setUser() y password().

void QNetworkProxy::setPort(quint16 port)

Establece el puerto del servidor proxy en port.

Véase también hostName(), setHostName() y port().

void QNetworkProxy::setRawHeader(const QByteArray &headerName, const QByteArray &headerValue)

Establece el valor de la cabecera « headerName » en « headerValue ». Si « headerName » corresponde a una cabecera conocida (véase QNetworkRequest::KnownHeaders), se analizará el formato sin procesar y se establecerá también la cabecera «procesada» correspondiente.

Por ejemplo:

request.setRawHeader(QByteArray("Last-Modified"), QByteArray("Sun, 06 Nov 1994 08:49:37 GMT"));

también establecerá el encabezado conocido LastModifiedHeader como el objeto QDateTime de la fecha analizada.

Nota: Establecer el mismo encabezado dos veces anula la configuración anterior. Para conseguir el comportamiento de varios encabezados HTTP con el mismo nombre, debes concatenar los dos valores, separándolos con una coma («,») y establecer un único encabezado sin procesar.

Si el proxy no es de tipo HttpProxy o HttpCachingProxy, esto no tiene ningún efecto.

Véase también QNetworkRequest::KnownHeaders, setHeader(), hasRawHeader() y rawHeader().

void QNetworkProxy::setType(QNetworkProxy::ProxyType type)

Establece el tipo de proxy de esta instancia como « type ».

Ten en cuenta que cambiar el tipo de un proxy no modifica el conjunto de capacidades que posee este objeto « QNetworkProxy » si se ha establecido alguna capacidad mediante la función « setCapabilities()».

Véanse también type() y setCapabilities().

void QNetworkProxy::setUser(const QString &user)

Establece el nombre de usuario para la autenticación mediante proxy como user.

Véase también user(), setPassword() y password().

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

Sustituye esta instancia de proxy de red por other. Esta operación es muy rápida y nunca falla.

QNetworkProxy::ProxyType QNetworkProxy::type() const

Devuelve el tipo de proxy de esta instancia.

Véase también setType().

QString QNetworkProxy::user() const

Devuelve el nombre de usuario utilizado para la autenticación.

Véase también setUser(), setPassword() y password().

bool QNetworkProxy::operator!=(const QNetworkProxy &other) const

Compara el valor de este proxy de red con other y devuelve true si no coinciden.

QNetworkProxy &QNetworkProxy::operator=(const QNetworkProxy &other)

Asigna el valor del proxy de red other a este proxy de red.

bool QNetworkProxy::operator==(const QNetworkProxy &other) const

Compara el valor de este proxy de red con other y devuelve true si coinciden (mismo tipo de proxy, servidor, nombre de usuario y contraseña).

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