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.
[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 |
|---|---|
|
Cette fonction n’est pas prise en charge sur ce système. |
|
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. |
|
L’un des paramètres n’est pas valide. Cette erreur est retournée si le paramètre IcmpHandle contient un handle non valide. |
|
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. |
|
La mémoire disponible est insuffisante pour traiter cette commande. |
|
La demande n'est pas prise en charge. Cette erreur est retournée si aucune pile IPv6 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. |
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.
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 :
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 :
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 |