WINHTTP_STATUS_CALLBACK fonction de rappel (winhttp.h)

Le type WINHTTP_STATUS_CALLBACK représente une fonction de rappel d’état définie par l’application.

Syntaxe

WINHTTP_STATUS_CALLBACK WinhttpStatusCallback;

void WinhttpStatusCallback(
  [in] HINTERNET hInternet,
  [in] DWORD_PTR dwContext,
  [in] DWORD dwInternetStatus,
  [in] LPVOID lpvStatusInformation,
  [in] DWORD dwStatusInformationLength
)
{...}

Paramètres

[in] hInternet

Handle pour lequel la fonction de rappel est appelée.

[in] dwContext

Pointeur vers un DWORD qui spécifie la valeur de contexte définie par l’application associée au handle dans le paramètre hInternet .

Une valeur de contexte peut être attribuée à un handle Session, Connect ou Request en appelant WinHttpSetOption avec l’option WINHTTP_OPTION_CONTEXT_VALUE . Vous pouvez également utiliser WinHttpSendRequest pour associer une valeur de contexte à un handle de requête.

[in] dwInternetStatus

Pointe vers un DWORD qui spécifie le code d’état qui indique la raison pour laquelle la fonction de rappel est appelée. Il peut s’agir de l’une des valeurs suivantes :

WINHTTP_CALLBACK_STATUS_CLOSING_CONNECTION

Fermeture de la connexion au serveur. Le paramètre lpvStatusInformation est NULL.

WINHTTP_CALLBACK_STATUS_CONNECTED_TO_SERVER

Connexion réussie au serveur. Le paramètre lpvStatusInformation contient un pointeur vers un LPWSTR qui indique l’adresse IP du serveur en notation pointillée.

WINHTTP_CALLBACK_STATUS_CONNECTING_TO_SERVER

Connexion au serveur. Le paramètre lpvStatusInformation contient un pointeur vers un LPWSTR qui indique l’adresse IP du serveur en notation pointillée.

WINHTTP_CALLBACK_STATUS_CONNECTION_CLOSED

La connexion au serveur a été fermée. Le paramètre lpvStatusInformation est NULL.

WINHTTP_CALLBACK_STATUS_DATA_AVAILABLE

Les données peuvent être récupérées avec WinHttpReadData. Le paramètre lpvStatusInformation pointe vers un DWORD qui contient le nombre d’octets de données disponibles. Le paramètre dwStatusInformationLength lui-même est 4 (la taille d’un DWORD).

WINHTTP_CALLBACK_STATUS_HANDLE_CREATED

Un handle HINTERNET a été créé. Le paramètre lpvStatusInformation contient un pointeur vers le handle HINTERNET .

WINHTTP_CALLBACK_STATUS_HANDLE_CLOSING

Cette valeur de handle a été arrêtée. Le paramètre lpvStatusInformation contient un pointeur vers le handle HINTERNET . Il n’y aura plus de rappels pour ce handle.

WINHTTP_CALLBACK_STATUS_HEADERS_AVAILABLE

L’en-tête de réponse a été reçu et est disponible avec WinHttpQueryHeaders. Le paramètre lpvStatusInformation est NULL.

WINHTTP_CALLBACK_STATUS_INTERMEDIATE_RESPONSE

Reçu un message de code d’état intermédiaire (niveau 100) du serveur. Le paramètre lpvStatusInformation contient un pointeur vers un DWORD qui indique le code d’état.

WINHTTP_CALLBACK_STATUS_NAME_RESOLVED

L’adresse IP du serveur a été trouvée. Le paramètre lpvStatusInformation contient un pointeur vers un LPWSTR qui indique le nom qui a été résolu.

WINHTTP_CALLBACK_STATUS_READ_COMPLETE

Les données ont été correctement lues à partir du serveur. Le paramètre lpvStatusInformation contient un pointeur vers la mémoire tampon spécifiée dans l’appel à WinHttpReadData. Le paramètre dwStatusInformationLength contient le nombre d’octets lus.

Lorsqu’il est utilisé par WinHttpWebSocketReceive, le paramètre lpvStatusInformation contient un pointeur vers une structure WINHTTP_WEB_SOCKET_STATUS , et le paramètre dwStatusInformationLength indique la taille de lpvStatusInformation.

WINHTTP_CALLBACK_STATUS_RECEIVING_RESPONSE

En attendant que le serveur réponde à une demande. Le paramètre lpvStatusInformation est NULL.

WINHTTP_CALLBACK_STATUS_REDIRECT

Une requête HTTP est sur le point de rediriger automatiquement la requête. Le paramètre lpvStatusInformation contient un pointeur vers un LPWSTR indiquant la nouvelle URL. À ce stade, l’application peut lire toutes les données retournées par le serveur avec la réponse de redirection et interroger les en-têtes de réponse. Il peut également annuler l’opération en fermant le handle.

WINHTTP_CALLBACK_STATUS_REQUEST_ERROR

Une erreur s’est produite lors de l’envoi d’une requête HTTP. Le paramètre lpvStatusInformation contient un pointeur vers une structure WINHTTP_ASYNC_RESULT . Son membre dwResult indique l’ID de la fonction appelée et dwError indique la valeur de retour.

WINHTTP_CALLBACK_STATUS_REQUEST_SENT

