IcmpSendEcho2Ex, fonction (icmpapi.h)

Article
08/24/2023

La fonction IcmpSendEcho2Ex 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 ICMP, le cas échéant.

Syntaxe

IPHLPAPI_DLL_LINKAGE DWORD IcmpSendEcho2Ex(
  [in]           HANDLE                 IcmpHandle,
  [in, optional] HANDLE                 Event,
  [in, optional] PIO_APC_ROUTINE        ApcRoutine,
  [in, optional] PVOID                  ApcContext,
  [in]           IPAddr                 SourceAddress,
  [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 chaque fois qu’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 Event Objects.

[in, optional] ApcRoutine

Routine appelée lorsque le thread appelant se trouve dans un thread pouvant être alerté et qu’une réponse ICMP arrive. PIO_APC_ROUTINE_DEFINED devez être défini pour 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 chaque fois qu’une réponse ICMP arrive ou qu’une erreur se produit.

[in] SourceAddress

Adresse source IPv4 sur laquelle émettre la demande d’écho. Cette adresse se présente sous la forme d’une structure IPAddr .

[in] DestinationAddress

Adresse de destination IPv4 pour la demande d’écho. Cette adresse se présente sous la forme d’une structure IPAddr .

[in] RequestData

Pointeur vers une mémoire tampon qui contient des données à envoyer dans la demande.

[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 requête, sous la forme d’une structure de IP_OPTION_INFORMATION . Sur une plateforme 64 bits, ce paramètre est sous la forme d’une structure IP_OPTION_INFORMATION32 .

Ce paramètre peut avoir la valeur NULL si aucune option d’en-tête IP ne doit être spécifiée.

[out] ReplyBuffer

Pointeur vers une mémoire tampon pour contenir toutes les réponses à la demande. Au 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 plus des octets de données RequestSize .

Cette mémoire tampon doit également être suffisamment grande pour contenir 8 octets supplémentaires de données (la taille d’un message d’erreur ICMP) plus de l’espace pour une structure IO_STATUS_BLOCK .

[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 plus des octets de données RequestSize .

[in] Timeout

Temps, en millisecondes, d’attente des réponses.

Valeur retournée

Lorsqu’elle est appelée de manière synchrone, la fonction IcmpSendEcho2Ex 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 manière asynchrone, la fonction IcmpSendEcho2Ex retourne 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 les signaux du paramètre Event ou 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 de ICMP_ECHO_REPLY .
ERROR_IO_PENDING	L’opération est en cours. Cette valeur est retournée par un appel asynchrone réussi à IcmpSendEcho2Ex et n’est pas une indication d’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 ne se trouve sur l’ordinateur local.
IP_BUF_TOO_SMALL	La taille de ReplyBuffer spécifiée dans le paramètre ReplySize était trop petite.
Autres	Utilisez FormatMessage pour obtenir la chaîne de message pour l’erreur retournée.

Notes

La fonction IcmpSendEcho2Ex est disponible sur Windows Server 2008 et versions ultérieures.

La fonction IcmpSendEcho2Ex est une version améliorée de la fonction IcmpSendEcho2 qui permet à l’utilisateur de spécifier l’adresse source IPv4 sur laquelle émettre la requête ICMP. La fonction IcmpSendEcho2Ex est utile dans les cas où un ordinateur a plusieurs interfaces réseau.

La fonction IcmpSendEcho2Ex est appelée de manière synchrone si les paramètres ApcRoutine ou Event sont NULL. Lorsqu’elle est appelée de manière synchrone, la valeur de retour contient le nombre de réponses reçues et stockées dans ReplyBuffer après avoir attendu 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 IcmpSendEcho2Ex 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 vers le paramètre ReplyBuffer à l’aide de la fonction IcmpParseReplies .

Si le paramètre Event est spécifié, la fonction IcmpSendEcho2Ex est appelée de manière asynchrone. L’événement spécifié dans le paramètre Event est signalé chaque fois qu’une réponse ICMP arrive. Utilisez la fonction CreateEvent pour créer cet objet d’événement.

Si le paramètre ApcRoutine est spécifié, la fonction IcmpSendEcho2Ex 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 chaque fois qu’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é chaque fois qu’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 IcmpSendEcho2Ex 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.

NotezPIO_APC_ROUTINE_DEFINED doit être défini avant que le fichier d’en-tête Icmpapi.h soit inclus.

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 ApcContext passé à la fonction IcmpSendEcho2Ex . Ce paramètre peut être utilisé par l’application pour identifier la requête IcmpSendEcho2Ex à laquelle la fonction de rappel répond.
IN PIO_STATUS_BLOCK IoStatusBlock	Pointeur vers un IO_STATUS_BLOCK. Cette variable contient la status d’achèvement finale et des informations sur l’opération. Le nombre d’octets effectivement 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 .
DANS ULONG réservé	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 IcmpSendEcho2Ex . Si la fonction de rappel se trouve dans une DLL distincte, la DLL doit être chargée avant d’appeler la fonction IcmpSendEcho2Ex .

Pour IPv6, utilisez les fonctions Icmp6CreateFile, Icmp6SendEcho2 et Icmp6ParseReplies .

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 .

Configuration requise


Client minimal pris en charge	Windows Vista avec SP1 [applications de bureau uniquement]
Serveur minimal pris en charge	Windows Server 2008 [applications de bureau uniquement]
Plateforme cible	Windows
En-tête	icmpapi.h
Bibliothèque	Iphlpapi.lib
DLL	Iphlpapi.dll