Gestion des cookies dans WinHTTP

  • Article

Les données de session HTTP sont passées entre le client et le serveur dans l’en-tête de cookie de la demande ou de la réponse. Le serveur envoie des cookies au client dans l’en-tête Set-cookie de la réponse et l’API WinHTTP renvoie le cookie serveur au serveur dans l’en-tête de cookie de la demande. Les spécifications de gestion des cookies, décrites dans rfc 2109 (HTTP State Management Mechanism), sont implémentées par défaut dans WinHTTP. Les spécifications récentes de gestion des cookies, décrites dans rfc 2964, ne sont pas prises en charge par WinHTTP.

WinHTTP obtient le cookie à partir des serveurs Set-Cookie'en-tête et le stocke dans un cache par session. Ce cookie est renvoyé sur les requêtes suivantes dans la même session WinHTTP où la cible correspond à la source du cookie. L’API WinHTTP régénère l’en-tête de cookie de requête pour chaque étape de la demande.

La liste suivante décrit plusieurs options que les applications clientes WinHTTP peuvent utiliser pour gérer les cookies :

  • Gestion automatique des cookies : WinHTTP gère automatiquement les cookies et l’application cliente n’effectue aucune gestion des cookies personnalisée.
  • Désactiver la gestion automatique des cookies : la gestion automatique des cookies dans l’API WinHTTP est désactivée et aucun cookie n’est envoyé.
  • Spécifier manuellement tous les cookies : la gestion automatique des cookies est désactivée et l’application cliente ajoute ou supprime tous les en-têtes de cookies pour chaque requête dans la session.
  • Gestion manuelle et automatique des cookies : combinez la gestion automatique et manuelle des cookies.

Pour désactiver la gestion des cookies, l’application cliente WinHTTP appelle la fonction WinHttpSetOption avec le paramètre dwOption défini sur WINHTTP_OPTION_DISABLE_FEATURE et le paramètre lpBuffer défini sur WINHTTP_DISABLE_COOKIES. Le paramètre hInternet doit être un handle de requête. Lorsque la gestion des cookies est désactivée sur un handle de demande qui a envoyé une requête précédente, le client doit supprimer manuellement les en-têtes de cookie de requête existants avec la fonction WinHttpAddRequestHeaders avant d’envoyer la requête suivante. Pour plus d’informations, consultez Suppression des en-têtes de cookie.

Notes

L’application cliente doit définir tous les cookies sur la session une fois le mode automatique désactivé.

Spécification manuelle de tous les cookies

Lorsque la gestion automatique des cookies est désactivée, l’application cliente WinHTTP a la possibilité de spécifier manuellement tous les cookies. Pour définir manuellement le cookie, l’application appelle WinHttpAddRequestHeaders en spécifiant l’en-tête de cookie dans le paramètre pwszHeaders . L’application cliente doit effacer tous les en-têtes de cookie avant de renvoyer la demande.

L’application cliente doit également modifier l’en-tête de cookie lorsque la demande a été redirigée. Pour modifier le cookie sur les demandes redirigées, le client spécifie une fonction de rappel avec WinHttpSetStatusCallback qui répond au cas de rappel de redirection. Le gestionnaire de rappel doit effacer le cookie précédemment envoyé sur la demande en appelant WinHttpAddRequestHeaders. Pour plus d’informations sur la suppression des en-têtes de cookies, consultez Suppression des en-têtes de cookies.

Les applications clientes WinHTTP peuvent combiner le mécanisme de gestion automatique des cookies WinHTTP avec la gestion manuelle des cookies. L’application ajoute des cookies personnalisés à l’en-tête de cookie généré automatiquement avant d’envoyer la demande avec la fonction WinHttpSendRequest . Le cookie personnalisé doit être le premier en-tête de cookie dans la demande de mise en cache correcte du cookie par l’API WinHTTP. L’application cliente doit également supprimer les cookies envoyés sur les demandes précédentes avant de renvoyer une demande sur le même handle de demande. Pour plus d’informations, consultez Suppression des en-têtes de cookie.

Les cookies ajoutés à une demande avant l’appel à WinHttpSendRequest sont inclus dans toutes les requêtes WinHTTP envoyées pour le compte des appels WinHttpSendRequest et WinHttpReceiveResponse suivants. L’application cliente peut avoir besoin d’effacer l’en-tête de cookie lorsque la demande a été redirigée. Pour effacer le cookie sur les requêtes redirigées, le client spécifie une fonction de rappel avec WinHttpSetStatusCallback qui répond au cas de rappel de redirection. Le gestionnaire de rappel doit effacer le cookie précédemment envoyé sur la demande en appelant WinHttpAddRequestHeaders. La fonction de rappel peut ne pas définir de nouveaux cookies personnalisés sur le rappel de redirection. Le client doit attendre que WinHttpReceiveResponse se termine avant d’ajouter de nouveaux cookies pour le prochain appel WinHttpSendRequest .

L’application cliente WinHTTP peut avoir besoin d’effacer le cookie de demande existant avant de renvoyer une demande pour empêcher que les cookies qui ont été envoyés sur des requêtes précédentes soient à nouveau envoyés sur la demande actuelle . Pour plus d’informations, consultez la remarque suivante. Sachez également que les cookies n’ont pas besoin d’être effacés avant que la première demande soit envoyée sur le handle de demande. Le client peut effacer les cookies existants en appelant WinHttpAddRequestHeaders avec un en-tête de cookie vide dans le paramètre pwszHeaders et l’indicateur WINHTTP_ADDREQ_FLAG_REPLACE défini dans le paramètre dwModifier . L’exemple de code suivant montre comment effacer l’en-tête de cookie sur la demande.

WinHttpAddRequestHeaders(hRequest, 
                         L"Cookie:", 
                         -1, 
                         WINHTTP_ADDREQ_FLAG_REPLACE);

L’API WinHTTP a des comportements de gestion des cookies différents pour les versions du système d’exploitation antérieures à Windows XP avec Service Pack 2 (SP2) et Windows Server 2003 avec Service Pack 1 (SP1).

**Windows XP avec SP2 et versions ultérieures et Windows Server 2003 avec SP1 et versions ultérieures : **

L’API WinHTTP efface tous les cookies envoyés sur les demandes précédentes pour le handle de requête. Le client peut ajouter manuellement de nouveaux en-têtes de cookie avant chaque appel à WinHttpSendRequest. Si la fonctionnalité de gestion automatique des cookies de l’API WinHTTP n’a pas été désactivée, l’API WinHTTP ajoute le nouvel en-tête de cookie (ou ajoute un nouvel en-tête de cookie si l’application cliente n’en a pas ajouté manuellement) au cookie à partir du serveur.

**Windows XP avec SP2 et Windows Server 2003 avec SP1 : **

L’API WinHTTP n’efface pas l’en-tête de cookie de demande une fois WinHttpReceiveResponse terminé. Les cookies envoyés dans les requêtes précédentes seront renvoyés dans les appels suivants à WinHttpSendRequest. L’application cliente WinHTTP doit effacer les en-têtes de cookies existants avant de renvoyer une demande sur le handle de requête.