WinHttpSetStatusCallback, fonction (winhttp.h)

Article
08/27/2023

La fonction WinHttpSetStatusCallback configure une fonction de rappel que WinHTTP peut appeler au fur et à mesure de la progression d’une opération.

Syntaxe

WINHTTPAPI WINHTTP_STATUS_CALLBACK WinHttpSetStatusCallback(
  [in] HINTERNET               hInternet,
  [in] WINHTTP_STATUS_CALLBACK lpfnInternetCallback,
  [in] DWORD                   dwNotificationFlags,
  [in] DWORD_PTR               dwReserved
);

Paramètres

[in] hInternet

Handle HINTERNET pour lequel le rappel doit être défini.

[in] lpfnInternetCallback

Pointeur vers la fonction de rappel à appeler lorsque la progression est effectuée. Définissez cette valeur sur NULL pour supprimer la fonction de rappel existante. Pour plus d’informations sur la fonction de rappel, consultez WINHTTP_STATUS_CALLBACK.

[in] dwNotificationFlags

Valeur entière longue non signée qui spécifie des indicateurs pour indiquer les événements qui activent la fonction de rappel.

Les valeurs possibles sont les suivantes.

Valeur	Signification
WINHTTP_CALLBACK_FLAG_ALL_COMPLETIONS	S’active lors de toute notification d’achèvement. Cet indicateur spécifie que toutes les notifications requises pour les opérations de lecture ou d’écriture sont utilisées. Consultez WINHTTP_STATUS_CALLBACK pour obtenir la liste des achèvements.
WINHTTP_CALLBACK_FLAG_ALL_NOTIFICATIONS	S’active sur n’importe quelle notification de modification status, y compris les achèvements. Consultez WINHTTP_STATUS_CALLBACK pour obtenir la liste des notifications.
WINHTTP_CALLBACK_FLAG_RESOLVE_NAME	S’active au début et à la fin de la résolution de noms.
WINHTTP_CALLBACK_FLAG_CONNECT_TO_SERVER	S’active au début et à la fin de la connexion au serveur.
WINHTTP_CALLBACK_FLAG_DETECTING_PROXY	S’active lors de la détection du serveur proxy.
WINHTTP_CALLBACK_FLAG_DATA_AVAILABLE	S’active lors de l’exécution d’une requête de données.
WINHTTP_CALLBACK_FLAG_HEADERS_AVAILABLE	S’active lorsque les en-têtes de réponse sont disponibles pour la récupération.
WINHTTP_CALLBACK_FLAG_READ_COMPLETE	S’active à la fin d’une opération de lecture de données.
WINHTTP_CALLBACK_FLAG_REQUEST_ERROR	S’active lorsqu’une erreur asynchrone se produit.
WINHTTP_CALLBACK_FLAG_SEND_REQUEST	Active au début et à la fin de l’envoi d’un en-tête de requête avec WinHttpSendRequest.
WINHTTP_CALLBACK_FLAG_SENDREQUEST_COMPLETE	S’active lorsqu’un en-tête de requête a été envoyé avec WinHttpSendRequest.
WINHTTP_CALLBACK_FLAG_WRITE_COMPLETE	S’active à la fin d’une opération de publication de données.
WINHTTP_CALLBACK_FLAG_RECEIVE_RESPONSE	S’active au début et à la fin de la réception d’une ressource à partir du serveur HTTP.
WINHTTP_CALLBACK_FLAG_CLOSE_CONNECTION	S’active lors du début et de la fin de la fermeture d’une connexion HTTP.
WINHTTP_CALLBACK_FLAG_HANDLES	S’active lorsqu’un handle HINTERNET est créé ou fermé.
WINHTTP_CALLBACK_FLAG_REDIRECT	S’active lorsque la requête est redirigée.
WINHTTP_CALLBACK_FLAG_INTERMEDIATE_RESPONSE	S’active lors de la réception d’un message de code intermédiaire (niveau 100) status du serveur.
WINHTTP_CALLBACK_FLAG_SECURE_FAILURE	S’active en cas d’échec de connexion sécurisée.

[in] dwReserved

Ce paramètre est réservé et doit être NULL.

Valeur retournée

En cas de réussite, retourne un pointeur vers la fonction de rappel status précédemment définie ou null s’il n’y avait pas de fonction de rappel définie précédemment status. Retourne WINHTTP_INVALID_STATUS_CALLBACK si la fonction de rappel n’a pas pu être installée. Pour obtenir des informations d’erreur étendues, appelez GetLastError. Parmi les codes d’erreur retournés figurent les suivants.

