QNetworkAccessManager

La classe QNetworkAccessManager permet � l'application d'envoyer des requ�tes sur le r�seau et de recevoir des r�ponses. Plus d'informations...

#include <QNetworkAccessManager>

Voir la position dans l'arbre des classes.

H�ritage

H�rite de QObject.

Note : toutes les fonctions de cette classe sont r�-entrantes.

Cette classe a �t� introduite dans Qt 4.4.

Description d�taill�e

La classe QNetworkAccessManager permet � l'application d'envoyer des requ�tes sur le r�seau et de recevoir des r�ponses

L'API Network Access (acc�s au r�seau) est construite autour d'un objet QNetworkAccessManager contenant la configuration et les param�tres communs pour les requ�tes envoy�es. Il contient la configuration du proxy et du cache, ainsi que les signaux associ�s, et des signaux de r�ponse pouvant �tre utilis�s pour suivre l'avancement d'une op�ration sur le r�seau. Un seul QNetworkAccessManager est suffisant pour l'ensemble d'une application Qt.

Une fois que l'objet QNetworkAccessManager a �t� cr��, l'application peut l'utiliser pour envoyer des requ�tes sur le r�seau. Un groupe de fonctions standard, prenant en arguments une requ�te et des donn�es optionnelles, sont fournies. Elles renvoient un objet QNetworkReply, utilis� pour acc�der aux donn�es renvoy�es en r�ponse � la requ�te correspondante.

Le code suivant effectue un t�l�chargement simple depuis le r�seau :

 QNetworkAccessManager *manager = new QNetworkAccessManager(this);
 connect(manager, SIGNAL(finished(QNetworkReply*)),
         this, SLOT(replyFinished(QNetworkReply*)));
 
 manager->get(QNetworkRequest(QUrl("http://qt.nokia.com")));

QNetworkAccessManager poss�de une API asynchrone. Lorsque le slot replyFinished ci-dessus est appel�, il renvoie en param�tre un objet QNetworkReply contenant les donn�es t�l�charg�es ainsi que des m�tadonn�es (en-t�tes, etc.).

Note : apr�s l'ex�cution de la requ�te, il est de la responsabilit� de l'utilisateur de d�truire l'objet QNetworkReply � un moment appropri�. Ne le d�truisez pas directement dans le slot connect� � finished(). Vous pouvez utiliser la fonction deleteLater().

Note : qNetworkAccessManager met les requ�tes qu'il re�oit dans une file d'attente. Le nombre de requ�tes ex�cut�es en parall�le d�pend du protocole. Actuellement, pour le protocole HTTP sur les plateformes de bureau, six requ�tes peuvent �tre ex�cut�es en parall�le par combinaison h�te/port.

Voici un exemple plus sophistiqu�, supposant que le QNetworkAccessManager existe d�j� :

 QNetworkRequest request;
 request.setUrl(QUrl("http://qt.nokia.com"));
 request.setRawHeader("User-Agent", "MyOwnBrowser 1.0");
 
 QNetworkReply *reply = manager->get(request);
 connect(reply, SIGNAL(readyRead()), this, SLOT(slotReadyRead()));
 connect(reply, SIGNAL(error(QNetworkReply::NetworkError)),
         this, SLOT(slotError(QNetworkReply::NetworkError)));
 connect(reply, SIGNAL(sslErrors(QList<QSslError>)),
         this, SLOT(slotSslErrors(QList<QSslError>)));

Gestion de la connexion et du changement de r�seau

Avec l'ajout de l'API d'acc�s au r�seau dans Qt 4.7, QNetworkAccessManager a acquis la possibilit� de g�rer les connexions r�seau. QNetworkAccessManager peut lancer l'interface r�seau si l'appareil est hors ligne et arr�ter l'interface si le processus courant est le dernier � utiliser la liaison. Notez que certaines plateformes d�finissent des p�riodes de latence entre le moment o� la derni�re application arr�te d'utiliser une liaison et le moment o� le syst�me supprime la liaison. Le changement de r�seau est �galement transparent. Toutes les requ�tes r�seau en attente ou en cours sont automatiquement transf�r�es sur le nouveau point d'acc�s.

