IcmpSendEcho, fonction (icmpapi.h)
La fonction IcmpSendEcho envoie une demande d’écho ICMP IPv4 et retourne toutes les réponses de réponse d’écho. L’appel est retourné lorsque le délai d’attente a expiré ou que la mémoire tampon de réponse est remplie.
Syntaxe
IPHLPAPI_DLL_LINKAGE DWORD IcmpSendEcho(
[in] HANDLE IcmpHandle,
[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] DestinationAddress
Adresse de 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 . Sur une plateforme 64 bits, ce paramètre se présente sous la forme d’une structure IP_OPTION_INFORMATION32 .
Ce paramètre peut être NULL si aucune option d’en-tête IP n’a besoin d’être spécifiée.
[out] ReplyBuffer
Mémoire tampon pour contenir toutes les réponses à la demande d’écho. Lors du retour, la mémoire tampon contient un tableau de structures ICMP_ECHO_REPLY suivi des options et des données pour les réponses. La mémoire tampon doit être suffisamment grande pour contenir au moins un ICMP_ECHO_REPLY structure et des octets de données RequestSize .
[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 et des octets de données RequestSize .
Cette mémoire tampon doit également être suffisamment grande pour contenir également 8 octets de données supplémentaires (la taille d’un message d’erreur ICMP).
[in] Timeout
Temps, en millisecondes, d’attente des réponses.
Valeur retournée
La fonction IcmpSendEcho retourne le nombre de structures ICMP_ECHO_REPLY stockées dans ReplyBuffer. La status de chaque réponse est contenue dans la structure. Si la valeur de retour est zéro, appelez GetLastError pour obtenir des informations supplémentaires sur l’erreur.
Si la fonction échoue, le code d’erreur étendu retourné par GetLastError peut être l’une des valeurs suivantes.
| Code de retour | Description |
|---|---|
|
La zone de données passée à un appel système est insuffisante. Cette erreur est retournée si le paramètre ReplySize indique que la mémoire tampon pointée par le paramètre ReplyBuffer est trop petite. |
|
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 . |
|
La mémoire n'est pas suffisante pour terminer cette opération. |
|
La demande n'est pas prise en charge. Cette erreur est retournée si aucune pile IPv4 n’est sur l’ordinateur local. |
|
La taille de l’objet ReplyBuffer spécifié dans le paramètre ReplySize était trop petite. |
|
Utilisez FormatMessage pour obtenir la chaîne de message de l’erreur retournée. |
Notes
La fonction IcmpSendEcho envoie une demande d’écho ICMP à l’adresse spécifiée et retourne le nombre de réponses reçues et stockées dans ReplyBuffer. La fonction IcmpSendEcho est une fonction synchrone qui retourne après avoir attendu l’heure spécifiée dans le paramètre Timeout pour une réponse. Si la valeur de retour est zéro, appelez GetLastError pour obtenir des informations d’erreur étendues.
Les fonctions IcmpSendEcho2 et IcmpSendEcho2Ex sont une version améliorée d’IcmpSendEcho qui prend en charge l’opération asynchrone. La fonction IcmpSendEcho2Ex permet également de spécifier l’adresse IP source. Cette fonctionnalité est utile sur les ordinateurs avec plusieurs interfaces réseau.
Pour IPv6, utilisez les fonctions Icmp6CreateFile, Icmp6SendEcho2 et Icmp6ParseReplies .
La fonction IcmpSendEcho est exportée à partir du Icmp.dll sur Windows 2000. La fonction IcmpSendEcho est exportée à partir du Iphlpapi.dll sur Windows XP et versions ultérieures. Il n’est pas recommandé de vérifier la version de Windows pour utiliser cette fonction. Les applications nécessitant une portabilité avec cette fonction dans Windows 2000, Windows XP, Windows Server 2003 et versions ultérieures de Windows ne doivent pas être liées de manière statique au fichier Icmp.lib ou Iphlpapi.lib . Au lieu de cela, l’application doit case activée pour la présence d’IcmpSendEcho dans le Iphlpapi.dll avec des appels à LoadLibrary et GetProcAddress. À défaut, l’application doit case activée pour la présence d’IcmpSendEcho dans le Icmp.dll avec des appels à LoadLibrary et GetProcAddress.
Notez que la directive include pour le fichier d’en-tête Iphlpapi.h doit être placée avant le fichier d’en-tête Icmpapi.h .
Exemples
L’exemple suivant 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;
char SendData[32] = "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;
}
ReplySize = sizeof(ICMP_ECHO_REPLY) + sizeof(SendData);
ReplyBuffer = (VOID*) malloc(ReplySize);
if (ReplyBuffer == NULL) {
printf("\tUnable to allocate memory\n");
return 1;
}
dwRetVal = IcmpSendEcho(hIcmpFile, 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\n",
pEchoReply->Status);
printf("\t Roundtrip time = %ld milliseconds\n",
pEchoReply->RoundTripTime);
}
else {
printf("\tCall to IcmpSendEcho failed.\n");
printf("\tIcmpSendEcho returned error: %ld\n", GetLastError() );
return 1;
}
return 0;
}
Configuration requise
| Client minimal pris en charge | Windows 2000 Professionnel [applications de bureau uniquement] |
| Serveur minimal pris en charge | Windows 2000 Server [applications de bureau uniquement] |
| 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 |