Différences entre les versions de WinHTTP
En général, les titres du Microsoft Game Development Kit (GDK) interagissent avec WinHTTP de la même façon que les applications Win32. Lors du développement de titres du Microsoft Game Development Kit (GDK), seule l’API C/C++ plate de WinHTTP est disponible. Cela signifie que les fonctionnalités HTTP doivent être construites sur cette API cliente HTTP.Ajouter WinHTTP à votre projet de console XBOX
Sur console, vous devez utiliser#include <winhttp.h> dans vos fichiers sources. Vous devez effectuer l’édition de liens avec XGamePlatform.lib plutôt que directement avec Winhttp.lib. Seules les API de la famille d’API WINAPI_PARTITION_GAMES fonctionnent dans les titres du Microsoft Game Development Kit (GDK). Sur PC Windows, vous devez continuer à effectuer l’édition de liens avec Winhttp.lib.
Pour obtenir un exemple d’intégration de WinHTTP dans votre titre du Microsoft Game Development Kit (GDK), consultez l’exemple SimpleWinHttp. Il constitue un bon point de départ pour votre propre implémentation de WinHTTP et inclut la classe WinHttpManager. Celle-ci expose une surface d’API asynchrone simple.
Initialisation du réseau et WinHTTP
Avant que votre titre n’effectue le premier appel à WinHttpOpen, les titres du Microsoft Game Development Kit (GDK) doivent s’assurer que la pile réseau est initialisée. SiWinHttpOpen est appelée trop tôt pendant le processus de lancement du titre, WinHttpOpen ou les appels WinHTTP suivants peuvent échouer ou planter de manière non déterministe. Avant que le réseau ne soit déclaré comme initialisé, des requêtes peuvent sembler réussir alors qu’elles échouent en réalité, ou inversement. Pour savoir comment déterminer quand la pile réseau est initialisée, consultez Initialisation du réseau.
Suspension et reprise du titre et WinHTTP
Les titres doivent lancer le processus de fermeture de tous les handles WinHTTP lorsqu’une notification de suspension du titre est reçue. Le nettoyage des handles WinHTTP est asynchrone. Par conséquent, vous devez fermer vos handles dans l’ordre suivant : tous les handles de requête, puis tous les handles de connexion, puis tous les handles de session. La nature asynchrone du nettoyage des handles WinHTTP vise à garantir la sécurité des threads de notification. Bien qu’il soit asynchrone, le nettoyage des handles WinHTTP n’introduit aucun délai, ce qui lui permet de s’inscrire facilement dans le délai de report de suspension d’une seconde. Lors de la reprise, les titres doivent suivre la même procédure que celle décrite dans la section précédente, Initialisation du réseau et WinHTTP, et attendre que le réseau revienne à l’état prêt avant de continuer à utiliser WinHTTP. Une longue période peut s’être écoulée entre les événements de suspension et de reprise, ce qui oblige le réseau à se stabiliser à nouveau avant que les API WinHTTP ne redeviennent déterministes.Considérations relatives à la mémoire et à la concurrence
Le nombre de requêtes WinHTTP simultanées doit toujours rester inférieur à huit pour garantir que l’état asynchrone de WinHTTP fonctionne correctement et dans les limites de son budget mémoire. Cette limite s’applique à toutes les opérations simultanées au sein du runtime du titre, y compris les appels provenant des API des services XBOX et deXCurl.
En complément des considérations relatives à la mémoire de WinSock, lors de la réception de données, vous devez toujours disposer d’une mémoire tampon en attente avec WinHttpReadData (ou attendre un rappel d’un appel à WinHttpQueryDataAvailable) afin de transférer les données des pools de mémoire en mode noyau vers votre processus en mode utilisateur aussi rapidement que possible et de minimiser la quantité de mémoire noyau consommée par votre opération HTTP.
La fonction d’accès WinHttpQueryHeaders nécessite des allocations de mémoire temporaires. Elle alloue, pour un usage interne, une mémoire tampon de travail de taille égale au paramètre lpdwBufferLength (et la libère avant le retour de la fonction). C’est pourquoi vous devez utiliser le modèle de double appel WINHTTP_NO_OUTPUT_BUFFER pour minimiser la taille des mémoires tampons de travail, et limiter le nombre d’appels simultanés à WinHttpQueryHeaders afin d’éviter une utilisation excessive de la mémoire système susceptible d’entraîner une instabilité du système. La taille maximale par défaut des en-têtes est de 64 Ko, comme spécifié par l’option WinHTTP WINHTTP_OPTION_MAX_RESPONSE_HEADER_SIZE.
Considérations relatives à WinHttpOpen
Indicateurs
Vous devez passer les indicateurs du tableau suivant à WinHttpOpen.
La combinaison de
WINHTTP_ACCESS_TYPE_AUTOMATIC_PROXY, WINHTTP_NO_PROXY_NAME et WINHTTP_NO_PROXY_BYPASS permet à la plateforme du Microsoft Game Development Kit (GDK) de gérer automatiquement les proxys tels que Fiddler et d’autres environnements réseau atypiques.
L’indicateur WINHTTP_FLAG_SECURE_DEFAULTS est un nouvel indicateur conçu pour aider les titres du Microsoft Game Development Kit (GDK) à respecter les bonnes pratiques de sécurité en définissant le comportement de connexion sécurisée recommandé. Il est disponible sur les consoles XBOX One et le sera sur PC Windows dans une future mise à jour du système d’exploitation Windows. Tenter de passer WINHTTP_FLAG_SECURE_DEFAULTS sur les versions existantes du système d’exploitation Windows entraîne un échec pour paramètre non valide. Cet indicateur a un effet secondaire important : il force WinHTTP en mode asynchrone, car il inclut implicitement l’indicateur WINHTTP_FLAG_ASYNC. Sur les versions du système d’exploitation Windows pour PC qui ne prennent pas en charge cet indicateur, vous devez passer WINHTTP_FLAG_ASYNC à la place afin de minimiser les différences dans le reste de votre implémentation WinHTTP.
L’indicateur
WINHTTP_FLAG_SECURE_DEFAULTS nécessite qu’un indicateur WINHTTP_FLAG_SECURE correspondant soit passé à WinHttpOpenRequest et bloque les requêtes HTTP non chiffrées. Sur les kits de développement, à des fins de débogage et de test internes, vous pouvez créer un handle de session WinHTTP et spécifier l’indicateur WINHTTP_FLAG_ASYNC pour WinHttpOpen. Cet indicateur vous permet d’effectuer une requête HTTP non chiffrée pendant le développement en ne spécifiant pas l’indicateur WINHTTP_FLAG_SECURE pour WinHttpOpenRequest. Vous devez néanmoins utiliser des handles de session ouverts avec WINHTTP_FLAG_SECURE_DEFAULTS pour le trafic hors débogage afin de reproduire le comportement des requêtes que votre titre rencontre en RETAIL.WINHTTP_OPTION_SECURE_PROTOCOLS
Après avoir créé un nouveau handle de session avecWinHttpOpen, vous devez appeler WinHttpSetOption avec l’option WINHTTP_OPTION_SECURE_PROTOCOLS et passer la valeur XNetworkingSecurityInformation::enabledHttpSecurityProtocolFlags correspondante, récupérée par un appel à XNetworkingQuerySecurityInformationForUrlUtf16Async pour une URL correspondant à celle pour laquelle ce handle de session sera utilisé. Vous devez également stocker la structure XNetworkingSecurityInformation dans votre objet de contexte pour l’utiliser ultérieurement lors de la validation de la négociation TLS/SSL.
Mise en cache des handles de session
Les handles de session HTTP créés viaWinHttpOpen sont coûteux en mémoire et entraînent un coût de démarrage important qui retarde la première requête HTTP. Nous vous recommandons de mettre en cache les handles de session HTTP autant que possible dans votre titre afin d’éviter ces coûts.
Toutefois, il n’est pas possible de modifier l’option WINHTTP_OPTION_SECURE_PROTOCOLS sur un handle de session. Vous devez conserver un cache de valeurs XNetworkingSecurityInformation::enabledHttpSecurityProtocolFlags associées aux handles de session WinHTTP afin de disposer d’un handle de session différent pour chaque indicateur de protocole sécurisé différent.
Le cache que gère votre titre doit être vidé lors des notifications de suspension et doit être entièrement reconstruit lors de la reprise (après avoir attendu que le réseau soit initialisé).
Considérations relatives à WinHttpConnect
Contrairement aux handles de session, les handles de connexion créés via WinHttpConnect ne doivent jamais être mis en cache. De nouveaux handles doivent être créés pour chaque nouvelle requête et/ou nouvelle tentative. Malgré leur nom, les handles de connexion WinHTTP n’ont aucun rapport avec les connexions TCP (Transmission Control Protocol) sous-jacentes au serveur. WinHTTP gère la durée de vie des connexions sous-jacentes au serveur avec le handle de session et réutilise automatiquement les connexions ouvertes au serveur lorsque c’est possible pour les nouveaux handles de connexion.Canonisation des URL
WinHTTP s’attend à ce que toutes les URL soient canonisées en caractères US-ASCII a-z, A-Z et 0-9. Pour plus d’informations sur la canonisation, consultez Uniform Resource Locators (URL) dans WinHTTP. Dans la mesure du possible, nous vous recommandons de coder en dur les URL utilisées par votre titre sous leur forme canonique. Cette forme évite les allocations de mémoire et les problèmes de performances liés à l’utilisation des fonctions WinHttpCrackUrl et WinHttpCreateUrl pour canoniser dynamiquement vos URL.Fractionnement des URL
WinHTTP exige qu’une chaîne de nom d’hôte terminée par un caractère null soit passée àWinHttpConnect, tandis que le chemin et l’objet sont passés à WinHttpOpenRequest. Votre titre doit passer l’URL complète, c’est-à-dire la concaténation du nom d’hôte et du chemin, à certains endroits, et uniquement le nom d’hôte ou le chemin à d’autres. Nous vous recommandons de coder en dur les deux dans votre titre afin d’éviter d’avoir à utiliser WinHttpCrackUrl et WinHttpCreateUrl pour concaténer ou fractionner dynamiquement les URL.
Considérations relatives à WinHttpOpenRequest
Comme les handles de connexion WinHTTP, les handles de requête WinHTTP créés via la fonction WinHttpOpenRequest ne doivent jamais être mis en cache. De nouveaux handles doivent être créés pour chaque nouvelle requête et/ou nouvelle tentative. Par bonne pratique de sécurité, les titres doivent toujours passer l’indicateurWINHTTP_FLAG_SECURE pour le paramètre dwFlags lors de l’appel à la fonction WinHttpOpenRequest.
Récupération et application des jetons des services XBOX
Les jetons ne sont pas insérés automatiquement pour les titres du Microsoft Game Development Kit (GDK). Le titre doit plutôt récupérer les jetons et signatures d’authentification des services XBOX à l’aide des API XUser du Microsoft Game Development Kit (GDK). Une fois que le titre dispose d’un utilisateur, il doit appeler XUserGetTokenAndSignatureUtf16Async pour récupérer les chaînes de jeton et de signature pour chaque requête. Ces deux chaînes doivent ensuite être passées sous forme d’en-têtes dans l’appel àWinHttpAddRequestHeadersEx, WinHttpSendRequest ou WinHttpAddRequestHeaders.
Pour générer une signature correcte, XUserGetTokenAndSignatureUtf16Async s’attend à ce que le titre passe tous les en-têtes et l’intégralité du corps. Pour un POST ou un PUT avec un corps volumineux, le titre peut passer un sous-ensemble du corps configuré dans l’Espace partenaires. Pour plus d’informations, consultez Services web (rubrique sous NDA). Pour l’instant, le réseau XBOX ne fournit aucun mécanisme permettant de récupérer cette configuration. Les clients doivent soit coder les valeurs en dur, soit les récupérer via un point de terminaison personnalisé propre au titre.
XUserGetTokenAndSignatureUtf16Async effectue en interne toute la mise en cache nécessaire et doit être appelée pour chaque tentative HTTP, y compris les nouvelles tentatives. Si le titre reçoit un code d’état de réponse HTTP 401 Unauthorized pour une requête HTTP quelconque, il doit relancer la requête et forcer l’actualisation du jeton d’authentification des services XBOX. Cette actualisation s’effectue en récupérant un nouveau jeton avec XUserGetTokenAndSignatureUtf16Async et en passant la valeur d’énumération XUserGetTokenAndSignatureOptions::ForceRefresh.
Une fois que le titre dispose de XUserGetTokenAndSignatureUtf16Data, récupérée par un appel à XUserGetTokenAndSignatureUtf16Async, il doit transformer XUserGetTokenAndSignatureUtf16Data::Token et XUserGetTokenAndSignatureUtf16Data::Signature en en-têtes HTTP à passer à WinHTTP. Une nouvelle API WinHTTP, WinHttpAddRequestHeadersEx, a été ajoutée spécifiquement pour réduire la complexité pour les titres du Microsoft Game Development Kit (GDK). Un exemple d’utilisation de cette nouvelle API est présenté ci-dessous. Cette nouvelle API est disponible sur les consoles XBOX One et le sera sur PC Windows dans une future mise à jour du système d’exploitation Windows. Sur console, nous vous recommandons d’utiliser WinHttpAddRequestHeadersEx pour éviter les allocations supplémentaires et les modifications de format de chaîne.
L’appareil ou un compte connecté doit avoir accès au sandbox sur lequel il est configuré. Sinon,
XUserGetTokenAndSignatureUtf16Data échoue.Utilisation de la liste d’autorisation de sécurité réseau XBOX (NSAL)
Le réseau XBOX utilise la NSAL pour garantir que les clients établissent des connexions sécurisées et authentifiées à vos services web. Les titres gèrent le contenu de la NSAL dans le cadre de leur configuration dans l’Espace partenaires. Pour plus d’informations, consultez Configuration des services web dans l’Espace partenaires (rubrique sous NDA). La configuration de la NSAL est ensuite téléchargée automatiquement pour chaque titre. Elle est utilisée à la fois pour générer les jetons des services XBOX appropriés et pour effectuer l’épinglage de certificats pour les points de terminaison propres à votre titre.}Considérations relatives à la machine à états asynchrone de WinHTTP
La machine à états asynchrone de WinHTTP est la même sur console que sur PC Windows. Pour inscrire une fonction de rappel auprès d’une ou plusieurs notifications, utilisez la fonction WinHttpSetStatusCallback. Nous recommandons d’utiliser l’indicateurWINHTTP_CALLBACK_FLAG_ALL_NOTIFICATIONS pour le paramètre dwNotificationFlags à des fins de débogage, car WinHTTP est relativement détaillé et transparent sur ce qu’il fait. Bien que la plupart des notifications ne nécessitent aucune action de votre part, la journalisation des données peut être utile pour découvrir la cause racine des problèmes.
WinHTTP utilise un seul thread pour les notifications. Les titres doivent éviter autant que possible de bloquer une fonction de notification, car cela empêche la progression de toutes les requêtes HTTP au sein de votre processus. Les notifications non traitées peuvent également augmenter la mémoire en mode noyau, ce qui peut entraîner des plantages.
WinHTTP ne copie pas vos mémoires tampons d’envoi ou de réception et exige que vous les mainteniez allouées jusqu’au rappel d’achèvement correspondant. Veillez à maintenir vos mémoires tampons d’envoi allouées et valides à partir du moment où vous appelez WinHttpSendRequest jusqu’à la réception de la notification WINHTTP_CALLBACK_STATUS_SENDREQUEST_COMPLETE correspondante. De même, chaque fois que vous appelez WinHttpReadData, veillez à maintenir votre mémoire tampon de réception allouée et valide jusqu’à la réception de la notification WINHTTP_CALLBACK_STATUS_READ_COMPLETE correspondante. Nous recommandons également d’utiliser une mémoire tampon de réception d’au moins 8 Ko afin d’éviter les problèmes de récursivité pouvant entraîner un épuisement de la pile.
Les titres doivent également s’assurer que les mémoires tampons WinHTTP sont correctement vidées en poursuivant le cycle asynchrone WinHttpQueryDataAvailable/WinHttpReadData et en ne bloquant jamais les rappels WinHTTP.
Validation de la négociation TLS (Transport Layer Security)/SSL (Secure Sockets Layer)
Par bonne pratique de sécurité, les titres doivent valider la négociation TLS/SSL et utiliser uniquement TLS 1.2. Une validation supplémentaire est effectuée dans la notificationWINHTTP_CALLBACK_STATUS_SENDING_REQUEST. Dans cette notification, vous devez appeler la fonction XNetworkingVerifyServerCertificate et lui passer la structure XNetworkingSecurityInformation récupérée lors d’un appel correspondant précédent à XNetworkingQuerySecurityInformationForUrlUtf16Async. Cette fonction échoue si la chaîne de certificats n’est pas valide. Vous devez alors fermer immédiatement le handle WinHTTP avant la fin du rappel afin de garantir qu’aucune donnée n’est transférée vers ou depuis le serveur compromis.
En plus de valider les chaînes de certificats, la fonction XNetworkingVerifyServerCertificate est requise pour le fonctionnement de Fiddler sur console.
Débogage de WinHTTP
Fiddler est un outil utile pour afficher et déboguer votre trafic WinHTTP. Pour que Fiddler capture le trafic de votre titre, vous devez passer les indicateursWINHTTP_ACCESS_TYPE_AUTOMATIC_PROXY, WINHTTP_NO_PROXY_NAME et WINHTTP_NO_PROXY_BYPASS à WinHttpOpen. Vous devez également appeler XNetworkingVerifyServerCertificate dans le rappel de la notification WINHTTP_CALLBACK_STATUS_SENDING_REQUEST.
HTTP Monitor ne fonctionne pas avec les titres du Microsoft Game Development Kit (GDK).
Documentation de référence de l’API
- Xuser (contenu de l’API)
- Fonctions
- Structures
- xnetworking (contenu de l’API)