Il ne devrait pas �tre n�cessaire de modifier les clients pour utiliser cette fonctionnalit�. En fait, il est probable que le code de connexion sp�cifique � la plateforme peut simplement �tre retir� de l'application.

Note : la gestion de la connexion et du changement de r�seau de QNetworkAccessManager d�pend du support fourni par la plateforme. Le drapeau QNetworkConfigurationManager::NetworkSessionRequired peut �tre utilis� pour d�tecter si QNetworkAccessManager poss�de cette fonction. Actuellement, seules les plateformes MeeGo/Harmattan et Symbian fournissent cette gestion de connexion.

Note : cette fonctionnalit� ne peut pas �tre combin�e avec l'API de changement de r�seau (Bearer Management) fournie par QtMobility. Les applications doivent migrer vers la version Qt de l'API.

Contraintes de s�curit� de la plateforme Symbian

Sur Symbian, les processus utilisant cette classe doivent poss�der les capacit�s de s�curit� NetworkServices. Si le processus client n'a pas cette capacit�, les op�rations vont produire une panique.

Les capacit�s de s�curit� de la plateforme sont ajout�es via la variable qmake TARGET.CAPABILITY.

Voir aussi QNetworkRequest, QNetworkReply et QNetworkProxy.

Type

enum QNetworkAccessManager::NetworkAccessibility

Indique si l'acc�s au r�seau est possible depuis cet adaptateur r�seau.

Voir aussi networkAccessible.

enum QNetworkAccessManager::Operation

Indique l'op�ration que cette r�ponse traite.

Cette �num�ration a �t� introduite ou modifi�e dans Qt 4.7.

Voir aussi QNetworkReply::operation().

Propri�t�s

networkAccessible : NetworkAccessibility

Cette propri�t� informe sur l'accessibilit� actuelle du r�seau via cet adaptateur.

Si le r�seau est inaccessible, l'adaptateur r�seau ne traitera aucune requ�te r�seau, elles vont toutes �chouer en renvoyant une erreur. Les requ�tes avec des URL commen�ant par file:// seront tout de m�me trait�es.

Par d�faut, la valeur de cette propri�t� refl�te l'�tat physique de l'appareil. Les applications peuvent forcer la d�sactivation des requ�tes via cet acc�s r�seau en appelant

 networkAccessManager->setNetworkAccessible(QNetworkAccessManager::NotAccessible);

Les requ�tes r�seau peuvent �tre r�activ�es en appelant

 networkAccessManager->setNetworkAccessible(QNetworkAccessManager::Accessible);

Note : l'appel de setNetworkAccessible() ne change pas l'�tat du r�seau.

Cette propri�t� a �t� introduite dans Qt 4.7.

Fonctions d'acc�s

NetworkAccessibility networkAccessible () const

void setNetworkAccessible ( NetworkAccessibility accessible )

Signal de notification

void networkAccessibleChanged ( QNetworkAccessManager::NetworkAccessibility accessible )

Fonctions membres

QNetworkAccessManager::QNetworkAccessManager ( QObject * parent = 0 )

Construit un objet QNetworkAccessManager, objet central de l'API d'acc�s r�seau, et sp�cifie que son objet parent est parent.

QNetworkAccessManager::~QNetworkAccessManager ()

D�truit l'objet QNetworkAccessManager et lib�re les ressources associ�es. Notez que les objets QNetworkReply qui sont renvoy�s depuis une instance de cette classe ont cet objet comme parent, ce qui signifie qu'ils seront eux aussi d�truits si vous n'appelez pas QObject::setParent() sur eux.

QNetworkConfiguration QNetworkAccessManager::activeConfiguration () const

Renvoie la configuration r�seau actuellement active.

Si la configuration r�seau renvoy�e par configuration() est du type QNetworkConfiguration::ServiceNetwork, cette fonction renverra la configuration actuellement active du r�seau enfant de cette configuration.

Utilisez cette fonction pour obtenir la configuration r�seau r�ellement utilis�e actuellement par la session r�seau.

Cette fonction a �t� introduite dans Qt 4.7.

