IcmpSendEcho2, fonction (icmpapi.h)
La fonction IcmpSendEcho2 envoie une demande d’écho ICMP IPv4 et retourne immédiatement (si Event ou ApcRoutine n’a pas la valeur NULL), ou retourne après le délai d’attente spécifié. ReplyBuffer contient les réponses d’écho ICMP, le cas échéant.
Syntaxe
IPHLPAPI_DLL_LINKAGE DWORD IcmpSendEcho2(
[in] HANDLE IcmpHandle,
[in, optional] HANDLE Event,
[in, optional] PIO_APC_ROUTINE ApcRoutine,
[in, optional] PVOID ApcContext,
[in] IPAddr DestinationAddress,
[in] LPVOID RequestData,
[in] WORD RequestSize,
[in, optional] PIP_OPTION_INFORMATION RequestOptions,
[out] LPVOID ReplyBuffer,
[in] DWORD ReplySize,
[in] DWORD Timeout
);
Paramètres
[in] IcmpHandle
Handle ouvert retourné par la fonction ICMPCreateFile .
[in, optional] Event
Événement à signaler (au plus une fois) lorsqu’une réponse ICMP arrive. Si ce paramètre est spécifié, il nécessite un handle pour un objet d’événement valide. Utilisez la fonction CreateEvent ou CreateEventEx pour créer cet objet d’événement.
Pour plus d’informations sur l’utilisation d’événements, consultez Objets d’événement.
[in, optional] ApcRoutine
Routine appelée lorsque le thread appelant se trouve dans un thread pouvant être alerté et qu’une réponse ICMPv4 arrive. PIO_APC_ROUTINE_DEFINED doit être défini afin de forcer le type de données de ce paramètre à PIO_APC_ROUTINE plutôt que FARPROC.
[in, optional] ApcContext
Paramètre facultatif passé à la routine de rappel spécifiée dans le paramètre ApcRoutine (au plus une fois) lorsqu’une réponse ICMP arrive ou qu’une erreur se produit.
[in] DestinationAddress
Destination IPv4 de la demande d’écho, sous la forme d’une structure IPAddr .
[in] RequestData
Pointeur vers une mémoire tampon qui contient les données à envoyer dans la requête.
[in] RequestSize
Taille, en octets, de la mémoire tampon de données de requête pointée vers le paramètre RequestData .
[in, optional] RequestOptions
Pointeur vers les options d’en-tête IP pour la demande, sous la forme d’une structure IP_OPTION_INFORMATION .
Ce paramètre peut être NULL si aucune option d’en-tête IP n’a besoin d’être spécifiée.
[out] ReplyBuffer
Pointeur vers une mémoire tampon pour contenir toutes les réponses à la demande. Lors du retour, la mémoire tampon contient un tableau de structures ICMP_ECHO_REPLY suivies d’options et de données.
La mémoire tampon doit être suffisamment grande pour contenir au moins un ICMP_ECHO_REPLY structure, ainsi que des octets RequestSize de données, ainsi que 8 octets supplémentaires de données (taille d’un message d’erreur ICMP).
[in] ReplySize
Taille allouée, en octets, de la mémoire tampon de réponse.
La mémoire tampon doit être suffisamment grande pour contenir au moins un ICMP_ECHO_REPLY structure, ainsi que des octets RequestSize de données, ainsi que 8 octets supplémentaires de données (taille d’un message d’erreur ICMP).
[in] Timeout
Délai en millisecondes d’attente des réponses.
Valeur retournée
Lorsqu’elle est appelée de manière synchrone, la fonction IcmpSendEcho2 retourne le nombre de réponses reçues et stockées dans ReplyBuffer. Si la valeur de retour est zéro, appelez GetLastError pour obtenir des informations d’erreur étendues.
Lorsqu’elle est appelée de façon asynchrone, la fonction IcmpSendEcho2 retourne zéro. Un appel suivant à GetLastError retourne un code d’erreur étendu ERROR_IO_PENDING pour indiquer que l’opération est en cours. Les résultats peuvent être récupérés ultérieurement lorsque l’événement spécifié dans le paramètre Event signale ou que la fonction de rappel dans le paramètre ApcRoutine est appelée.
Si la valeur de retour est zéro, appelez GetLastError pour obtenir des informations d’erreur étendues.
Si la fonction échoue, le code d’erreur étendu retourné par GetLastError peut être l’une des valeurs suivantes.
| Code de retour | Description |
|---|---|
| ERROR_INVALID_PARAMETER | Un paramètre non valide a été transmis à la fonction. Cette erreur est retournée si le paramètre IcmpHandle contient un handle non valide. Cette erreur peut également être retournée si le paramètre ReplySize spécifie une valeur inférieure à la taille d’une structure ICMP_ECHO_REPLY . |
| ERROR_IO_PENDING | L’opération est en cours. Cette valeur est retournée par un appel asynchrone réussi à IcmpSendEcho2 et n’indique pas une erreur. |
| ERROR_NOT_ENOUGH_MEMORY | La mémoire n'est pas suffisante pour terminer cette opération. |
| ERROR_NOT_SUPPORTED | La demande n'est pas prise en charge. Cette erreur est retournée si aucune pile IPv4 n’est sur l’ordinateur local. |
| IP_BUF_TOO_SMALL | La taille de l’objet ReplyBuffer spécifié dans le paramètre ReplySize était trop petite. |
| Autres | Utilisez FormatMessage pour obtenir la chaîne de message de l’erreur retournée. |
Remarques
La fonction IcmpSendEcho2 est appelée de manière synchrone si les paramètres ApcRoutine ou Event ont la valeur NULL. Lorsqu’elle est appelée de façon synchrone, la valeur de retour contient le nombre de réponses reçues et stockées dans ReplyBuffer après l’attente de l’heure spécifiée dans le paramètre Timeout . Si la valeur de retour est zéro, appelez GetLastError pour obtenir des informations d’erreur étendues.
La fonction IcmpSendEcho2 est appelée de manière asynchrone lorsque les paramètres ApcRoutine ou Event sont spécifiés. Lorsqu’ils sont appelés de manière asynchrone, les paramètres ReplyBuffer et ReplySize sont requis pour accepter la réponse. Les données de réponse ICMP sont copiées dans l’objet ReplyBuffer fourni, et l’application est signalée (lorsque le paramètre Event est spécifié) ou la fonction de rappel est appelée (lorsque le paramètre ApcRoutine est spécifié). L’application doit analyser les données pointées par le paramètre ReplyBuffer à l’aide de la fonction IcmpParseReplies .
Si le paramètre Event est spécifié, la fonction IcmpSendEcho2 est appelée de façon asynchrone. L’événement spécifié dans le paramètre Event est signalé (au plus une fois) lorsqu’une réponse ICMP arrive. Utilisez la fonction CreateEvent ou CreateEventEx pour créer cet objet d’événement.
Si le paramètre ApcRoutine est spécifié, la fonction IcmpSendEcho2 est appelée de manière asynchrone. Le paramètre ApcRoutine doit pointer vers une fonction de rappel définie par l’utilisateur. La fonction de rappel spécifiée dans le paramètre ApcRoutine est appelée (au plus une fois) lorsqu’une réponse ICMP arrive. L’appel de la fonction de rappel spécifiée dans le paramètre ApcRoutine est sérialisé.
Si les paramètres Event et ApcRoutine sont spécifiés, l’événement spécifié dans le paramètre Event est signalé (au plus une fois) lorsqu’une réponse ICMP arrive, mais la fonction de rappel spécifiée dans le paramètre ApcRoutine est ignorée.
Toute application qui appelle la fonction IcmpSendEcho2 de manière asynchrone à l’aide du paramètre ApcRoutine doit définir PIO_APC_ROUTINE_DEFINED pour forcer le type de données du paramètre ApcRoutine à PIO_APC_ROUTINE plutôt que FARPROC.
Notes
PIO_APC_ROUTINE_DEFINED doit être défini avant d’inclure le fichier d’en-tête Icmpapi.h .
La fonction de rappel pointée par ApcRoutine doit être définie comme une fonction de type VOID avec la syntaxe suivante :
typedef
VOID WINAPI
(*PIO_APC_ROUTINE) (
IN PVOID ApcContext,
IN PIO_STATUS_BLOCK IoStatusBlock,
IN ULONG Reserved
);
Les paramètres passés à la fonction de rappel sont les suivants :
| Paramètre | Description |
|---|---|
| IN PVOID ApcContext | Paramètre AppContext passé à la fonction IcmpSendEcho2 . Ce paramètre peut être utilisé par l’application pour identifier la requête IcmpSendEcho2 à laquelle la fonction de rappel répond. |
| IN PIO_STATUS_BLOCK IoStatusBlock | Pointeur vers un IO_STATUS_BLOCK. Cette variable contient l’achèvement final status et des informations sur l’opération. Le nombre d’octets réellement reçus dans la réponse est retourné dans le membre Information du struct IO_STATUS_BLOCK . La structure IO_STATUS_BLOCK est définie dans le fichier d’en-tête Wdm.h . |
| IN ULONG Reserved | Ce paramètre est réservé. |
La fonction de rappel spécifiée dans le paramètre ApcRoutine doit être implémentée dans le même processus que l’application appelant la fonction IcmpSendEcho2 . Si la fonction de rappel se trouve dans une DLL distincte, la DLL doit être chargée avant d’appeler la fonction IcmpSendEcho2 .
La fonction IcmpSendEcho2 est exportée à partir de Iphlpapi.dll.
Pour IPv6, utilisez les fonctions Icmp6CreateFile, Icmp6SendEcho2 et Icmp6ParseReplies .
La directive include pour le fichier d’en-tête Iphlpapi.h doit être placée avant celle du fichier d’en-tête Icmpapi.h .
Exemple
L’exemple suivant appelle la fonction IcmpSendEcho2 de manière synchrone. L’exemple envoie une demande d’écho ICMP à l’adresse IP spécifiée sur la ligne de commande et imprime les informations reçues à partir de la première réponse.
#include <winsock2.h>
#include <iphlpapi.h>
#include <icmpapi.h>
#include <stdio.h>
#pragma comment(lib, "iphlpapi.lib")
#pragma comment(lib, "ws2_32.lib")
int __cdecl main(int argc, char **argv)
{
// Declare and initialize variables.
HANDLE hIcmpFile;
unsigned long ipaddr = INADDR_NONE;
DWORD dwRetVal = 0;
DWORD dwError = 0;
char SendData[] = "Data Buffer";
LPVOID ReplyBuffer = NULL;
DWORD ReplySize = 0;
// Validate the parameters.
if (argc != 2) {
printf("usage: %s IP address\n", argv[0]);
return 1;
}
ipaddr = inet_addr(argv[1]);
if (ipaddr == INADDR_NONE) {
printf("usage: %s IP address\n", argv[0]);
return 1;
}
hIcmpFile = IcmpCreateFile();
if (hIcmpFile == INVALID_HANDLE_VALUE) {
printf("\tUnable to open handle.\n");
printf("IcmpCreatefile returned error: %ld\n", GetLastError());
return 1;
}
// Allocate space for a single reply.
ReplySize = sizeof (ICMP_ECHO_REPLY) + sizeof (SendData) + 8;
ReplyBuffer = (VOID *) malloc(ReplySize);
if (ReplyBuffer == NULL) {
printf("\tUnable to allocate memory for reply buffer\n");
return 1;
}
dwRetVal = IcmpSendEcho2(hIcmpFile, NULL, NULL, NULL,
ipaddr, SendData, sizeof (SendData), NULL,
ReplyBuffer, ReplySize, 1000);
if (dwRetVal != 0) {
PICMP_ECHO_REPLY pEchoReply = (PICMP_ECHO_REPLY) ReplyBuffer;
struct in_addr ReplyAddr;
ReplyAddr.S_un.S_addr = pEchoReply->Address;
printf("\tSent icmp message to %s\n", argv[1]);
if (dwRetVal > 1) {
printf("\tReceived %ld icmp message responses\n", dwRetVal);
printf("\tInformation from the first response:\n");
} else {
printf("\tReceived %ld icmp message response\n", dwRetVal);
printf("\tInformation from this response:\n");
}
printf("\t Received from %s\n", inet_ntoa(ReplyAddr));
printf("\t Status = %ld ", pEchoReply->Status);
switch (pEchoReply->Status) {
case IP_DEST_HOST_UNREACHABLE:
printf("(Destination host was unreachable)\n");
break;
case IP_DEST_NET_UNREACHABLE:
printf("(Destination Network was unreachable)\n");
break;
case IP_REQ_TIMED_OUT:
printf("(Request timed out)\n");
break;
default:
printf("\n");
break;
}
printf("\t Roundtrip time = %ld milliseconds\n",
pEchoReply->RoundTripTime);
} else {
printf("Call to IcmpSendEcho2 failed.\n");
dwError = GetLastError();
switch (dwError) {
case IP_BUF_TOO_SMALL:
printf("\tReplyBufferSize too small\n");
break;
case IP_REQ_TIMED_OUT:
printf("\tRequest timed out\n");
break;
default:
printf("\tExtended error returned: %ld\n", dwError);
break;
}
return 1;
}
return 0;
}
Configuration requise
| Condition requise | Valeur |
|---|---|
| Client minimal pris en charge | Windows 2000 Professionnel [applications de bureau | Applications UWP] |
| Serveur minimal pris en charge | Windows 2000 Server [applications de bureau | Applications UWP] |
| Plateforme cible | Windows |
| En-tête | icmpapi.h |
| Bibliothèque | Iphlpapi.lib |
| DLL | Iphlpapi.dll sur Windows Server 2008, Windows Vista, Windows Server 2003 et Windows XP ; Icmp.dll sur Windows 2000 Server et Windows 2000 Professionnel |