icmp6SendEcho2 函式 (icmpapi.h)

發行項
02/27/2024

Icmp6SendEcho2 函式會傳送 IPv6 ICMPv6 回應要求，並在 Event 或 ApcRoutine 為非 NULL) 或傳回指定的逾時之後 (立即傳回。ReplyBuffer 包含 IPv6 ICMPv6 回應回應，如果有的話。

語法

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

參數

[in] IcmpHandle

Icmp6CreateFile 傳回的開啟句柄。

[in, optional] Event

每當 ICMPv6 回應送達時，要發出訊號的事件。如果指定此參數，則需要有效事件物件的句柄。使用 CreateEvent 或 CreateEventEx 函式來建立此事件物件。

如需使用事件的詳細資訊，請參閱事件物件。

[in, optional] ApcRoutine

當呼叫線程位於可警示線程且ICMPv6 回復送達時所呼叫的例程。在 Windows Vista 和更新版本上，必須定義 PIO_APC_ROUTINE_DEFINED ，以強制此參數的數據類型 PIO_APC_ROUTINE 而非 FARPROC。

在 Windows Server 2003 和 Windows XP 上，不得定義 PIO_APC_ROUTINE_DEFINED ，將此參數的數據類型強制為 FARPROC。

[in, optional] ApcContext

每當 ICMPv6 回應送達或發生錯誤時，傳遞至 ApcRoutine 參數中指定的回呼例程的選擇性參數。

[in] SourceAddress

要發出回應要求的 IPv6 來源位址，格式為 sockaddr 結構。

[in] DestinationAddress

回應要求的 IPv6 目的地位址，格式為 sockaddr 結構。

[in] RequestData

緩衝區的指標，其中包含要求中要傳送的數據。

[in] RequestSize

RequestData 參數所指向之要求數據緩衝區的大小，以位元組為單位。

[in, optional] RequestOptions

要求的 IPv6 標頭選項指標，格式為 IP_OPTION_INFORMATION 結構。在 64 位平臺上，此參數的格式為 IP_OPTION_INFORMATION32 結構。

如果不需要指定任何IP標頭選項，此參數可能是NULL。

注意在 Windows Server 2003 和 Windows XP 上， RequestOptions 參數不是選擇性的，不能是 NULL，而且只會使用 Ttl 和 Flags 成員。

[out] ReplyBuffer

緩衝區的指標，用來保存對要求的回復。傳回時，緩衝區包含 ICMPV6_ECHO_REPLY 結構，後面接著來自ICMPv6回應回應回復數據的訊息本文。緩衝區必須夠大，才能保存至少一個 ICMPV6_ECHO_REPLY 結構，加上 RequestSize 參數中指定的數據位元組數目。此緩衝區也應該夠大，以容納 8 個以上的數據位元組， (ICMP 錯誤訊息的大小) 加上 IO_STATUS_BLOCK 結構的空間。

[in] ReplySize

ReplyBuffer 參數所指向之回復緩衝區的大小，以位元組為單位。這個緩衝區應該夠大，足以保存至少一個 ICMPV6_ECHO_REPLY 結構加上 RequestSize 位元組的數據。此緩衝區也應該夠大，以容納 8 個以上的數據位元組， (ICMP 錯誤訊息的大小) 加上 IO_STATUS_BLOCK 結構的空間。

[in] Timeout

等候回復的時間，以毫秒為單位。只有在以同步方式呼叫 Icmp6SendEcho2 函式時，才會使用此參數。因此，如果 ApcRoutine 或 Event 參數不是 NULL，則不會使用此參數。

傳回值

以同步方式呼叫時，傳回接收並儲存在 ReplyBuffer 中的回復數目。

以異步方式呼叫時，表示作業正在進行中，方法是傳回 ERROR_IO_PENDING。您可以稍後擷取回復數目結果、 事件參數所 指定的事件發出訊號，或呼叫 ApcRoutine 參數中的回呼函式時。

如果 (同步或異步) 回復數目值為零，則針對擴充錯誤資訊呼叫 GetLastError。

如果函式失敗， GetLastError 傳回的擴充錯誤碼可以是下列其中一個值。

傳回碼	Description
ERROR_CALL_NOT_IMPLEMENTED	此系統不支援此函式。
ERROR_INSUFFICIENT_BUFFER	傳遞至系統呼叫的數據區域太小。如果 ReplySize 參數指出 ReplyBuffer 參數指向的緩衝區太小，就會傳回此錯誤。
ERROR_INVALID_PARAMETER	其中一個參數無效。如果 IcmpHandle 參數包含無效的句柄，就會傳回此錯誤。
ERROR_IO_PENDING	作業正在進行中。這個值是由 Icmp6SendEcho2 的成功異步呼叫所傳回，而且不是錯誤的指示。
ERROR_NOT_ENOUGH_MEMORY	沒有足夠的記憶體可用來處理此命令。
ERROR_NOT_SUPPORTED	不支援此要求。如果本機計算機上沒有IPv6堆疊，則會傳回此錯誤。
IP_BUF_TOO_SMALL	ReplySize 參數中指定的 ReplyBuffer 大小太小。
其他	使用 FormatMessage 取得傳回錯誤的訊息字串。

備註

如果 ApcRoutine 或 Event 參數為 NULL，就會同步呼叫 Icmp6SendEcho2 函式。以同步方式呼叫時，傳回值會包含在等候 Timeout 參數中指定的時間之後，接收並儲存在 ReplyBuffer 中的回覆數目。如果傳回值為零，請呼叫 GetLastError 以取得擴充的錯誤資訊。

指定 ApcRoutine 或 Event 參數時，會以異步方式呼叫 Icmp6SendEcho2 函式。以異步方式呼叫時，需要 ReplyBuffer 和 ReplySize 參數才能接受回應。 ICMP 回應數據會複製到提供的 ReplyBuffer ，並在指定 Event 參數) 或 (指定 ApcRoutine 參數時呼叫回呼函式 () 發出訊號。應用程式必須使用Icmp6ParseReplies函式來剖析 ReplyBuffer 參數所指向的數據。

如果指定 Event 參數，則會以異步方式呼叫 Icmp6SendEcho2 函式。每當 ICMPv6 回應送達時，事件參數中指定的事件就會發出訊號。使用 CreateEvent 函式來建立此事件物件。

如果指定 了 ApcRoutine 參數，則會以異步方式呼叫 Icmp6SendEcho2 函式。 ApcRoutine 參數應該指向使用者定義的回呼函式。每當 ICMPv6 回應送達時，就會呼叫 ApcRoutine 參數中指定的回調函式。 ApcRoutine 參數中指定的回呼函式調用會串行化。

如果同時指定 Event 和 ApcRoutine 參數，每當 ICMPv6 回應送達時， 就會發出 Event 參數中指定的事件，但會忽略 ApcRoutine 參數中指定的回呼函式。

在 Windows Vista 和更新版本上，任何使用 ApcRoutine 參數異步呼叫 Icmp6SendEcho2 函式的應用程式都必須定義 PIO_APC_ROUTINE_DEFINED，以強制 ApcRoutine 參數的數據類型PIO_APC_ROUTINE而非 FARPROC。

注意PIO_APC_ROUTINE_DEFINED 必須先定義 ，才能包含Icmpapi.h 頭檔。

在 Windows Vista 和更新版本上， ApcRoutine 指向的回調函式必須定義為 VOID 類型的函式，其語法如下：

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

在 Windows Vista 和更新版本上，傳遞至回調函式的參數包括下列各項：

參數	Description
IN PVOID ApcContext	傳遞至 Icmp6SendEcho2 函式的 ApcContext 參數。應用程式可以使用此參數來識別回呼函式所回應的 Icmp6SendEcho2 要求。
IN PIO_STATUS_BLOCK IoStatusBlock	IO_STATUS_BLOCK的指標。此變數包含最終完成狀態和作業的相關信息。在IO_STATUS_BLOCK結構的信息成員中，會傳回回復中實際收到的位元元組數目。 IO_STATUS_BLOCK 結構定義於 Wdm.h 頭檔中。
在 ULONG 中保留	此參數已保留備用。

在 Windows Server 2003 和 Windows XP 上，使用 ApcRoutine 參數以異步方式呼叫 Icmp6SendEcho2 函式的任何應用程式都不得定義PIO_APC_ROUTINE_DEFINED，以強制 ApcRoutine 參數的數據類型為 FARPROC，而不是PIO_APC_ROUTINE。

在 Windows Server 2003 和 Windows XP 上， ApcRoutine 指向的回調函式必須定義為 VOID 類型的函式，其語法如下：

typedef
VOID WINAPI
(*FARPROC) (
    IN PVOID ApcContext,
    );

在 Windows Server 2003 和 Windows XP 上，傳遞至回調函式的參數包括下列各項：

參數	Description
IN PVOID ApcContext	傳遞至 Icmp6SendEcho2 函式的 ApcContext 參數。應用程式可以使用此參數來識別回呼函式所回應的 Icmp6SendEcho2 要求。

ApcRoutine 參數中指定的回呼函式必須與呼叫 Icmp6SendEcho2 函式的應用程式在相同的進程中實作。如果回呼函式位於個別的 DLL 中，則應該先載入 DLL，再呼叫 Icmp6SendEcho2 函式。

針對 IPv4，請使用 IcmpCreateFile、 IcmpSendEcho、 IcmpSendEcho2、 IcmpSendEcho2Ex 和 IcmpParseReplies 函式。

請注意， Iphlpapi.h 頭檔的 include 指示詞必須放在 Icmpapi.h 頭檔之前。

規格需求

需求	值
最低支援的用戶端	Windows XP [傳統型應用程式 \|UWP 應用程式]
最低支援的伺服器	Windows Server 2003 [傳統型應用程式 \|UWP 應用程式]
目標平台	Windows
標頭	icmpapi.h
程式庫	Iphlpapi.lib
Dll	Iphlpapi.dll