Voir aussi configuration().

void QNetworkAccessManager::authenticationRequired ( QNetworkReply * reply, QAuthenticator * authenticator ) [signal]

Ce signal est �mis chaque fois qu'un serveur final demande une authentification avant d'envoyer le contenu demand�. Le slot connect� � ce signal doit remplir le certificat d'identit� pour ce contenu (qui peut �tre d�termin� en inspectant l'objet reply) dans l'objet authenticator.

QNetworkAccessManager conservera le certificat dans un cache interne et renverra les m�mes valeurs si le serveur redemande une authentification, sans �mettre le signal authenticationRequired(). S'il rejette le certificat, ce signal sera r��mis.

Voir aussi proxyAuthenticationRequired().

QAbstractNetworkCache * QNetworkAccessManager::cache () const

Renvoie le cache utilis� pour le stockage des donn�es re�ues depuis le r�seau.

Cette fonction a �t� introduite dans Qt 4.5.

Voir aussi setCache().

QNetworkConfiguration QNetworkAccessManager::configuration () const

Renvoie la configuration qui sera utilis�e pour la cr�ation de la session r�seau qui sera utilis�e pour le traitement des requ�tes r�seau.

Cette fonction a �t� introduite dans Qt 4.7.

Voir aussi setConfiguration() et activeConfiguration().

QNetworkCookieJar * QNetworkAccessManager::cookieJar () const

Renvoie le QNetworkCookieJar utilis� pour le stockage des cookies re�us du r�seau ainsi que les cookies qui sont sur le point d'�tre envoy�s.

Voir aussi setCookieJar().

QNetworkReply * QNetworkAccessManager::createRequest ( Operation op, const QNetworkRequest & req, QIODevice * outgoingData = 0 ) [virtual protected]

Renvoie un nouvel objet QNetworkReply pour le traitement de l'op�ration op et de la requ�te req. Le QIODevice outgoingData vaut toujours 0 dans le cas des requ�tes Get et Head mais est la valeur pass�e � post() et put() pour ces op�rations (les variantes QByteArray passent un objet QBuffer).

L'impl�mentation par d�faut appelle QNetworkCookieJar::cookiesForUrl() sur le cookie jar (pot � cookies) sp�cifi� par setCookieJar() pour obtenir les cookies � envoyer au serveur distant.

L'objet renvoy� doit �tre dans un �tat ouvert.

QNetworkReply * QNetworkAccessManager::deleteResource ( const QNetworkRequest & request )

Envoie une requ�te de suppression de la ressource identifi�e par l'URL de request.

Note : cette fonctionnalit� est actuellement seulement disponible pour HTTP, elle effectue une requ�te HTTP DELETE.

Cette fonction a �t� introduite dans Qt 4.6.

Voir aussi get(), post(), put() et sendCustomRequest().

void QNetworkAccessManager::finished ( QNetworkReply * reply ) [signal]

Ce signal est �mis chaque fois qu'une r�ponse r�seau se termine. Le param�tre reply contient un pointeur sur la r�ponse qui vient de se terminer. Ce signal est �mis conjointement avec le signal QNetworkReply::finished().

Voir QNetworkReply::finished() pour des informations sur l'�tat dans lequel l'objet va �tre.

Note : ne supprimez par l'objet reply dans le slot connect� � ce signal. Utilisez deleteLater().

Voir aussi QNetworkReply::finished() et QNetworkReply::error().

QNetworkReply * QNetworkAccessManager::get ( const QNetworkRequest & request )

Poste une requ�te de demande des contenus de request et renvoie un nouvel objet QNetworkReply ouvert en lecture qui �mettra le signal readyRead() lorsque les donn�es seront arriv�es.

Les contenus ainsi que les en-t�tes associ�s seront t�l�charg�s.

Voir aussi post(), put(), deleteResource() et sendCustomRequest().

QNetworkReply * QNetworkAccessManager::head ( const QNetworkRequest & request )

Poste une requ�te de demande des en-t�tes de request et renvoie un nouvel objet QNetworkReply qui contiendra ces en-t�tes.

