WINHTTP_STATUS_CALLBACK fonction de rappel (winhttp.h)
Le type WINHTTP_STATUS_CALLBACK représente une fonction de rappel status 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 affecté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 status qui indique pourquoi 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 de 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 intermédiaire (niveau 100) status du serveur. Le paramètre lpvStatusInformation contient un pointeur vers un DWORD qui indique le code status.
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é lues avec succès à 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
Attendre 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 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
Réception réussie d’une réponse du serveur. 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 la récupération d’un certificat SSL (Secure Sockets Layer) à partir du serveur. Le paramètre lpvStatusInformation contient un indicateur. 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 (valeur dwOptionalLength passée à WinHttpSendRequest).
WINHTTP_CALLBACK_STATUS_WRITE_COMPLETE
Les données ont été correctement écrites 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 lancé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 de bits-OR d’une ou plusieurs des valeurs suivantes.
[in] dwStatusInformationLength
WINHTTP_CALLBACK_STATUS_REDIRECT status rappels 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 status reçoit des mises à jour sur le status 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.
| Indicateur d’achèvement | Fonction |
|---|---|
| WINHTTP_CALLBACK_STATUS_DATA_AVAILABLE | WinHttpQueryDataAvailable |
| WINHTTP_CALLBACK_STATUS_HEADERS_AVAILABLE | WinHttpReceiveResponse |
| WINHTTP_CALLBACK_STATUS_READ_COMPLETE | WinHttpReadData |
| WINHTTP_CALLBACK_STATUS_SENDREQUEST_COMPLETE | WinHttpSendRequest |
| WINHTTP_CALLBACK_STATUS_WRITE_COMPLETE | WinHttpWriteData |
| WINHTTP_CALLBACK_STATUS_REQUEST_ERROR | L’une des fonctions ci-dessus en cas d’erreur. |
É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
| 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 |
| Composant redistribuable | WinHTTP 5.0 et Internet Explorer 5.01 ou version ultérieure sur Windows XP et Windows 2000. |
Voir aussi
Commentaires
Bientôt disponible : Tout au long de 2024, nous allons supprimer progressivement GitHub Issues comme mécanisme de commentaires pour le contenu et le remplacer par un nouveau système de commentaires. Pour plus d’informations, consultez https://aka.ms/ContentUserFeedback.
Envoyer et afficher des commentaires pour