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 !