Cette fonction est nomm�e d'apr�s la requ�te HTTP associ�e (HEAD).

void QNetworkAccessManager::networkAccessibleChanged ( QNetworkAccessManager::NetworkAccessibility accessible ) [signal]

Ce signal est �mis lorsque la valeur de la propri�t� networkAccessible change. accessible est la nouvelle valeur de l'accessibilit�.

QNetworkReply * QNetworkAccessManager::post ( const QNetworkRequest & request, QIODevice * data )

Envoie une requ�te HTTP POST � la destination sp�cifi�e par request et renvoie un nouvel objet QNetworkReply ouvert en lecture qui contiendra la r�ponse envoy�e par le serveur. Les contenus de l'objet data seront transmis au serveur.

data doit �tre ouvert en lecture et doit rester valide jusqu'� ce que le signal finished() soit �mis pour cette r�ponse.

Note : l'envoi d'une requ�te POST sur les protocoles autres que HTTP et HTTPS est ind�fini et �chouera probablement.

Voir aussi get(), put(), deleteResource() et sendCustomRequest().

QNetworkReply * QNetworkAccessManager::post ( const QNetworkRequest & request, const QByteArray & data )

Il s'agit d'une fonction surcharg�e.

Envoie le contenu du tableau d'octets data � la destination sp�cifi�e par request.

QNetworkProxy QNetworkAccessManager::proxy () const

Renvoie le QNetworkProxy que les requ�tes faites avec cet objet QNetworkAccessManager vont utiliser. La valeur par d�faut du proxy est QNetworkProxy::DefaultProxy.

Voir aussi setProxy(), setProxyFactory() et proxyAuthenticationRequired().

void QNetworkAccessManager::proxyAuthenticationRequired ( const QNetworkProxy & proxy, QAuthenticator * authenticator ) [signal]

Ce signal est �mis chaque fois qu'un proxy demande une authentification et que QNetworkAccessManager ne trouve pas de certificat valide dans le cache. Le slot connect� � ce signal doit remplir le certificat pour le proxy dans l'objet authenticator.

QNetworkAccessManager va mettre le certificat en cache. � la prochaine demande d'authentification par le proxy, QNetworkAccessManager renverra automatiquement le m�me certificat sans envoyer de nouveau le signal proxyAuthenticationRequired.

Si le proxy rejette le certificat, QNetworkAccessManager r��mettra ce signal.

Voir aussi proxy(), setProxy() et authenticationRequired().

QNetworkProxyFactory * QNetworkAccessManager::proxyFactory () const

Renvoie le QNetworkProxyFactory utilis� par cet objet QNetworkAccessManager pour d�terminer les proxy � utiliser pour les requ�tes.

Notez que le pointeur renvoy� par cette fonction est g�r� par QNetworkAccessManager et peut �tre supprim� � tout moment.

Cette fonction a �t� introduite dans Qt 4.5.

Voir aussi setProxyFactory() et proxy().

QNetworkReply * QNetworkAccessManager::put ( const QNetworkRequest & request, QIODevice * data )

Transmet les contenus de data � la request destination et renvoie un nouvel objet QNetworkReply qui sera ouvert aux r�ponses.

data doit �tre ouvert en lecture lorsque cette fonction est appel�e et doit rester valide jusqu'� ce que le signal finished() soit �mis pour cette r�ponse.

Le fait que l'objet renvoy� poss�de ou non du contenu lisible d�pend du protocole. Pour HTTP, le serveur peut envoyer une petite page HTML indiquant que la transmission a r�ussi (ou pas). D'autres protocoles auront probablement du contenu dans leurs r�ponses.

Note : pour HTTP, cette requ�te enverra une requ�te PUT, que la plupart des serveurs interdisent. Les m�canismes d'envoi de formulaires, incluant l'envoi de fichiers via des formulaires HTML, utilisent le m�canisme POST.

Voir aussi get(), post(), deleteResource() et sendCustomRequest().

QNetworkReply * QNetworkAccessManager::put ( const QNetworkRequest & request, const QByteArray & data )

Il s'agit d'une fonction surcharg�e.

