IcmpSendEcho2Ex function (icmpapi.h)

The IcmpSendEcho2Ex function sends an IPv4 ICMP echo request and returns either immediately (if Event or ApcRoutine is non-NULL) or returns after the specified time-out. The ReplyBuffer contains the ICMP responses, if any.

Syntax

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
);

Parameters

[in] IcmpHandle

An open handle returned by the ICMPCreateFile function.

[in, optional] Event

An event to be signaled whenever an ICMP response arrives. If this parameter is specified, it requires a handle to a valid event object. Use the CreateEvent or CreateEventEx function to create this event object.

For more information on using events, see Event Objects.

[in, optional] ApcRoutine

The routine that is called when the calling thread is in an alertable thread and an ICMP reply arrives. PIO_APC_ROUTINE_DEFINED must be defined to force the datatype for this parameter to PIO_APC_ROUTINE rather than FARPROC.

[in, optional] ApcContext

An optional parameter passed to the callback routine specified in the ApcRoutine parameter whenever an ICMP response arrives or an error occurs.

[in] SourceAddress

The IPv4 source address on which to issue the echo request. This address is in the form of an IPAddr structure.

[in] DestinationAddress

The IPv4 destination address for the echo request. This address is in the form of an IPAddr structure.

[in] RequestData

A pointer to a buffer that contains data to send in the request.

[in] RequestSize

The size, in bytes, of the request data buffer pointed to by the RequestData parameter.

[in, optional] RequestOptions

A pointer to the IP header options for the request, in the form of an IP_OPTION_INFORMATION structure. On a 64-bit platform, this parameter is in the form for an IP_OPTION_INFORMATION32 structure.

This parameter may be NULL if no IP header options need to be specified.

[out] ReplyBuffer

A pointer to a buffer to hold any replies to the request. Upon return, the buffer contains an array of ICMP_ECHO_REPLY structures followed by options and data. The buffer must be large enough to hold at least one ICMP_ECHO_REPLY structure plus RequestSize bytes of data.

This buffer should also be large enough to also hold 8 more bytes of data (the size of an ICMP error message) plus space for an IO_STATUS_BLOCK structure.

[in] ReplySize

The allocated size, in bytes, of the reply buffer. The buffer should be large enough to hold at least one ICMP_ECHO_REPLY structure plus RequestSize bytes of data.

This buffer should also be large enough to also hold 8 more bytes of data (the size of an ICMP error message) plus space for an IO_STATUS_BLOCK structure.

[in] Timeout

The time, in milliseconds, to wait for replies.

Return value

When called synchronously, the IcmpSendEcho2Ex function returns the number of replies received and stored in ReplyBuffer. If the return value is zero, call GetLastError for extended error information.

When called asynchronously, the IcmpSendEcho2Ex function returns ERROR_IO_PENDING to indicate the operation is in progress. The results can be retrieved later when the event specified in the Event parameter signals or the callback function in the ApcRoutine parameter is called.

If the return value is zero, call GetLastError for extended error information.

If the function fails, the extended error code returned by GetLastError can be one of the following values.

Remarks

The IcmpSendEcho2Ex function is available on Windows Server 2008 and later.

The IcmpSendEcho2Ex function is an enhanced version of the IcmpSendEcho2 function that allows the user to specify the IPv4 source address on which to issue the ICMP request. The IcmpSendEcho2Ex function is useful in cases where a computer has multiple network interfaces.

The IcmpSendEcho2Ex function is called synchronously if the ApcRoutine or Event parameters are NULL. When called synchronously, the return value contains the number of replies received and stored in ReplyBuffer after waiting for the time specified in the Timeout parameter. If the return value is zero, call GetLastError for extended error information.

The IcmpSendEcho2Ex function is called asynchronously when either the ApcRoutine or Event parameters are specified. When called asynchronously, the ReplyBuffer and ReplySize parameters are required to accept the response. ICMP response data is copied to the ReplyBuffer provided and the application is signaled (when the Event parameter is specified) or the callback function is called (when the ApcRoutine parameter is specified). The application must parse the data pointed to by ReplyBuffer parameter using the IcmpParseReplies function.

If the Event parameter is specified, the IcmpSendEcho2Ex function is called asynchronously. The event specified in the Event parameter is signaled whenever an ICMP response arrives. Use the CreateEvent function to create this event object.

If the ApcRoutine parameter is specified, the IcmpSendEcho2Ex function is called asynchronously. The ApcRoutine parameter should point to a user-defined callback function. The callback function specified in the ApcRoutine parameter is called whenever an ICMP response arrives. The invocation of the callback function specified in the ApcRoutine parameter is serialized.

If both the Event and ApcRoutine parameters are specified, the event specified in the Event parameter is signaled whenever an ICMP response arrives, but the callback function specified in the ApcRoutine parameter is ignored .

Any application that calls the IcmpSendEcho2Ex function asynchronously using the ApcRoutine parameter must define PIO_APC_ROUTINE_DEFINED to force the datatype for the ApcRoutine parameter to PIO_APC_ROUTINE rather than FARPROC.

The callback function pointed to by the ApcRoutine must be defined as a function of type VOID with the following syntax:

typedef
VOID WINAPI
(*PIO_APC_ROUTINE) (
    IN PVOID ApcContext,
    IN PIO_STATUS_BLOCK IoStatusBlock,
    IN ULONG Reserved
    );

The parameters passed to the callback function include the following:

The callback function specified in the ApcRoutine parameter must be implemented in the same process as the application calling the IcmpSendEcho2Ex function. If the callback function is in a separate DLL, then the DLL should be loaded before calling the IcmpSendEcho2Ex function.

For IPv6, use the Icmp6CreateFile, Icmp6SendEcho2, and Icmp6ParseReplies functions.

Note that the include directive for Iphlpapi.h header file must be placed before the Icmpapi.h header file.

Requirements

See also

CreateEvent

CreateEventEx

Event Objects

GetLastError

ICMPCreateFile

ICMP_ECHO_REPLY

IPAddr

IP_OPTION_INFORMATION

IP_OPTION_INFORMATION32

Icmp6CreateFile

Icmp6ParseReplies

Icmp6SendEcho2

IcmpParseReplies

IcmpSendEcho

IcmpSendEcho2