SIO_ADDRESS_LIST_QUERY控制項程式碼

發行項
06/13/2023

描述

SIO_ADDRESS_LIST_QUERY控制項程式碼會取得應用程式可系結的通訊端通訊協定系列本機傳輸地址清單。地址清單會根據地址系列而有所不同，有些位址會從清單中排除。

若要執行這項作業，請使用下列參數呼叫 WSAIoctl 或 WSPIoctl 函式。

int WSAIoctl(
  (socket) s,            // descriptor identifying a socket
  SIO_ADDRESS_LIST_QUERY,            // dwIoControlCode
  NULL,                              // lpvInBuffer
  0,                                 // cbInBuffer
  (LPVOID) lpvOutBuffer,          // output buffer
  (DWORD) cbOutBuffer,            // size of output buffer  
  (LPDWORD) lpcbBytesReturned,    // number of bytes returned
  (LPWSAOVERLAPPED) lpOverlapped, // OVERLAPPED structure
  (LPWSAOVERLAPPED_COMPLETION_ROUTINE) lpCompletionRoutine,  // completion routine
);

int WSPIoctl(
  (socket) s,            // descriptor identifying a socket
  SIO_ADDRESS_LIST_QUERY,            // dwIoControlCode
  NULL,                              // lpvInBuffer
  0,                                 // cbInBuffer
  (LPVOID) lpvOutBuffer,          // output buffer
  (DWORD) cbOutBuffer,            // size of output buffer  
  (LPDWORD) lpcbBytesReturned,    // number of bytes returned
  (LPWSAOVERLAPPED) lpOverlapped, // OVERLAPPED structure
  (LPWSAOVERLAPPED_COMPLETION_ROUTINE) lpCompletionRoutine,  // completion routine
  (LPWSATHREADID) lpThreadId,   // a WSATHREADID structure
  (LPINT) lpErrno   // a pointer to the error code.
);

參數

s

識別通訊端的描述項。

dwIoControlCode

作業的控制程式代碼。針對此作業使用 SIO_ADDRESS_LIST_QUERY 。

lpvInBuffer

輸入緩衝區的指標。這個作業未使用此參數。

cbInBuffer

輸入緩衝區的大小，以位元組為單位。這個作業未使用此參數。

lpvOutBuffer

輸出緩衝區的指標。

cbOutBuffer

輸出緩衝區的大小，以位元組為單位。

lBytesReturned

變數的指標，可接收儲存在輸出緩衝區中的資料大小，以位元組為單位。

lpvOverlapped

WSAOVERLAPPED結構的指標。

如果沒有重迭屬性建立通訊端，則會忽略 lpOverlapped參數。

如果使用重迭屬性開啟 s ，且 lpOverlapped 參數不是 Null，則會以重迭的 (非同步) 作業來執行作業。在此情況下， lpOverlapped 參數必須指向有效的 WSAOVERLAPPED 結構。

對於重迭的作業， WSAIoctl 或 WSPIoctl 函式會立即傳回，並在作業完成時發出適當的完成方法訊號。否則，在作業完成或發生錯誤之前，函式不會傳回。

lpCompletionRoutine

類型：_In_opt_ LPWSAOVERLAPPED_COMPLETION_ROUTINE

當作業完成時呼叫的完成常式指標， (忽略非重迭通訊端) 。

lpThreadId

WSATHREADID結構的指標，供提供者在後續呼叫WPUQueueApc時使用。提供者應該儲存參考的 WSATHREADID 結構， (在 WPUQueueApc 函式傳回之前，不要儲存相同) 的指標。

注意此參數僅適用于 WSPIoctl 函式。

lpErrno

錯誤碼的指標。

注意此參數僅適用于 WSPIoctl 函式。

傳回值

如果作業順利完成， WSAIoctl 或 WSPIoctl 函式會傳回零。

如果作業失敗或擱置中，WSAIoctl 或 WSPIoctl函式會傳回SOCKET_ERROR。若要取得擴充錯誤資訊，請呼叫 WSAGetLastError。

錯誤碼	意義
WSA_IO_PENDING	已成功起始重迭的作業，稍後將會指出完成。
WSA_OPERATION_ABORTED	因為通訊端關閉或執行 SIO_FLUSH IOCTL 命令，所以已取消重迭的作業。
WSAEFAULT	lpOverlapped或lpCompletionRoutine參數完全不包含在使用者位址空間的有效部分。
WSAEINPROGRESS	當回呼正在進行時，會叫用函式。
WSAEINTR	封鎖作業已中斷。
WSAEINVAL	dwIoControlCode參數不是有效的命令，或無法接受指定的輸入參數，或命令不適用於指定的通訊端類型。如果 cbInBuffer 參數未設定為 Null，就會傳回此錯誤。
WSAENETDOWN	網路子系統失敗。
WSAENOBUFS	沒有可用的緩衝區空間。
WSAENOPROTOOPT	指定的通訊協定不支援通訊端選項。
WSAENOTSOCK	描述項 s 不是通訊端。
WSAEOPNOTSUPP	不支援指定的 IOCTL 命令。如果傳輸提供者不支援 SIO_ADDRESS_LIST_QUERY IOCTL，就會傳回此錯誤。