Envoie le contenu du tableau d'octets data � la destination sp�cifi�e par request.

QNetworkReply * QNetworkAccessManager::sendCustomRequest ( const QNetworkRequest & request, const QByteArray & verb, QIODevice * data = 0 )

Envoie une requ�te personnalis�e au serveur identifi� par l'URL de request.

Il est de la responsabilit� de l'utilisateur d'envoyer au serveur un verb valide au sens de la sp�cification HTTP.

Cette m�thode donne le moyen d'envoyer des verbes diff�rents des verbes communs envoy�s avec get() ou post(), par exemple une commande HTTP OPTIONS.

Si data n'est pas vide, son contenu sera transmis au serveur ; dans ce cas, data doit �tre ouvert en lecture et doit rester valide jusqu'� l'�mission du signal finished() pour cette r�ponse.

Note : cette fonctionnalit� n'est actuellement disponible que pour HTTP.

Cette fonction a �t� introduite dans Qt 4.7.

Voir aussi get(), post(), put() et deleteResource().

void QNetworkAccessManager::setCache ( QAbstractNetworkCache * cache )

D�finit cache comme cache r�seau de cet objet. Le cache est utilis� pour toutes les requ�tes envoy�es par ce gestionnaire.

Utilisez cette fonction pour d�finir comme cache un objet impl�mentant des fonctions suppl�mentaires, comme la sauvegarde des cookies sur un support de stockage persistant.

Note : QNetworkAccessManager devient propri�taire de l'objet cache.

QNetworkAccessManager ne poss�de pas de cache par d�faut. Qt fournit un cache disque simple, QNetworkDiskCache, qui peut �tre utilis�.

Cette fonction a �t� introduite dans Qt 4.5.

Voir aussi cache() et QNetworkRequest::CacheLoadControl.

void QNetworkAccessManager::setConfiguration ( const QNetworkConfiguration & config )

Sp�cifie que config sera la configuration r�seau utilis�e � la cr�ation d'une session r�seau.

La configuration r�seau est utilis�e pour cr�er et ouvrir une session r�seau avant que des requ�tes n�cessitant un acc�s au r�seau soient trait�es. Si aucune configuration r�seau n'est explicitement sp�cifi�e avec cette fonction c'est la configuration renvoy�e par QNetworkConfigurationManager::defaultConfiguration() qui sera utilis�e.

Pour restaurer la configuration r�seau par d�faut passez en param�tre la valeur renvoy�e par QNetworkConfigurationManager::defaultConfiguration().

 QNetworkConfigurationManager manager;
 networkAccessManager->setConfiguration(manager.defaultConfiguration());

Si vous sp�cifiez une configuration invalide, aucune session r�seau ne sera cr��e. Dans ce cas les requ�tes r�seau seront tout de m�me trait�es mais risquent d'�chouer. Par exemple :

 networkAccessManager->setConfiguration(QNetworkConfiguration());

Cette fonction a �t� introduite dans Qt 4.7.

Voir aussi configuration() et QNetworkSession.

void QNetworkAccessManager::setCookieJar ( QNetworkCookieJar * cookieJar )

Sp�cifie que le « pot � cookies » (cookie jar) de l'objet devient cookieJar. Le pot � cookie est utilis� par toutes les requ�tes trait�es par le gestionnaire.

Utilisez cette fonction pour d�finir comme pot � cookies un objet impl�mentant des fonctions suppl�mentaires, comme la sauvegarde des cookies sur un support de stockage persistant.

Note : QNetworkAccessManager devient propri�taire de l'objet cookieJar.

Si cookieJar appartient au m�me thread que ce QNetworkAccessManager, il d�finira le parent de cookieJar de fa�on � ce que cookieJar soit supprim� en m�me temps que l'objet. Si vous voulez partager des pots � cookies entre diff�rents objets QNetworkAccessManager, vous pouvez mettre le parent de cookieJar � z�ro apr�s l'appel de cette fonction.

