WinHttpSetStatusCallback, fonction (winhttp.h)

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.

[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.

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é.

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

Voir aussi

À propos des services HTTP Microsoft Windows (WinHTTP)

WINHTTP_STATUS_CALLBACK

WinHTTP Versions

WinHttpConnect

WinHttpOpen