備註

Windows 2000 和更新版本的作業系統支援 SIO_ADDRESS_LIST_QUERY IOCTL。

SIO_ADDRESS_LIST_QUERY控制項程式碼會取得應用程式可系結的通訊端通訊協定系列本機傳輸地址清單。地址清單會根據地址系列而有所不同。

針對AF_INET6位址系列，除了下列各項之外，所有位址都會傳回：

任何重複位址偵測 (DAD) 狀態不是 IpDadStateP 參考的 IP 位址。
介面類別型 為IF_TYPE_SOFTWARE_LOOPBACK之介面上範圍層級低於 ScopeLevelSubnet 的任何 IP 位址。這表示 IF_TYPE_SOFTWARE_LOOPBACK類型介面 上的連結本機 (fe80：*) 和回送 (：：1) 位址已排除，但如果這些位址位於具有不同類型的介面上，則不會。

針對 AF_INET 位址系列，除了下列各項之外，所有位址都會傳回：

任何重複位址偵測 (DAD) 狀態不是 IpDadStateP 參考的 IP 位址。
介面類別型 為IF_TYPE_SOFTWARE_LOOPBACK且 連結為本機的介面上的任何 IP 位址。這表示連結本機 (169.254。) 和回送 (127。) IF_TYPE_SOFTWARE_LOOPBACK類型介面 上的位址會排除，但如果這些位址位於具有不同類型的介面上，則不會。

如需 DAD 狀態的詳細資訊，請參閱 有關IP_DAD_STATE 列舉和 IP_ADAPTER_UNICAST_ADDRESS 結構的 IP 協助程式檔，以及 MIB_UNICASTIPADDRESS_ROW 結構的 MIB 檔。如需介面類別型的詳細資訊，請參閱 IP_ADAPTER_ADDRESSES 結構和 GetAdaptersAddresses 函式的 IP 協助程式檔，以及 MIB_IF_ROW2 結構的 MIB 檔。如需範圍層級的詳細資訊，請參閱 IP_ADAPTER_ADDRESSES 結構和 SCOPE_LEVEL 列舉的 IP 協助程式檔。

lpvOutBuffer參數所指向輸出緩衝區中所傳回的清單格式為SOCKET_ADDRESS_LIST結構。

如果 lpvOutBuffer 參數中指定的輸出緩衝區不足以包含地址清單，則會傳回SOCKET_ERROR，因為此 IOCTL 的結果， 而 WSAGetLastError 會傳回 WSAEFAULT。在此情況下，輸出緩衝區的必要大小會以位元組為單位傳回 lkbBytesReturned 參數。請注意，如果lpvInBuffer、lpvOutBuffer或lBytesReturned參數未完全包含在使用者位址空間的有效部分，也會傳回WSAEFAULT錯誤碼。

SIO_ADDRESS_LIST_QUERY IOCTL 通常會以同步方式呼叫，並將lpvOverlapped參數設定為Null，因為會立即傳回地址清單。

注意在 Windows 隨插即用環境中，可以動態新增和移除位址。因此，應用程式無法依賴 SIO_ADDRESS_LIST_QUERY 傳回的資訊，才能持續運作。應用程式可以透過 SIO_ADDRESS_LIST_CHANGE IOCTL 登入位址變更通知，以透過重迭的 I/O 或 FD_ADDRESS_LIST_CHANGE 事件提供通知。下列動作序列可用來保證應用程式一律有目前的通訊清單資訊：

發出 SIO_ADDRESS_LIST_CHANGE IOCTL
發出 SIO_ADDRESS_LIST_QUERY IOCTL
每當 SIO_ADDRESS_LIST_CHANGE IOCTL 呼叫透過重迭的 I/O 或發出 FD_ADDRESS_LIST_CHANGE事件) 訊號來通知地址清單 (變更的應用程式時，應該重複整個動作序列。

在 Microsoft Windows 軟體發展工具組 (SDK) 針對 Windows Vista 和更新版本發行，標頭檔的組織已變更，且Ws2def.h標頭檔中定義了SIO_ADDRESS_LIST_QUERY控制程式代碼。請注意， Ws2def.h 標頭檔會自動包含在 Winsock2.h中，不應該直接使用。