Code d'erreur	Description
ERROR_WINHTTP_INCORRECT_HANDLE_TYPE	Le type de handle fourni est incorrect pour cette opération.
ERROR_WINHTTP_INTERNAL_ERROR	Une erreur interne s'est produite.
ERROR_NOT_ENOUGH_MEMORY	La mémoire disponible était insuffisante pour terminer l’opération demandée. (Code d’erreur Windows)

Remarques

Si vous définissez le rappel sur le handle de session avant de créer le handle de requête, le handle de requête hérite du pointeur de la fonction de rappel de sa session parente.

Même lorsque WinHTTP est utilisé en mode asynchrone (autrement dit, quand WINHTTP_FLAG_ASYNC a été défini dans WinHttpOpen), cette fonction fonctionne de manière synchrone. La valeur de retour indique la réussite ou l’échec. Pour obtenir des informations détaillées sur l’erreur, appelez GetLastError.

Les fonctions synchrones et asynchrones utilisent la fonction de rappel pour indiquer la progression de la demande, comme la résolution d’un nom, la connexion à un serveur, etc. La fonction de rappel est requise pour une opération asynchrone.

Une fonction de rappel peut être définie sur n’importe quel handle et est héritée par les handles dérivés. Une fonction de rappel peut être modifiée à l’aide de WinHttpSetStatusCallback, à condition qu’aucune demande en attente n’ait besoin d’utiliser la valeur de rappel précédente. Toutefois, la modification de la fonction de rappel sur un handle ne modifie pas les rappels sur les handles dérivés, tels que ceux retournés par WinHttpConnect. Vous devez modifier la fonction de rappel à chaque niveau.

De nombreuses fonctions WinHTTP effectuent plusieurs opérations sur le réseau. Chaque opération peut prendre du temps et chacune peut échouer.

Après avoir lancé la fonction WinHttpSetStatusCallback , la fonction de rappel est accessible à partir de WinHTTP pour surveiller les opérations réseau nécessitant beaucoup de temps.

À la fin du traitement asynchrone, l’application peut définir la fonction de rappel sur NULL. Cela empêche l’application cliente de recevoir des notifications supplémentaires.

L’extrait de code suivant montre la méthode recommandée pour définir la fonction de rappel sur NULL.

WinHttpSetStatusCallback( hOpen,
                          NULL,
                          WINHTTP_CALLBACK_FLAG_ALL_NOTIFICATIONS,
                          NULL );

Notez, toutefois, que WinHTTP ne synchronise pas WinHttpSetStatusCallback avec les threads de travail. Si un rappel provenant d’un autre thread est en cours lorsqu’une application appelle WinHttpSetStatusCallback, l’application reçoit toujours une notification de rappel même après que WinHttpSetStatusCallback a correctement défini la fonction de rappel sur NULL et retourné.

Note Pour Windows XP et Windows 2000, consultez la section Conditions requises pour l’exécution de la page de démarrage WinHttp.

Exemples

L’exemple suivant montre comment installer une fonction de rappel pour les fonctions WinHTTP asynchrones. L’exemple suppose qu’une fonction WINHTTP_STATUS_CALLBACK nommée « AsyncCallback( ) » a été implémentée précédemment :

    // Use WinHttpOpen to obtain an HINTERNET handle.
    HINTERNET hSession = WinHttpOpen(L"A WinHTTP Example Program/1.0", 
                                    WINHTTP_ACCESS_TYPE_DEFAULT_PROXY,
                                    WINHTTP_NO_PROXY_NAME, 
                                    WINHTTP_NO_PROXY_BYPASS, 0);
    if (hSession)
    {
        // Install the status callback function.
        WINHTTP_STATUS_CALLBACK isCallback = WinHttpSetStatusCallback( hSession,
                                               (WINHTTP_STATUS_CALLBACK)AsyncCallback,
                                               WINHTTP_CALLBACK_FLAG_ALL_NOTIFICATIONS, 
                                               NULL);
                                               
        // Place additional code here.
    
        // When finished, release the HINTERNET handle.
        WinHttpCloseHandle(hSession);
    }
    else
    {
        printf("Error %u in WinHttpOpen.\n", GetLastError());
    }

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Windows XP, Windows 2000 Professionnel avec SP3 [applications de bureau uniquement]
Serveur minimal pris en charge	Windows Server 2003, Windows 2000 Server avec SP3 [applications de bureau uniquement]
Plateforme cible	Windows
En-tête	winhttp.h
Bibliothèque	Winhttp.lib
DLL	Winhttp.dll
Composant redistribuable	WinHTTP 5.0 et Internet Explorer 5.01 ou version ultérieure sur Windows XP et Windows 2000.