Partager via


Icmp6SendEcho2, fonction (icmpapi.h)

La fonction Icmp6SendEcho2 envoie une demande d’écho IPv6 ICMPv6 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 la réponse d’écho ICMPv6 IPv6, le cas échéant.

Syntaxe

IPHLPAPI_DLL_LINKAGE DWORD Icmp6SendEcho2(
  [in]           HANDLE                 IcmpHandle,
  [in, optional] HANDLE                 Event,
  [in, optional] PIO_APC_ROUTINE        ApcRoutine,
  [in, optional] PVOID                  ApcContext,
  [in]           sockaddr_in6           *SourceAddress,
  [in]           sockaddr_in6           *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 Icmp6CreateFile.

[in, optional] Event

Événement à signaler chaque fois qu’une réponse ICMPv6 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énements.

[in, optional] ApcRoutine

Routine appelée lorsque le thread appelant se trouve dans un thread pouvant être alerté et qu’une réponse ICMPv6 arrive. Sur Windows Vista et versions ultérieures, 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.

Sur Windows Server 2003 et Windows XP, PIO_APC_ROUTINE_DEFINED ne doit pas être défini pour forcer le type de données de ce paramètre à 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 ICMPv6 arrive ou qu’une erreur se produit.

[in] SourceAddress

Adresse source IPv6 sur laquelle émettre la demande d’écho, sous la forme d’une structure sockaddr .

[in] DestinationAddress

Adresse de destination IPv6 de la demande d’écho, sous la forme d’une structure sockaddr .

[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 IPv6 pour la demande, sous la forme d’une structure de 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.

Note Sur Windows Server 2003 et Windows XP, le paramètre RequestOptions n’est pas facultatif et ne doit pas être NULL et seuls les membres Ttl et Flags sont utilisés.
 

[out] ReplyBuffer

Pointeur vers une mémoire tampon pour contenir les réponses à la demande. Lors du retour, la mémoire tampon contient une structure ICMPV6_ECHO_REPLY suivie du corps du message à partir des données de réponse d’écho ICMPv6. La mémoire tampon doit être suffisamment grande pour contenir au moins une structure ICMPV6_ECHO_REPLY plus le nombre d’octets de données spécifié dans le paramètre 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) plus de l’espace pour une structure IO_STATUS_BLOCK .

[in] ReplySize

Taille, en octets, de la mémoire tampon de réponse pointée vers le paramètre ReplyBuffer . Cette mémoire tampon doit être suffisamment grande pour contenir au moins un ICMPV6_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) plus de l’espace pour une structure IO_STATUS_BLOCK .

[in] Timeout

Temps, en millisecondes, d’attente des réponses. Ce paramètre est utilisé uniquement si la fonction Icmp6SendEcho2 est appelée de manière synchrone. Ce paramètre n’est donc pas utilisé si le paramètre ApcRoutine ou Event n’est pas NULL.

Valeur retournée

En cas d’appel synchrone, retourne le nombre de réponses reçues et stockées dans ReplyBuffer.

En cas d’appel asynchrone, indique que l’opération est en cours en retournant ERROR_IO_PENDING. Vous pouvez récupérer le résultat du nombre de réponses ultérieurement, lorsque l’événement spécifié dans le paramètre Event signale ou lorsque la fonction de rappel dans le paramètre ApcRoutine est appelée.

Si la valeur de nombre de réponses (synchrone ou asynchrone) est égale à zéro, pour les informations d’erreur étendues, appelez GetLastError.

Si la fonction échoue, le code d’erreur étendu retourné par GetLastError peut être l’une des valeurs suivantes.

Code de retour Description
ERROR_CALL_NOT_IMPLEMENTED
Cette fonction n’est pas prise en charge sur ce système.
ERROR_INSUFFICIENT_BUFFER
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.
ERROR_INVALID_PARAMETER
L’un des paramètres n’est pas valide. Cette erreur est retournée si le paramètre IcmpHandle contient un handle non valide.
ERROR_IO_PENDING
L’opération est en cours. Cette valeur est retournée par un appel asynchrone réussi à Icmp6SendEcho2 et n’est pas une indication d’erreur.
ERROR_NOT_ENOUGH_MEMORY
La mémoire disponible est insuffisante pour traiter cette commande.
ERROR_NOT_SUPPORTED
La demande n'est pas prise en charge. Cette erreur est retournée si aucune pile IPv6 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 Icmp6SendEcho2 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 Icmp6SendEcho2 est appelée de façon 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 Icmp6ParseReplies .

Si le paramètre Event est spécifié, la fonction Icmp6SendEcho2 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 ICMPv6 arrive. Utilisez la fonction CreateEvent pour créer cet objet d’événement.

Si le paramètre ApcRoutine est spécifié, la fonction Icmp6SendEcho2 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 ICMPv6 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 ICMPv6 arrive, mais la fonction de rappel spécifiée dans le paramètre ApcRoutine est ignorée .

Sur Windows Vista et versions ultérieures, toute application qui appelle la fonction Icmp6SendEcho2 de façon 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 devez être défini avant d’inclure le fichier d’en-tête Icmpapi.h .

 

Sur Windows Vista et versions ultérieures, 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
    );

Sur Windows Vista et versions ultérieures, les paramètres passés à la fonction de rappel sont les suivants :

Paramètre Description
IN PVOID ApcContext Paramètre ApcContext passé à la fonction Icmp6SendEcho2 . Ce paramètre peut être utilisé par l’application pour identifier la requête Icmp6SendEcho2 à 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é.
 

Sur Windows Server 2003 et Windows XP, toute application qui appelle la fonction Icmp6SendEcho2 de façon asynchrone à l’aide du paramètre ApcRoutine ne doit pas définir PIO_APC_ROUTINE_DEFINED pour forcer le type de données du paramètre ApcRoutine à FARPROC plutôt qu’PIO_APC_ROUTINE.

Sur Windows Server 2003 et Windows XP, 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
(*FARPROC) (
    IN PVOID ApcContext,
    );

Sur Windows Server 2003 et Windows XP, les paramètres passés à la fonction de rappel sont les suivants :

Paramètre Description
IN PVOID ApcContext Paramètre ApcContext passé à la fonction Icmp6SendEcho2 . Ce paramètre peut être utilisé par l’application pour identifier la requête Icmp6SendEcho2 à laquelle la fonction de rappel répond.
 

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 Icmp6SendEcho2 . Si la fonction de rappel se trouve dans une DLL distincte, la DLL doit être chargée avant d’appeler la fonction Icmp6SendEcho2 .

Pour IPv4, utilisez les fonctions IcmpCreateFile, IcmpSendEcho, IcmpSendEcho2, IcmpSendEcho2Ex et IcmpParseReplies .

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

Condition requise Valeur
Client minimal pris en charge Windows XP [applications de bureau | applications UWP]
Serveur minimal pris en charge Windows Server 2003 [applications de bureau | applications UWP]
Plateforme cible Windows
En-tête icmpapi.h
Bibliothèque Iphlpapi.lib
DLL Iphlpapi.dll

Voir aussi

CreateEvent

CreateEventEx

Objets d’événement

Obtenir la dernière erreur

ICMPV6_ECHO_REPLY

ICMP_ECHO_REPLY

IP_OPTION_INFORMATION

Icmp6CreateFile

Icmp6ParseReplies

IcmpCloseHandle

IcmpCreateFile

IcmpParseReplies

IcmpSendEcho

IcmpSendEcho2

IcmpSendEcho2Ex

sockaddr