Envoi réussi de la demande d’informations au serveur. Le paramètre lpvStatusInformation contient un pointeur vers un DWORD indiquant le nombre d’octets envoyés.

WINHTTP_CALLBACK_STATUS_RESOLVING_NAME

Recherche de l’adresse IP d’un nom de serveur. Le paramètre lpvStatusInformation contient un pointeur vers le nom du serveur en cours de résolution.

WINHTTP_CALLBACK_STATUS_RESPONSE_RECEIVED

Le serveur a reçu une réponse. Le paramètre lpvStatusInformation contient un pointeur vers un DWORD indiquant le nombre d’octets reçus.

WINHTTP_CALLBACK_STATUS_SECURE_FAILURE

Une ou plusieurs erreurs ont été rencontrées lors de l’établissement d’une connexion sécurisée (HTTPS) au serveur. Le paramètre lpvStatusInformation contient un pointeur vers un DWORD qui est une combinaison de valeurs d’erreur au niveau du bit-OR. Pour plus d’informations, consultez la description de lpvStatusInformation.

WINHTTP_CALLBACK_STATUS_SENDING_REQUEST

Envoi de la demande d’informations au serveur. Le paramètre lpvStatusInformation est NULL.

WINHTTP_CALLBACK_STATUS_SENDREQUEST_COMPLETE

La demande s’est terminée avec succès. Le paramètre lpvStatusInformation est la valeur lpOptional passée à WinHttpSendRequest (le corps de la requête initiale), et le paramètre dwStatusInformationLength indique le nombre d’octets de corps initiaux correctement écrits (la valeur dwOptionalLength passée à WinHttpSendRequest).

WINHTTP_CALLBACK_STATUS_WRITE_COMPLETE

Les données ont été écrites avec succès sur le serveur. Le paramètre lpvStatusInformation contient un pointeur vers un DWORD qui indique le nombre d’octets écrits.

Lorsqu’il est utilisé par WinHttpWebSocketSend, le paramètre lpvStatusInformation contient un pointeur vers une structure WINHTTP_WEB_SOCKET_STATUS , et le paramètre dwStatusInformationLength indique la taille de lpvStatusInformation.

WINHTTP_CALLBACK_STATUS_GETPROXYFORURL_COMPLETE

L’opération initiée par un appel à WinHttpGetProxyForUrlEx est terminée. Les données peuvent être récupérées avec WinHttpReadData.

WINHTTP_CALLBACK_STATUS_CLOSE_COMPLETE

La connexion a été correctement fermée via un appel à WinHttpWebSocketClose. Le paramètre lpvStatusInformation est NULL.

WINHTTP_CALLBACK_STATUS_SHUTDOWN_COMPLETE

La connexion a été correctement arrêtée via un appel à WinHttpWebSocketShutdown. Le paramètre lpvStatusInformation est NULL.

[in] lpvStatusInformation

Pointeur vers une mémoire tampon qui spécifie les informations pertinentes pour cet appel à la fonction de rappel. Le format de ces données dépend de la valeur de l’argument dwInternetStatus . Pour plus d’informations, consultez dwInternetStatus.

Si l’argument dwInternetStatus est WINHTTP_CALLBACK_STATUS_SECURE_FAILURE, lpvStatusInformation pointe vers un DWORD qui est une combinaison OR au niveau du bit d’une ou plusieurs des valeurs suivantes.

[in] dwStatusInformationLength

WINHTTP_CALLBACK_STATUS_REDIRECT rappels d’état fournissent une valeur dwStatusInformationLength qui correspond au nombre de caractères du LPWSTR pointé par lpvStatusInformation.

Valeur de retour

None

Remarques

La fonction de rappel doit être threadsafe et réentrante, car elle peut être appelée sur un autre thread pour une demande distincte, puis réinscrite sur le même thread pour la requête actuelle. Il doit donc être codé pour gérer la réentrance en toute sécurité pendant le traitement. Lorsque le paramètre dwInternetStatus est égal à WINHTTP_CALLBACK_STATUS_HANDLE_CLOSING, le rappel n’a pas besoin d’être en mesure de gérer la réentrance pour la même demande, car ce rappel est garanti comme étant le dernier et ne se produit pas lorsque d’autres messages de cette demande sont gérés.

La fonction de rappel d’état reçoit des mises à jour sur l’état des opérations asynchrones via des indicateurs de notification. Les notifications qui indiquent qu’une opération particulière est terminée sont appelées notifications d’achèvement, ou simplement achèvements. Le tableau suivant répertorie les six indicateurs d’achèvement et la fonction correspondante qui est terminée lorsque cet indicateur est reçu.

Étant donné que les rappels sont effectués pendant le traitement de la demande, l’application doit consacrer le moins de temps possible à la fonction de rappel pour éviter de dégrader le débit des données sur le réseau. Par exemple, l’affichage d’une boîte de dialogue dans une fonction de rappel peut être une opération tellement longue que le serveur met fin à la demande.

La fonction de rappel peut être appelée dans un contexte de thread différent du thread qui a lancé la demande.

De même, il n’existe aucune affinité de thread de rappel lorsque vous appelez WinHttp de manière asynchrone : un appel peut commencer à partir d’un thread, mais n’importe quel autre thread peut recevoir le rappel.

Configuration requise

Voir aussi

WinHTTP Versions

WinHttpSetStatusCallback