src/network/kernel/qnetworkproxy.cpp

   1 /****************************************************************************
   2 **
   3 ** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
   4 ** Contact: http://www.qt-project.org/
   5 **
   6 ** This file is part of the QtNetwork module of the Qt Toolkit.
   7 **
   8 ** $QT_BEGIN_LICENSE:LGPL$
   9 ** GNU Lesser General Public License Usage
  10 ** This file may be used under the terms of the GNU Lesser General Public
  11 ** License version 2.1 as published by the Free Software Foundation and
  12 ** appearing in the file LICENSE.LGPL included in the packaging of this
  13 ** file. Please review the following information to ensure the GNU Lesser
  14 ** General Public License version 2.1 requirements will be met:
  15 ** http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
  16 **
  17 ** In addition, as a special exception, Nokia gives you certain additional
  18 ** rights. These rights are described in the Nokia Qt LGPL Exception
  19 ** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
  20 **
  21 ** GNU General Public License Usage
  22 ** Alternatively, this file may be used under the terms of the GNU General
  23 ** Public License version 3.0 as published by the Free Software Foundation
  24 ** and appearing in the file LICENSE.GPL included in the packaging of this
  25 ** file. Please review the following information to ensure the GNU General
  26 ** Public License version 3.0 requirements will be met:
  27 ** http://www.gnu.org/copyleft/gpl.html.
  28 **
  29 ** Other Usage
  30 ** Alternatively, this file may be used in accordance with the terms and
  31 ** conditions contained in a signed written agreement between you and Nokia.
  32 **
  33 **
  34 **
  35 **
  36 **
  37 **
  38 ** $QT_END_LICENSE$
  39 **
  40 ****************************************************************************/
  41
  42
  43 /*!
  44     \class QNetworkProxy
  45
  46     \since 4.1
  47
  48     \brief The QNetworkProxy class provides a network layer proxy.
  49
  50     \reentrant
  51     \ingroup network
  52     \inmodule QtNetwork
  53
  54     QNetworkProxy provides the method for configuring network layer
  55     proxy support to the Qt network classes. The currently supported
  56     classes are QAbstractSocket, QTcpSocket, QUdpSocket, QTcpServer
  57     and QNetworkAccessManager. The proxy support is designed to
  58     be as transparent as possible. This means that existing
  59     network-enabled applications that you have written should
  60     automatically support network proxy using the following code.
  61
  62     \snippet doc/src/snippets/code/src_network_kernel_qnetworkproxy.cpp 0
  63
  64     An alternative to setting an application wide proxy is to specify
  65     the proxy for individual sockets using QAbstractSocket::setProxy()
  66     and QTcpServer::setProxy(). In this way, it is possible to disable
  67     the use of a proxy for specific sockets using the following code:
  68
  69     \snippet doc/src/snippets/code/src_network_kernel_qnetworkproxy.cpp 1
  70
  71     Network proxy is not used if the address used in \l
  72     {QAbstractSocket::connectToHost()}{connectToHost()}, \l
  73     {QUdpSocket::bind()}{bind()} or \l
  74     {QTcpServer::listen()}{listen()} is equivalent to
  75     QHostAddress::LocalHost or QHostAddress::LocalHostIPv6.
  76
  77     Each type of proxy support has certain restrictions associated with it.
  78     You should read the \l{ProxyType} documentation carefully before
  79     selecting a proxy type to use.
  80
  81     \note Changes made to currently connected sockets do not take effect.
  82     If you need to change a connected socket, you should reconnect it.
  83
  84     \section1 SOCKS5
  85
  86     The SOCKS5 support in Qt 4 is based on \l{RFC 1928} and \l{RFC 1929}.
  87     The supported authentication methods are no authentication and
  88     username/password authentication.  Both IPv4 and IPv6 are
  89     supported. Domain names are resolved through the SOCKS5 server if
  90     the QNetworkProxy::HostNameLookupCapability is enabled, otherwise
  91     they are resolved locally and the IP address is sent to the
  92     server. There are several things to remember when using SOCKS5
  93     with QUdpSocket and QTcpServer:
  94
  95     With QUdpSocket, a call to \l {QUdpSocket::bind()}{bind()} may fail
  96     with a timeout error. If a port number other than 0 is passed to
  97     \l {QUdpSocket::bind()}{bind()}, it is not guaranteed that it is the
  98     specified port that will be used.
  99     Use \l{QUdpSocket::localPort()}{localPort()} and
 100     \l{QUdpSocket::localAddress()}{localAddress()} to get the actual
 101     address and port number in use. Because proxied UDP goes through
 102     two UDP connections, it is more likely that packets will be dropped.
 103
 104     With QTcpServer a call to \l{QTcpServer::listen()}{listen()} may
 105     fail with a timeout error. If a port number other than 0 is passed
 106     to \l{QTcpServer::listen()}{listen()}, then it is not guaranteed
 107     that it is the specified port that will be used.
 108     Use \l{QTcpServer::serverPort()}{serverPort()} and
 109     \l{QTcpServer::serverAddress()}{serverAddress()} to get the actual
 110     address and port used to listen for connections. SOCKS5 only supports
 111     one accepted connection per call to \l{QTcpServer::listen()}{listen()},
 112     and each call is likely to result in a different
 113     \l{QTcpServer::serverPort()}{serverPort()} being used.
 114
 115     \sa QAbstractSocket, QTcpServer
 116 */
 117
 118 /*!
 119     \enum QNetworkProxy::ProxyType
 120
 121     This enum describes the types of network proxying provided in Qt.
 122
 123     There are two types of proxies that Qt understands:
 124     transparent proxies and caching proxies. The first group consists
 125     of proxies that can handle any arbitrary data transfer, while the
 126     second can only handle specific requests. The caching proxies only
 127     make sense for the specific classes where they can be used.
 128
 129     \value NoProxy No proxying is used
 130     \value DefaultProxy Proxy is determined based on the application proxy set using setApplicationProxy()
 131     \value Socks5Proxy \l Socks5 proxying is used
 132     \value HttpProxy HTTP transparent proxying is used
 133     \value HttpCachingProxy Proxying for HTTP requests only
 134     \value FtpCachingProxy Proxying for FTP requests only
 135
 136     The table below lists different proxy types and their
 137     capabilities. Since each proxy type has different capabilities, it
 138     is important to understand them before choosing a proxy type.
 139
 140     \table
 141     \header
 142         \o Proxy type
 143         \o Description
 144         \o Default capabilities
 145
 146     \row
 147         \o SOCKS 5
 148         \o Generic proxy for any kind of connection. Supports TCP,
 149            UDP, binding to a port (incoming connections) and
 150            authentication.
 151         \o TunnelingCapability, ListeningCapability,
 152            UdpTunnelingCapability, HostNameLookupCapability
 153
 154     \row
 155         \o HTTP
 156         \o Implemented using the "CONNECT" command, supports only
 157            outgoing TCP connections; supports authentication.
 158         \o TunnelingCapability, CachingCapability, HostNameLookupCapability
 159
 160     \row
 161         \o Caching-only HTTP
 162         \o Implemented using normal HTTP commands, it is useful only
 163            in the context of HTTP requests (see QNetworkAccessManager)
 164         \o CachingCapability, HostNameLookupCapability
 165
 166     \row
 167         \o Caching FTP
 168         \o Implemented using an FTP proxy, it is useful only in the
 169            context of FTP requests (see QNetworkAccessManager)
 170         \o CachingCapability, HostNameLookupCapability
 171
 172     \endtable
 173
 174     Also note that you shouldn't set the application default proxy
 175     (setApplicationProxy()) to a proxy that doesn't have the
 176     TunnelingCapability capability. If you do, QTcpSocket will not
 177     know how to open connections.
 178
 179     \sa setType(), type(), capabilities(), setCapabilities()
 180 */
 181
 182 /*!
 183     \enum QNetworkProxy::Capability
 184     \since 4.5
 185
 186     These flags indicate the capabilities that a given proxy server
 187     supports.
 188
 189     QNetworkProxy sets different capabilities by default when the
 190     object is created (see QNetworkProxy::ProxyType for a list of the
 191     defaults). However, it is possible to change the capabitilies
 192     after the object has been created with setCapabilities().
 193
 194     The capabilities that QNetworkProxy supports are:
 195
 196     \value TunnelingCapability Ability to open transparent, tunneled
 197     TCP connections to a remote host. The proxy server relays the
 198     transmission verbatim from one side to the other and does no
 199     caching.
 200
 201     \value ListeningCapability Ability to create a listening socket
 202     and wait for an incoming TCP connection from a remote host.
 203
 204     \value UdpTunnelingCapability Ability to relay UDP datagrams via
 205     the proxy server to and from a remote host.
 206
 207     \value CachingCapability Ability to cache the contents of the
 208     transfer. This capability is specific to each protocol and proxy
 209     type. For example, HTTP proxies can cache the contents of web data
 210     transferred with "GET" commands.
 211
 212     \value HostNameLookupCapability Ability to connect to perform the
 213     lookup on a remote host name and connect to it, as opposed to
 214     requiring the application to perform the name lookup and request
 215     connection to IP addresses only.
 216 */
 217
 218 #include "qnetworkproxy.h"
 219
 220 #ifndef QT_NO_NETWORKPROXY
 221
 222 #include "private/qnetworkproxy_p.h"
 223 #include "private/qnetworkrequest_p.h"
 224 #include "private/qsocks5socketengine_p.h"
 225 #include "private/qhttpsocketengine_p.h"
 226 #include "qauthenticator.h"
 227 #include "qhash.h"
 228 #include "qmutex.h"
 229 #include "qurl.h"
 230
 231 #ifndef QT_NO_BEARERMANAGEMENT
 232 #include <QtNetwork/QNetworkConfiguration>
 233 #endif
 234
 235 QT_BEGIN_NAMESPACE
 236
 237 class QSocks5SocketEngineHandler;
 238 class QHttpSocketEngineHandler;
 239
 240 class QGlobalNetworkProxy
 241 {
 242 public:
 243     QGlobalNetworkProxy()
 244         : mutex(QMutex::Recursive)
 245         , applicationLevelProxy(0)
 246         , applicationLevelProxyFactory(0)
 247         , socks5SocketEngineHandler(0)
 248         , httpSocketEngineHandler(0)
 249     {
 250     }
 251
 252     ~QGlobalNetworkProxy()
 253     {
 254         delete applicationLevelProxy;
 255         delete applicationLevelProxyFactory;
 256         delete socks5SocketEngineHandler;
 257         delete httpSocketEngineHandler;
 258     }
 259
 260     void init()
 261     {
 262         QMutexLocker lock(&mutex);
 263 #ifndef QT_NO_SOCKS5
 264         if (!socks5SocketEngineHandler)
 265             socks5SocketEngineHandler = new QSocks5SocketEngineHandler();
 266 #endif
 267 #ifndef QT_NO_HTTP
 268         if (!httpSocketEngineHandler)
 269             httpSocketEngineHandler = new QHttpSocketEngineHandler();
 270 #endif
 271     }
 272
 273     void setApplicationProxy(const QNetworkProxy &proxy)
 274     {
 275         QMutexLocker lock(&mutex);
 276         if (!applicationLevelProxy)
 277             applicationLevelProxy = new QNetworkProxy;
 278         *applicationLevelProxy = proxy;
 279         delete applicationLevelProxyFactory;
 280         applicationLevelProxyFactory = 0;
 281     }
 282
 283     void setApplicationProxyFactory(QNetworkProxyFactory *factory)
 284     {
 285         QMutexLocker lock(&mutex);
 286         if (applicationLevelProxy)
 287             *applicationLevelProxy = QNetworkProxy();
 288         delete applicationLevelProxyFactory;
 289         applicationLevelProxyFactory = factory;
 290     }
 291
 292     QNetworkProxy applicationProxy()
 293     {
 294         return proxyForQuery(QNetworkProxyQuery()).first();
 295     }
 296
 297     QList<QNetworkProxy> proxyForQuery(const QNetworkProxyQuery &query);
 298
 299 private:
 300     QMutex mutex;
 301     QNetworkProxy *applicationLevelProxy;
 302     QNetworkProxyFactory *applicationLevelProxyFactory;
 303     QSocks5SocketEngineHandler *socks5SocketEngineHandler;
 304     QHttpSocketEngineHandler *httpSocketEngineHandler;
 305 };
 306
 307 QList<QNetworkProxy> QGlobalNetworkProxy::proxyForQuery(const QNetworkProxyQuery &query)
 308 {
 309     QMutexLocker locker(&mutex);
 310
 311     QList<QNetworkProxy> result;
 312     if (!applicationLevelProxyFactory) {
 313         if (applicationLevelProxy
 314             && applicationLevelProxy->type() != QNetworkProxy::DefaultProxy)
 315             result << *applicationLevelProxy;
 316         else
 317             result << QNetworkProxy(QNetworkProxy::NoProxy);
 318         return result;
 319     }
 320
 321     // we have a factory
 322     result = applicationLevelProxyFactory->queryProxy(query);
 323     if (result.isEmpty()) {
 324         qWarning("QNetworkProxyFactory: factory %p has returned an empty result set",
 325                  applicationLevelProxyFactory);
 326         result << QNetworkProxy(QNetworkProxy::NoProxy);
 327     }
 328     return result;
 329 }
 330
 331 Q_GLOBAL_STATIC(QGlobalNetworkProxy, globalNetworkProxy)
 332
 333 namespace {
 334     template<bool> struct StaticAssertTest;
 335     template<> struct StaticAssertTest<true> { enum { Value = 1 }; };
 336 }
 337
 338 static inline void qt_noop_with_arg(int) {}
 339 #define q_static_assert(expr)   qt_noop_with_arg(sizeof(StaticAssertTest< expr >::Value))
 340
 341 static QNetworkProxy::Capabilities defaultCapabilitiesForType(QNetworkProxy::ProxyType type)
 342 {
 343     q_static_assert(int(QNetworkProxy::DefaultProxy) == 0);
 344     q_static_assert(int(QNetworkProxy::FtpCachingProxy) == 5);
 345     static const int defaults[] =
 346     {
 347         /* [QNetworkProxy::DefaultProxy] = */
 348         (int(QNetworkProxy::ListeningCapability) |
 349          int(QNetworkProxy::TunnelingCapability) |
 350          int(QNetworkProxy::UdpTunnelingCapability)),
 351         /* [QNetworkProxy::Socks5Proxy] = */
 352         (int(QNetworkProxy::TunnelingCapability) |
 353          int(QNetworkProxy::ListeningCapability) |
 354          int(QNetworkProxy::UdpTunnelingCapability) |
 355          int(QNetworkProxy::HostNameLookupCapability)),
 356         // it's weird to talk about the proxy capabilities of a "not proxy"...
 357         /* [QNetworkProxy::NoProxy] = */
 358         (int(QNetworkProxy::ListeningCapability) |
 359          int(QNetworkProxy::TunnelingCapability) |
 360          int(QNetworkProxy::UdpTunnelingCapability)),
 361         /* [QNetworkProxy::HttpProxy] = */
 362         (int(QNetworkProxy::TunnelingCapability) |
 363          int(QNetworkProxy::CachingCapability) |
 364          int(QNetworkProxy::HostNameLookupCapability)),
 365         /* [QNetworkProxy::HttpCachingProxy] = */
 366         (int(QNetworkProxy::CachingCapability) |
 367          int(QNetworkProxy::HostNameLookupCapability)),
 368         /* [QNetworkProxy::FtpCachingProxy] = */
 369         (int(QNetworkProxy::CachingCapability) |
 370          int(QNetworkProxy::HostNameLookupCapability)),
 371     };
 372
 373     if (int(type) < 0 || int(type) > int(QNetworkProxy::FtpCachingProxy))
 374         type = QNetworkProxy::DefaultProxy;
 375     return QNetworkProxy::Capabilities(defaults[int(type)]);
 376 }
 377
 378 class QNetworkProxyPrivate: public QSharedData
 379 {
 380 public:
 381     QString hostName;
 382     QString user;
 383     QString password;
 384     QNetworkProxy::Capabilities capabilities;
 385     quint16 port;
 386     QNetworkProxy::ProxyType type;
 387     bool capabilitiesSet;
 388     QNetworkHeadersPrivate headers;
 389
 390     inline QNetworkProxyPrivate(QNetworkProxy::ProxyType t = QNetworkProxy::DefaultProxy,
 391                                 const QString &h = QString(), quint16 p = 0,
 392                                 const QString &u = QString(), const QString &pw = QString())
 393         : hostName(h),
 394           user(u),
 395           password(pw),
 396           capabilities(defaultCapabilitiesForType(t)),
 397           port(p),
 398           type(t),
 399           capabilitiesSet(false)
 400     { }
 401
 402     inline bool operator==(const QNetworkProxyPrivate &other) const
 403     {
 404         return type == other.type &&
 405             port == other.port &&
 406             hostName == other.hostName &&
 407             user == other.user &&
 408             password == other.password &&
 409             capabilities == other.capabilities;
 410     }
 411 };
 412
 413 template<> void QSharedDataPointer<QNetworkProxyPrivate>::detach()
 414 {
 415     if (d && d->ref.load() == 1)
 416         return;
 417     QNetworkProxyPrivate *x = (d ? new QNetworkProxyPrivate(*d)
 418                                : new QNetworkProxyPrivate);
 419     x->ref.ref();
 420     if (d && !d->ref.deref())
 421         delete d;
 422     d = x;
 423 }
 424
 425 /*!
 426     Constructs a QNetworkProxy with DefaultProxy type; the proxy type is
 427     determined by applicationProxy(), which defaults to NoProxy.
 428
 429     \sa setType(), setApplicationProxy()
 430 */
 431 QNetworkProxy::QNetworkProxy()
 432     : d(0)
 433 {
 434     if (QGlobalNetworkProxy *globalProxy = globalNetworkProxy())
 435         globalProxy->init();
 436 }
 437
 438 /*!
 439     Constructs a QNetworkProxy with \a type, \a hostName, \a port,
 440     \a user and \a password.
 441
 442     The default capabilities for proxy type \a type are set automatically.
 443
 444     \sa capabilities()
 445 */
 446 QNetworkProxy::QNetworkProxy(ProxyType type, const QString &hostName, quint16 port,
 447                   const QString &user, const QString &password)
 448     : d(new QNetworkProxyPrivate(type, hostName, port, user, password))
 449 {
 450     if (QGlobalNetworkProxy *globalProxy = globalNetworkProxy())
 451         globalProxy->init();
 452 }
 453
 454 /*!
 455     Constructs a copy of \a other.
 456 */
 457 QNetworkProxy::QNetworkProxy(const QNetworkProxy &other)
 458     : d(other.d)
 459 {
 460 }
 461
 462 /*!
 463     Destroys the QNetworkProxy object.
 464 */
 465 QNetworkProxy::~QNetworkProxy()
 466 {
 467     // QSharedDataPointer takes care of deleting for us
 468 }
 469
 470 /*!
 471     \since 4.4
 472
 473     Compares the value of this network proxy to \a other and returns true
 474     if they are equal (same proxy type, server as well as username and password)
 475 */
 476 bool QNetworkProxy::operator==(const QNetworkProxy &other) const
 477 {
 478     return d == other.d || (d && other.d && *d == *other.d);
 479 }
 480
 481 /*!
 482     \fn bool QNetworkProxy::operator!=(const QNetworkProxy &other) const
 483     \since 4.4
 484
 485     Compares the value of this network proxy to \a other and returns true
 486     if they differ.
 487 \*/
 488
 489 /*!
 490     \since 4.2
 491
 492     Assigns the value of the network proxy \a other to this network proxy.
 493 */
 494 QNetworkProxy &QNetworkProxy::operator=(const QNetworkProxy &other)
 495 {
 496     d = other.d;
 497     return *this;
 498 }
 499
 500 /*!
 501     Sets the proxy type for this instance to be \a type.
 502
 503     Note that changing the type of a proxy does not change
 504     the set of capabilities this QNetworkProxy object holds if any
 505     capabilities have been set with setCapabilities().
 506
 507     \sa type(), setCapabilities()
 508 */
 509 void QNetworkProxy::setType(QNetworkProxy::ProxyType type)
 510 {
 511     d->type = type;
 512     if (!d->capabilitiesSet)
 513         d->capabilities = defaultCapabilitiesForType(type);
 514 }
 515
 516 /*!
 517     Returns the proxy type for this instance.
 518
 519     \sa setType()
 520 */
 521 QNetworkProxy::ProxyType QNetworkProxy::type() const
 522 {
 523     return d ? d->type : DefaultProxy;
 524 }
 525
 526 /*!
 527     \since 4.5
 528
 529     Sets the capabilities of this proxy to \a capabilities.
 530
 531     \sa setType(), capabilities()
 532 */
 533 void QNetworkProxy::setCapabilities(Capabilities capabilities)
 534 {
 535     d->capabilities = capabilities;
 536     d->capabilitiesSet = true;
 537 }
 538
 539 /*!
 540     \since 4.5
 541
 542     Returns the capabilities of this proxy server.
 543
 544     \sa setCapabilities(), type()
 545 */
 546 QNetworkProxy::Capabilities QNetworkProxy::capabilities() const
 547 {
 548     return d ? d->capabilities : defaultCapabilitiesForType(DefaultProxy);
 549 }
 550
 551 /*!
 552     \since 4.4
 553
 554     Returns true if this proxy supports the
 555     QNetworkProxy::CachingCapability capability.
 556
 557     In Qt 4.4, the capability was tied to the proxy type, but since Qt
 558     4.5 it is possible to remove the capability of caching from a
 559     proxy by calling setCapabilities().
 560
 561     \sa capabilities(), type(), isTransparentProxy()
 562 */
 563 bool QNetworkProxy::isCachingProxy() const
 564 {
 565     return capabilities() & CachingCapability;
 566 }
 567
 568 /*!
 569     \since 4.4
 570
 571     Returns true if this proxy supports transparent tunneling of TCP
 572     connections. This matches the QNetworkProxy::TunnelingCapability
 573     capability.
 574
 575     In Qt 4.4, the capability was tied to the proxy type, but since Qt
 576     4.5 it is possible to remove the capability of caching from a
 577     proxy by calling setCapabilities().
 578
 579     \sa capabilities(), type(), isCachingProxy()
 580 */
 581 bool QNetworkProxy::isTransparentProxy() const
 582 {
 583     return capabilities() & TunnelingCapability;
 584 }
 585
 586 /*!
 587     Sets the user name for proxy authentication to be \a user.
 588
 589     \sa user(), setPassword(), password()
 590 */
 591 void QNetworkProxy::setUser(const QString &user)
 592 {
 593     d->user = user;
 594 }
 595
 596 /*!
 597     Returns the user name used for authentication.
 598
 599     \sa setUser(), setPassword(), password()
 600 */
 601 QString QNetworkProxy::user() const
 602 {
 603     return d ? d->user : QString();
 604 }
 605
 606 /*!
 607     Sets the password for proxy authentication to be \a password.
 608
 609     \sa user(), setUser(), password()
 610 */
 611 void QNetworkProxy::setPassword(const QString &password)
 612 {
 613     d->password = password;
 614 }
 615
 616 /*!
 617     Returns the password used for authentication.
 618
 619     \sa user(), setPassword(), setUser()
 620 */
 621 QString QNetworkProxy::password() const
 622 {
 623     return d ? d->password : QString();
 624 }
 625
 626 /*!
 627     Sets the host name of the proxy host to be \a hostName.
 628
 629     \sa hostName(), setPort(), port()
 630 */
 631 void QNetworkProxy::setHostName(const QString &hostName)
 632 {
 633     d->hostName = hostName;
 634 }
 635
 636 /*!
 637     Returns the host name of the proxy host.
 638
 639     \sa setHostName(), setPort(), port()
 640 */
 641 QString QNetworkProxy::hostName() const
 642 {
 643     return d ? d->hostName : QString();
 644 }
 645
 646 /*!
 647     Sets the port of the proxy host to be \a port.
 648
 649     \sa hostName(), setHostName(), port()
 650 */
 651 void QNetworkProxy::setPort(quint16 port)
 652 {
 653     d->port = port;
 654 }
 655
 656 /*!
 657     Returns the port of the proxy host.
 658
 659     \sa setHostName(), setPort(), hostName()
 660 */
 661 quint16 QNetworkProxy::port() const
 662 {
 663     return d ? d->port : 0;
 664 }
 665
 666 /*!
 667     Sets the application level network proxying to be \a networkProxy.
 668
 669     If a QAbstractSocket or QTcpSocket has the
 670     QNetworkProxy::DefaultProxy type, then the QNetworkProxy set with
 671     this function is used. If you want more flexibility in determining
 672     which the proxy, use the QNetworkProxyFactory class.
 673
 674     Setting a default proxy value with this function will override the
 675     application proxy factory set with
 676     QNetworkProxyFactory::setApplicationProxyFactory.
 677
 678     \sa QNetworkProxyFactory, applicationProxy(), QAbstractSocket::setProxy(), QTcpServer::setProxy()
 679 */
 680 void QNetworkProxy::setApplicationProxy(const QNetworkProxy &networkProxy)
 681 {
 682     if (globalNetworkProxy()) {
 683         // don't accept setting the proxy to DefaultProxy
 684         if (networkProxy.type() == DefaultProxy)
 685             globalNetworkProxy()->setApplicationProxy(QNetworkProxy::NoProxy);
 686         else
 687             globalNetworkProxy()->setApplicationProxy(networkProxy);
 688     }
 689 }
 690
 691 /*!
 692     Returns the application level network proxying.
 693
 694     If a QAbstractSocket or QTcpSocket has the
 695     QNetworkProxy::DefaultProxy type, then the QNetworkProxy returned
 696     by this function is used.
 697
 698     \sa QNetworkProxyFactory, setApplicationProxy(), QAbstractSocket::proxy(), QTcpServer::proxy()
 699 */
 700 QNetworkProxy QNetworkProxy::applicationProxy()
 701 {
 702     if (globalNetworkProxy())
 703         return globalNetworkProxy()->applicationProxy();
 704     return QNetworkProxy();
 705 }
 706
 707 /*!
 708     Returns the value of the known network header \a header if it is
 709     in use for this proxy. If it is not present, returns QVariant()
 710     (i.e., an invalid variant).
 711
 712     \sa QNetworkRequest::KnownHeaders, rawHeader(), setHeader()
 713 */
 714 QVariant QNetworkProxy::header(QNetworkRequest::KnownHeaders header) const
 715 {
 716     if (d->type != HttpProxy && d->type != HttpCachingProxy)
 717         return QVariant();
 718     return d->headers.cookedHeaders.value(header);
 719 }
 720
 721 /*!
 722     Sets the value of the known header \a header to be \a value,
 723     overriding any previously set headers. This operation also sets
 724     the equivalent raw HTTP header.
 725
 726     If the proxy is not of type HttpProxy or HttpCachingProxy this has no
 727     effect.
 728
 729     \sa QNetworkRequest::KnownHeaders, setRawHeader(), header()
 730 */
 731 void QNetworkProxy::setHeader(QNetworkRequest::KnownHeaders header, const QVariant &value)
 732 {
 733     if (d->type == HttpProxy || d->type == HttpCachingProxy)
 734         d->headers.setCookedHeader(header, value);
 735 }
 736
 737 /*!
 738     Returns true if the raw header \a headerName is in use for this
 739     proxy. Returns false if the proxy is not of type HttpProxy or
 740     HttpCachingProxy.
 741
 742     \sa rawHeader(), setRawHeader()
 743 */
 744 bool QNetworkProxy::hasRawHeader(const QByteArray &headerName) const
 745 {
 746     if (d->type != HttpProxy && d->type != HttpCachingProxy)
 747         return false;
 748     return d->headers.findRawHeader(headerName) != d->headers.rawHeaders.constEnd();
 749 }
 750
 751 /*!
 752     Returns the raw form of header \a headerName. If no such header is
 753     present or the proxy is not of type HttpProxy or HttpCachingProxy,
 754     an empty QByteArray is returned, which may be indistinguishable
 755     from a header that is present but has no content (use hasRawHeader()
 756     to find out if the header exists or not).
 757
 758     Raw headers can be set with setRawHeader() or with setHeader().
 759
 760     \sa header(), setRawHeader()
 761 */
 762 QByteArray QNetworkProxy::rawHeader(const QByteArray &headerName) const
 763 {
 764     if (d->type != HttpProxy && d->type != HttpCachingProxy)
 765         return QByteArray();
 766     QNetworkHeadersPrivate::RawHeadersList::ConstIterator it =
 767         d->headers.findRawHeader(headerName);
 768     if (it != d->headers.rawHeaders.constEnd())
 769         return it->second;
 770     return QByteArray();
 771 }
 772
 773 /*!
 774     Returns a list of all raw headers that are set in this network
 775     proxy. The list is in the order that the headers were set.
 776
 777     If the proxy is not of type HttpProxy or HttpCachingProxy an empty
 778     QList is returned.
 779
 780     \sa hasRawHeader(), rawHeader()
 781 */
 782 QList<QByteArray> QNetworkProxy::rawHeaderList() const
 783 {
 784     if (d->type != HttpProxy && d->type != HttpCachingProxy)
 785         return QList<QByteArray>();
 786     return d->headers.rawHeadersKeys();
 787 }
 788
 789 /*!
 790     Sets the header \a headerName to be of value \a headerValue. If \a
 791     headerName corresponds to a known header (see
 792     QNetworkRequest::KnownHeaders), the raw format will be parsed and
 793     the corresponding "cooked" header will be set as well.
 794
 795     For example:
 796     \snippet doc/src/snippets/code/src_network_access_qnetworkrequest.cpp 0
 797
 798     will also set the known header LastModifiedHeader to be the
 799     QDateTime object of the parsed date.
 800
 801     Note: setting the same header twice overrides the previous
 802     setting. To accomplish the behaviour of multiple HTTP headers of
 803     the same name, you should concatenate the two values, separating
 804     them with a comma (",") and set one single raw header.
 805
 806     If the proxy is not of type HttpProxy or HttpCachingProxy this has no
 807     effect.
 808
 809     \sa QNetworkRequest::KnownHeaders, setHeader(), hasRawHeader(), rawHeader()
 810 */
 811 void QNetworkProxy::setRawHeader(const QByteArray &headerName, const QByteArray &headerValue)
 812 {
 813     if (d->type == HttpProxy || d->type == HttpCachingProxy)
 814         d->headers.setRawHeader(headerName, headerValue);
 815 }
 816
 817 class QNetworkProxyQueryPrivate: public QSharedData
 818 {
 819 public:
 820     inline QNetworkProxyQueryPrivate()
 821         : localPort(-1), type(QNetworkProxyQuery::TcpSocket)
 822     { }
 823
 824     bool operator==(const QNetworkProxyQueryPrivate &other) const
 825     {
 826         return type == other.type &&
 827             localPort == other.localPort &&
 828             remote == other.remote;
 829     }
 830
 831     QUrl remote;
 832     int localPort;
 833     QNetworkProxyQuery::QueryType type;
 834 #ifndef QT_NO_BEARERMANAGEMENT
 835     QNetworkConfiguration config;
 836 #endif
 837 };
 838
 839 template<> void QSharedDataPointer<QNetworkProxyQueryPrivate>::detach()
 840 {
 841     if (d && d->ref.load() == 1)
 842         return;
 843     QNetworkProxyQueryPrivate *x = (d ? new QNetworkProxyQueryPrivate(*d)
 844                                     : new QNetworkProxyQueryPrivate);
 845     x->ref.ref();
 846     if (d && !d->ref.deref())
 847         delete d;
 848     d = x;
 849 }
 850
 851 /*!
 852     \class QNetworkProxyQuery
 853     \since 4.5
 854     \inmodule QtNetwork
 855     \brief The QNetworkProxyQuery class is used to query the proxy
 856     settings for a socket
 857
 858     QNetworkProxyQuery holds the details of a socket being created or
 859     request being made. It is used by QNetworkProxy and
 860     QNetworkProxyFactory to allow applications to have a more
 861     fine-grained control over which proxy servers are used, depending
 862     on the details of the query. This allows an application to apply
 863     different settings, according to the protocol or destination
 864     hostname, for instance.
 865
 866     QNetworkProxyQuery supports the following criteria for selecting
 867     the proxy:
 868
 869     \list
 870       \o the type of query
 871       \o the local port number to use
 872       \o the destination host name
 873       \o the destination port number
 874       \o the protocol name, such as "http" or "ftp"
 875       \o the URL being requested
 876     \endlist
 877
 878     The destination host name is the host in the connection in the
 879     case of outgoing connection sockets. It is the \c hostName
 880     parameter passed to QTcpSocket::connectToHost() or the host
 881     component of a URL requested with QNetworkRequest.
 882
 883     The destination port number is the requested port to connect to in
 884     the case of outgoing sockets, while the local port number is the
 885     port the socket wishes to use locally before attempting the
 886     external connection. In most cases, the local port number is used
 887     by listening sockets only (QTcpSocket) or by datagram sockets
 888     (QUdpSocket).
 889
 890     The protocol name is an arbitrary string that indicates the type
 891     of connection being attempted. For example, it can match the
 892     scheme of a URL, like "http", "https" and "ftp". In most cases,
 893     the proxy selection will not change depending on the protocol, but
 894     this information is provided in case a better choice can be made,
 895     like choosing an caching HTTP proxy for HTTP-based connections,
 896     but a more powerful SOCKSv5 proxy for all others.
 897
 898     The network configuration specifies which configuration to use,
 899     when bearer management is used. For example on a mobile phone
 900     the proxy settings are likely to be different for the cellular
 901     network vs WLAN.
 902
 903     Some of the criteria may not make sense in all of the types of
 904     query. The following table lists the criteria that are most
 905     commonly used, according to the type of query.
 906
 907     \table
 908     \header
 909       \o Query type
 910       \o Description
 911
 912     \row
 913       \o TcpSocket
 914       \o Normal sockets requesting a connection to a remote server,
 915          like QTcpSocket. The peer hostname and peer port match the
 916          values passed to QTcpSocket::connectToHost(). The local port
 917          is usually -1, indicating the socket has no preference in
 918          which port should be used. The URL component is not used.
 919
 920     \row
 921       \o UdpSocket
 922       \o Datagram-based sockets, which can both send and
 923          receive. The local port, remote host or remote port fields
 924          can all be used or be left unused, depending on the
 925          characteristics of the socket. The URL component is not used.
 926
 927     \row
 928       \o TcpServer
 929       \o Passive server sockets that listen on a port and await
 930          incoming connections from the network. Normally, only the
 931          local port is used, but the remote address could be used in
 932          specific circumstances, for example to indicate which remote
 933          host a connection is expected from. The URL component is not used.
 934
 935     \row
 936       \o UrlRequest
 937       \o A more high-level request, such as those coming from
 938          QNetworkAccessManager. These requests will inevitably use an
 939          outgoing TCP socket, but the this query type is provided to
 940          indicate that more detailed information is present in the URL
 941          component. For ease of implementation, the URL's host and
 942          port are set as the destination address.
 943     \endtable
 944
 945     It should be noted that any of the criteria may be missing or
 946     unknown (an empty QString for the hostname or protocol name, -1
 947     for the port numbers). If that happens, the functions executing
 948     the query should make their best guess or apply some
 949     implementation-defined default values.
 950
 951     \sa QNetworkProxy, QNetworkProxyFactory, QNetworkAccessManager,
 952         QAbstractSocket::setProxy()
 953 */
 954
 955 /*!
 956     \enum QNetworkProxyQuery::QueryType
 957
 958     Describes the type of one QNetworkProxyQuery query.
 959
 960     \value TcpSocket    a normal, outgoing TCP socket
 961     \value UdpSocket    a datagram-based UDP socket, which could send
 962                         to multiple destinations
 963     \value TcpServer    a TCP server that listens for incoming
 964                         connections from the network
 965     \value UrlRequest   a more complex request which involves loading
 966                         of a URL
 967
 968     \sa queryType(), setQueryType()
 969 */
 970
 971 /*!
 972     Constructs a default QNetworkProxyQuery object. By default, the
 973     query type will be QNetworkProxyQuery::TcpSocket.
 974 */
 975 QNetworkProxyQuery::QNetworkProxyQuery()
 976 {
 977 }
 978
 979 /*!
 980     Constructs a QNetworkProxyQuery with the URL \a requestUrl and
 981     sets the query type to \a queryType.
 982
 983     \sa protocolTag(), peerHostName(), peerPort()
 984 */
 985 QNetworkProxyQuery::QNetworkProxyQuery(const QUrl &requestUrl, QueryType queryType)
 986 {
 987     d->remote = requestUrl;
 988     d->type = queryType;
 989 }
 990
 991 /*!
 992     Constructs a QNetworkProxyQuery of type \a queryType and sets the
 993     protocol tag to be \a protocolTag. This constructor is suitable
 994     for QNetworkProxyQuery::TcpSocket queries, because it sets the
 995     peer hostname to \a hostname and the peer's port number to \a
 996     port.
 997 */
 998 QNetworkProxyQuery::QNetworkProxyQuery(const QString &hostname, int port,
 999                                        const QString &protocolTag,
1000                                        QueryType queryType)
1001 {
1002     d->remote.setScheme(protocolTag);
1003     d->remote.setHost(hostname);
1004     d->remote.setPort(port);
1005     d->type = queryType;
1006 }
1007
1008 /*!
1009     Constructs a QNetworkProxyQuery of type \a queryType and sets the
1010     protocol tag to be \a protocolTag. This constructor is suitable
1011     for QNetworkProxyQuery::TcpSocket queries because it sets the
1012     local port number to \a bindPort.
1013
1014     Note that \a bindPort is of type quint16 to indicate the exact
1015     port number that is requested. The value of -1 (unknown) is not
1016     allowed in this context.
1017
1018     \sa localPort()
1019 */
1020 QNetworkProxyQuery::QNetworkProxyQuery(quint16 bindPort, const QString &protocolTag,
1021                                        QueryType queryType)
1022 {
1023     d->remote.setScheme(protocolTag);
1024     d->localPort = bindPort;
1025     d->type = queryType;
1026 }
1027
1028 #ifndef QT_NO_BEARERMANAGEMENT
1029 /*!
1030     Constructs a QNetworkProxyQuery with the URL \a requestUrl and
1031     sets the query type to \a queryType. The specified \a networkConfiguration
1032     is used to resolve the proxy settings.
1033
1034     \sa protocolTag(), peerHostName(), peerPort(), networkConfiguration()
1035 */
1036 QNetworkProxyQuery::QNetworkProxyQuery(const QNetworkConfiguration &networkConfiguration,
1037                                        const QUrl &requestUrl, QueryType queryType)
1038 {
1039     d->config = networkConfiguration;
1040     d->remote = requestUrl;
1041     d->type = queryType;
1042 }
1043
1044 /*!
1045     Constructs a QNetworkProxyQuery of type \a queryType and sets the
1046     protocol tag to be \a protocolTag. This constructor is suitable
1047     for QNetworkProxyQuery::TcpSocket queries, because it sets the
1048     peer hostname to \a hostname and the peer's port number to \a
1049     port. The specified \a networkConfiguration
1050     is used to resolve the proxy settings.
1051
1052     \sa networkConfiguration()
1053 */
1054 QNetworkProxyQuery::QNetworkProxyQuery(const QNetworkConfiguration &networkConfiguration,
1055                                        const QString &hostname, int port,
1056                                        const QString &protocolTag,
1057                                        QueryType queryType)
1058 {
1059     d->config = networkConfiguration;
1060     d->remote.setScheme(protocolTag);
1061     d->remote.setHost(hostname);
1062     d->remote.setPort(port);
1063     d->type = queryType;
1064 }
1065
1066 /*!
1067     Constructs a QNetworkProxyQuery of type \a queryType and sets the
1068     protocol tag to be \a protocolTag. This constructor is suitable
1069     for QNetworkProxyQuery::TcpSocket queries because it sets the
1070     local port number to \a bindPort. The specified \a networkConfiguration
1071     is used to resolve the proxy settings.
1072
1073     Note that \a bindPort is of type quint16 to indicate the exact
1074     port number that is requested. The value of -1 (unknown) is not
1075     allowed in this context.
1076
1077     \sa localPort(), networkConfiguration()
1078 */
1079 QNetworkProxyQuery::QNetworkProxyQuery(const QNetworkConfiguration &networkConfiguration,
1080                                        quint16 bindPort, const QString &protocolTag,
1081                                        QueryType queryType)
1082 {
1083     d->config = networkConfiguration;
1084     d->remote.setScheme(protocolTag);
1085     d->localPort = bindPort;
1086     d->type = queryType;
1087 }
1088 #endif
1089
1090 /*!
1091     Constructs a QNetworkProxyQuery object that is a copy of \a other.
1092 */
1093 QNetworkProxyQuery::QNetworkProxyQuery(const QNetworkProxyQuery &other)
1094     : d(other.d)
1095 {
1096 }
1097
1098 /*!
1099     Destroys this QNetworkProxyQuery object.
1100 */
1101 QNetworkProxyQuery::~QNetworkProxyQuery()
1102 {
1103     // QSharedDataPointer automatically deletes
1104 }
1105
1106 /*!
1107     Copies the contents of \a other.
1108 */
1109 QNetworkProxyQuery &QNetworkProxyQuery::operator=(const QNetworkProxyQuery &other)
1110 {
1111     d = other.d;
1112     return *this;
1113 }
1114
1115 /*!
1116     Returns true if this QNetworkProxyQuery object contains the same
1117     data as \a other.
1118 */
1119 bool QNetworkProxyQuery::operator==(const QNetworkProxyQuery &other) const
1120 {
1121     return d == other.d || (d && other.d && *d == *other.d);
1122 }
1123
1124 /*!
1125     \fn bool QNetworkProxyQuery::operator!=(const QNetworkProxyQuery &other) const
1126
1127     Returns true if this QNetworkProxyQuery object does not contain
1128     the same data as \a other.
1129 */
1130
1131 /*!
1132     Returns the query type.
1133 */
1134 QNetworkProxyQuery::QueryType QNetworkProxyQuery::queryType() const
1135 {
1136     return d ? d->type : TcpSocket;
1137 }
1138
1139 /*!
1140     Sets the query type of this object to be \a type.
1141 */
1142 void QNetworkProxyQuery::setQueryType(QueryType type)
1143 {
1144     d->type = type;
1145 }
1146
1147 /*!
1148     Returns the port number for the outgoing request or -1 if the port
1149     number is not known.
1150
1151     If the query type is QNetworkProxyQuery::UrlRequest, this function
1152     returns the port number of the URL being requested. In general,
1153     frameworks will fill in the port number from their default values.
1154
1155     \sa peerHostName(), localPort(), setPeerPort()
1156 */
1157 int QNetworkProxyQuery::peerPort() const
1158 {
1159     return d ? d->remote.port() : -1;
1160 }
1161
1162 /*!
1163     Sets the requested port number for the outgoing connection to be
1164     \a port. Valid values are 1 to 65535, or -1 to indicate that the
1165     remote port number is unknown.
1166
1167     The peer port number can also be used to indicate the expected
1168     port number of an incoming connection in the case of
1169     QNetworkProxyQuery::UdpSocket or QNetworkProxyQuery::TcpServer
1170     query types.
1171
1172     \sa peerPort(), setPeerHostName(), setLocalPort()
1173 */
1174 void QNetworkProxyQuery::setPeerPort(int port)
1175 {
1176     d->remote.setPort(port);
1177 }
1178
1179 /*!
1180     Returns the host name or IP address being of the outgoing
1181     connection being requested, or an empty string if the remote
1182     hostname is not known.
1183
1184     If the query type is QNetworkProxyQuery::UrlRequest, this function
1185     returns the host component of the URL being requested.
1186
1187     \sa peerPort(), localPort(), setPeerHostName()
1188 */
1189 QString QNetworkProxyQuery::peerHostName() const
1190 {
1191     return d ? d->remote.host() : QString();
1192 }
1193
1194 /*!
1195     Sets the hostname of the outgoing connection being requested to \a
1196     hostname.  An empty hostname can be used to indicate that the
1197     remote host is unknown.
1198
1199     The peer host name can also be used to indicate the expected
1200     source address of an incoming connection in the case of
1201     QNetworkProxyQuery::UdpSocket or QNetworkProxyQuery::TcpServer
1202     query types.
1203
1204     \sa peerHostName(), setPeerPort(), setLocalPort()
1205 */
1206 void QNetworkProxyQuery::setPeerHostName(const QString &hostname)
1207 {
1208     d->remote.setHost(hostname);
1209 }
1210
1211 /*!
1212     Returns the port number of the socket that will accept incoming
1213     packets from remote servers or -1 if the port is not known.
1214
1215     \sa peerPort(), peerHostName(), setLocalPort()
1216 */
1217 int QNetworkProxyQuery::localPort() const
1218 {
1219     return d ? d->localPort : -1;
1220 }
1221
1222 /*!
1223     Sets the port number that the socket wishes to use locally to
1224     accept incoming packets from remote servers to \a port. The local
1225     port is most often used with the QNetworkProxyQuery::TcpServer
1226     and QNetworkProxyQuery::UdpSocket query types.
1227
1228     Valid values are 0 to 65535 (with 0 indicating that any port
1229     number will be acceptable) or -1, which means the local port
1230     number is unknown or not applicable.
1231
1232     In some circumstances, for special protocols, it's the local port
1233     number can also be used with a query of type
1234     QNetworkProxyQuery::TcpSocket. When that happens, the socket is
1235     indicating it wishes to use the port number \a port when
1236     connecting to a remote host.
1237
1238     \sa localPort(), setPeerPort(), setPeerHostName()
1239 */
1240 void QNetworkProxyQuery::setLocalPort(int port)
1241 {
1242     d->localPort = port;
1243 }
1244
1245 /*!
1246     Returns the protocol tag for this QNetworkProxyQuery object, or an
1247     empty QString in case the protocol tag is unknown.
1248
1249     In the case of queries of type QNetworkProxyQuery::UrlRequest,
1250     this function returns the value of the scheme component of the
1251     URL.
1252
1253     \sa setProtocolTag(), url()
1254 */
1255 QString QNetworkProxyQuery::protocolTag() const
1256 {
1257     return d ? d->remote.scheme() : QString();
1258 }
1259
1260 /*!
1261     Sets the protocol tag for this QNetworkProxyQuery object to be \a
1262     protocolTag.
1263
1264     The protocol tag is an arbitrary string that indicates which
1265     protocol is being talked over the socket, such as "http", "xmpp",
1266     "telnet", etc. The protocol tag is used by the backend to
1267     return a request that is more specific to the protocol in
1268     question: for example, a HTTP connection could be use a caching
1269     HTTP proxy server, while all other connections use a more powerful
1270     SOCKSv5 proxy server.
1271
1272     \sa protocolTag()
1273 */
1274 void QNetworkProxyQuery::setProtocolTag(const QString &protocolTag)
1275 {
1276     d->remote.setScheme(protocolTag);
1277 }
1278
1279 /*!
1280     Returns the URL component of this QNetworkProxyQuery object in
1281     case of a query of type QNetworkProxyQuery::UrlRequest.
1282
1283     \sa setUrl()
1284 */
1285 QUrl QNetworkProxyQuery::url() const
1286 {
1287     return d ? d->remote : QUrl();
1288 }
1289
1290 /*!
1291     Sets the URL component of this QNetworkProxyQuery object to be \a
1292     url. Setting the URL will also set the protocol tag, the remote
1293     host name and port number. This is done so as to facilitate the
1294     implementation of the code that determines the proxy server to be
1295     used.
1296
1297     \sa url(), peerHostName(), peerPort()
1298 */
1299 void QNetworkProxyQuery::setUrl(const QUrl &url)
1300 {
1301     d->remote = url;
1302 }
1303
1304 #ifndef QT_NO_BEARERMANAGEMENT
1305 /*!
1306     Returns the network configuration component of the query.
1307
1308     \sa setNetworkConfiguration()
1309 */
1310 QNetworkConfiguration QNetworkProxyQuery::networkConfiguration() const
1311 {
1312     return d ? d->config : QNetworkConfiguration();
1313 }
1314
1315 /*!
1316     Sets the network configuration component of this QNetworkProxyQuery
1317     object to be \a networkConfiguration. The network configuration can
1318     be used to return different proxy settings based on the network in
1319     use, for example WLAN vs cellular networks on a mobile phone.
1320
1321     In the case of "user choice" or "service network" configurations,
1322     you should first start the QNetworkSession and obtain the active
1323     configuration from its properties.
1324
1325     \sa networkConfiguration()
1326 */
1327 void QNetworkProxyQuery::setNetworkConfiguration(const QNetworkConfiguration &networkConfiguration)
1328 {
1329     d->config = networkConfiguration;
1330 }
1331 #endif
1332
1333 /*!
1334     \class QNetworkProxyFactory
1335     \brief The QNetworkProxyFactory class provides fine-grained proxy selection.
1336     \since 4.5
1337
1338     \ingroup network
1339     \inmodule QtNetwork
1340
1341     QNetworkProxyFactory is an extension to QNetworkProxy, allowing
1342     applications to have a more fine-grained control over which proxy
1343     servers are used, depending on the socket requesting the
1344     proxy. This allows an application to apply different settings,
1345     according to the protocol or destination hostname, for instance.
1346
1347     QNetworkProxyFactory can be set globally for an application, in
1348     which case it will override any global proxies set with
1349     QNetworkProxy::setApplicationProxy(). If set globally, any sockets
1350     created with Qt will query the factory to determine the proxy to
1351     be used.
1352
1353     A factory can also be set in certain frameworks that support
1354     multiple connections, such as QNetworkAccessManager. When set on
1355     such object, the factory will be queried for sockets created by
1356     that framework only.
1357
1358     \section1 System Proxies
1359
1360     You can configure a factory to use the system proxy's settings.
1361     Call the setUseSystemConfiguration() function with true to enable
1362     this behavior, or false to disable it.
1363
1364     Similarly, you can use a factory to make queries directly to the
1365     system proxy by calling its systemProxyForQuery() function.
1366
1367     \warning Depending on the configuration of the user's system, the
1368     use of system proxy features on certain platforms may be subject
1369     to limitations. The systemProxyForQuery() documentation contains a
1370     list of these limitations for those platforms that are affected.
1371 */
1372
1373 /*!
1374     Creates a QNetworkProxyFactory object.
1375
1376     Since QNetworkProxyFactory is an abstract class, you cannot create
1377     objects of type QNetworkProxyFactory directly.
1378 */
1379 QNetworkProxyFactory::QNetworkProxyFactory()
1380 {
1381 }
1382
1383 /*!
1384     Destroys the QNetworkProxyFactory object.
1385 */
1386 QNetworkProxyFactory::~QNetworkProxyFactory()
1387 {
1388 }
1389
1390
1391 /*!
1392     \since 4.6
1393
1394     Enables the use of the platform-specific proxy settings, and only those.
1395     See systemProxyForQuery() for more information.
1396
1397     Internally, this method (when called with \a enable set to true)
1398     sets an application-wide proxy factory. For this reason, this method
1399     is mutually exclusive with setApplicationProxyFactory(): calling
1400     setApplicationProxyFactory() overrides the use of the system-wide proxy,
1401     and calling setUseSystemConfiguration() overrides any
1402     application proxy or proxy factory that was previously set.
1403
1404     \note See the systemProxyForQuery() documentation for a list of
1405     limitations related to the use of system proxies.
1406 */
1407 void QNetworkProxyFactory::setUseSystemConfiguration(bool enable)
1408 {
1409     if (enable) {
1410         setApplicationProxyFactory(new QSystemConfigurationProxyFactory);
1411     } else {
1412         setApplicationProxyFactory(0);
1413     }
1414 }
1415
1416 /*!
1417     Sets the application-wide proxy factory to be \a factory. This
1418     function will take ownership of that object and will delete it
1419     when necessary.
1420
1421     The application-wide proxy is used as a last-resort when all other
1422     proxy selection requests returned QNetworkProxy::DefaultProxy. For
1423     example, QTcpSocket objects can have a proxy set with
1424     QTcpSocket::setProxy, but if none is set, the proxy factory class
1425     set with this function will be queried.
1426
1427     If you set a proxy factory with this function, any application
1428     level proxies set with QNetworkProxy::setApplicationProxy will be
1429     overridden.
1430
1431     \sa QNetworkProxy::setApplicationProxy(),
1432         QAbstractSocket::proxy(), QAbstractSocket::setProxy()
1433 */
1434 void QNetworkProxyFactory::setApplicationProxyFactory(QNetworkProxyFactory *factory)
1435 {
1436     if (globalNetworkProxy())
1437         globalNetworkProxy()->setApplicationProxyFactory(factory);
1438 }
1439
1440 /*!
1441     \fn QList<QNetworkProxy> QNetworkProxyFactory::queryProxy(const QNetworkProxyQuery &query)
1442
1443     This function examines takes the query request, \a query,
1444     examines the details of the type of socket or request and returns
1445     a list of QNetworkProxy objects that indicate the proxy servers to
1446     be used, in order of preference.
1447
1448     When reimplementing this class, take care to return at least one
1449     element.
1450
1451     If you cannot determine a better proxy alternative, use
1452     QNetworkProxy::DefaultProxy, which tells the code querying for a
1453     proxy to use a higher alternative. For example, if this factory is
1454     set to a QNetworkAccessManager object, DefaultProxy will tell it
1455     to query the application-level proxy settings.
1456
1457     If this factory is set as the application proxy factory,
1458     DefaultProxy and NoProxy will have the same meaning.
1459 */
1460
1461 /*!
1462     \fn QList<QNetworkProxy> QNetworkProxyFactory::systemProxyForQuery(const QNetworkProxyQuery &query)
1463
1464     This function examines takes the query request, \a query,
1465     examines the details of the type of socket or request and returns
1466     a list of QNetworkProxy objects that indicate the proxy servers to
1467     be used, in order of preference.
1468
1469     This function can be used to determine the platform-specific proxy
1470     settings. This function will use the libraries provided by the
1471     operating system to determine the proxy for a given connection, if
1472     such libraries exist. If they don't, this function will just return a
1473     QNetworkProxy of type QNetworkProxy::NoProxy.
1474
1475     On Windows, this function will use the WinHTTP DLL functions. Despite
1476     its name, Microsoft suggests using it for all applications that
1477     require network connections, not just HTTP. This will respect the
1478     proxy settings set on the registry with the proxycfg.exe tool. If
1479     those settings are not found, this function will attempt to obtain
1480     Internet Explorer's settings and use them.
1481
1482     On MacOS X, this function will obtain the proxy settings using the
1483     SystemConfiguration framework from Apple. It will apply the FTP,
1484     HTTP and HTTPS proxy configurations for queries that contain the
1485     protocol tag "ftp", "http" and "https", respectively. If the SOCKS
1486     proxy is enabled in that configuration, this function will use the
1487     SOCKS server for all queries. If SOCKS isn't enabled, it will use
1488     the HTTPS proxy for all TcpSocket and UrlRequest queries.
1489
1490     On other systems, this function will pick up proxy settings from
1491     the "http_proxy" environment variable. This variable must be a URL
1492     using one of the following schemes: "http", "socks5" or "socks5h".
1493
1494     \section1 Limitations
1495
1496     These are the limitations for the current version of this
1497     function. Future versions of Qt may lift some of the limitations
1498     listed here.
1499
1500     \list
1501     \o On MacOS X, this function will ignore the Proxy Auto Configuration
1502     settings, since it cannot execute the associated ECMAScript code.
1503
1504     \o On Windows platforms, this function may take several seconds to
1505     execute depending on the configuration of the user's system.
1506     \endlist
1507 */
1508
1509 /*!
1510     This function examines takes the query request, \a query,
1511     examines the details of the type of socket or request and returns
1512     a list of QNetworkProxy objects that indicate the proxy servers to
1513     be used, in order of preference.
1514 */
1515 QList<QNetworkProxy> QNetworkProxyFactory::proxyForQuery(const QNetworkProxyQuery &query)
1516 {
1517     if (!globalNetworkProxy())
1518         return QList<QNetworkProxy>() << QNetworkProxy(QNetworkProxy::NoProxy);
1519     return globalNetworkProxy()->proxyForQuery(query);
1520 }
1521
1522 QT_END_NAMESPACE
1523
1524 #endif // QT_NO_NETWORKPROXY