Par d�faut QNetworkAccessManager n'impl�mente pas de r�gles propres pour la gestion des cookies : il accepte tous les cookies envoy�s par le serveur, du moment qu'ils sont bien form�s et r�pondent aux crit�res minimums de s�curit� (le domaine et le chemin du cookie correspondent � celui de la requ�te). Pour impl�menter vos propres r�gles de s�curit�, r�impl�mentez QNetworkCookieJar::cookiesForUrl() et les fonctions virtuelles QNetworkCookieJar::setCookiesFromUrl(). Ces fonctions sont appel�es par QNetworkAccessManager lorsqu'il d�tecte un nouveau cookie.

Voir aussi cookieJar(), QNetworkCookieJar::cookiesForUrl() et QNetworkCookieJar::setCookiesFromUrl().

void QNetworkAccessManager::setProxy ( const QNetworkProxy & proxy )

Sp�cifie que proxy devient le proxy � utiliser dans les requ�tes futures. Cela n'affecte pas les requ�tes d�j� envoy�es. Le signal proxyAuthenticationRequired() sera �mis si le proxy demande une authentification.

Un proxy sp�cifi� par cette fonction sera utilis� pour toutes les requ�tes envoy�es par ce QNetworkAccessManager. Il peut �tre n�cessaire de s�lectionner des proxy diff�rents suivat le type de requ�te envoy�e ou l'h�te de destination ; dans ce cas, vous devriez envisager d'utiliser setProxyFactory().

Voir aussi proxy() et proxyAuthenticationRequired().

void QNetworkAccessManager::setProxyFactory ( QNetworkProxyFactory * factory )

La proxy factory (fabrique de proxy) de cet objet devient factory. La proxy factory permet de d�terminer une liste sp�cifique de proxy � utiliser pour une requ�te donn�e, au lieu d'utiliser le m�me proxy pour toutes les requ�tes.

Toutes les requ�tes envoy�es par le QNetworkAccessManager seront du type QNetworkProxyQuery::UrlRequest.

Par exemple, une fabrique de proxy pourrait appliquer les r�gles suivantes :

• si l'adresse de destination fait partie du r�seau local (par exemple, si le nom d'h�te ne contient pas de point ou s'il s'agit d'une adresse IP interne de l'organisation), renvoyer QNetworkProxy::NoProxy ;
• si la requ�te est FTP, renvoyer un proxy FTP ;
• si la requ�te est HTTP ou HTTPS, renvoyer un proxy HTTP ;
• sinon, renvoyer un serveur proxy SOCKSv5.

L'existence de factory sera g�r�e par le QNetworkAccessManager. Il d�truira l'objet au moment opportun.

Note : si un proxy est fix� par setProxy(), factory ne sera pas utilis�.

Cette fonction a �t� introduite dans Qt 4.5.

Voir aussi proxyFactory(), setProxy() et QNetworkProxyQuery.

void QNetworkAccessManager::sslErrors ( QNetworkReply * reply, const QList<QSslError> & errors ) [signal]

Ce signal est �mis si la session SSL/TLS a rencontr� des erreurs pendant son initialisation, y compris des erreurs de v�rification de certificat. Le param�tre errors contient la liste des erreurs et reply est le QNetworkReply qui a rencontr� ces erreurs.

Pour indiquer que les erreurs ne sont pas fatales et que la connexion peut continuer, la fonction QNetworkReply::ignoreSslErrors() doit �tre appel�e depuis le slot connect� � ce signal. Si elle n'est pas appel�e, la session SSL sera stopp�e avant qu'aucune donn�e ne soit �chang�e (y compris l'URL).

Ce signal peut �tre utilis� pour afficher un message d'erreur � l'utilisateur indiquant que la s�curit� peut �tre compromise et afficher la configuration SSL (voir sslConfiguration() pour l'obtenir). Si l'utilisateur d�cide de continuer apr�s avoir analys� le certificat re�u, le slot doit appeler ignoreSslErrors().

Voir aussi QSslSocket::sslErrors(), QNetworkReply::sslErrors(), QNetworkReply::sslConfiguration() et QNetworkReply::ignoreSslErrors().

Remerciements

Merci � Ilya Diallo pour la traduction et � Thibaut Cuvelier ainsi qu'� Claude Leloup pour leur relecture !