共用方式為

WSANSPIoctl 函式 (winsock2.h)

  • 發行項

Windows Sockets WSANSPIoctl 函式可讓開發人員對已註冊的命名空間進行 I/O 控制項呼叫。

語法

INT WSAAPI WSANSPIoctl(
  [in]      HANDLE          hLookup,
  [in]      DWORD           dwControlCode,
  [in]      LPVOID          lpvInBuffer,
  [in, out] DWORD           cbInBuffer,
  [out]     LPVOID          lpvOutBuffer,
  [in]      DWORD           cbOutBuffer,
  [out]     LPDWORD         lpcbBytesReturned,
  [in]      LPWSACOMPLETION lpCompletion
);

參數

[in] hLookup

從先前呼叫 WSALookupServiceBegin 函式傳回的查閱句柄。

[in] dwControlCode

要執行的作業控制程式碼。

可用於 dwControlCode 參數的值是由命名空間提供者決定。

數個 Microsoft 命名空間提供者支援下列值，包括網路位置感知 (NS_NLA) 命名空間提供者。 此 IOCTL 定義於 Winsock2.h 頭檔中。

值 意義
SIO_NSP_NOTIFY_CHANGE
 這項作業會檢查使用 hLookup 參數以先前呼叫傳回的結果是否仍然有效。 這些先前的呼叫包括 WSALookupServiceBegin 函式的初始呼叫，以擷取 hLookup 參數。 這些先前的呼叫也可能包含使用 hLookup 參數呼叫 WSALookupServiceNext 函式。

[in] lpvInBuffer

輸入緩衝區的指標。

[in, out] cbInBuffer

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

[out] lpvOutBuffer

輸出緩衝區的指標。

[in] cbOutBuffer

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

[out] lpcbBytesReturned

傳回位元組數目的指標。

[in] lpCompletion

WSACOMPLETION 結構的指標，用於異步處理。 將 lpCompletion 設定為 NULL ，強制 (封鎖同步) 執行。

傳回值

成功會傳回NO_ERROR。 失敗會傳回SOCKET_ERROR，而且可以藉由呼叫 WSAGetLastError 函式來擷取特定的錯誤碼。 下表描述錯誤碼。

錯誤碼 描述
WSA_INVALID_HANDLE
 hLookup 參數不是 WSALookupServiceBegin 所傳回的有效查詢句柄。
WSA_IO_PENDING
 已成功起始重疊的作業，稍後將會指出完成。
WSAEFAULT
 lpvInBuffer、cbInBuffer、lpvOutBuffer、cbOutBuffer 或 lpCompletion 自變數並未完全包含在使用者地址空間的有效部分。 或者， cbInBuffer 或 cbOutBuffer 自變數太小，而且會修改自變數以反映所需的配置大小。
WSAEINVAL
 無法接受提供的 參數，或者當指定作業不合理時，作業會不適當地傳回多個命名空間的結果。
WSAENETDOWN
 網路子系統失敗。
WSAEOPNOTSUPP
 不支援此作業。 如果命名空間提供者未實作此函式，就會傳回此錯誤。 如果指定的 dwControlCode 是無法辨識的命令，也可以傳回此錯誤。
WSAEWOULDBLOCK
 套接字未使用重疊的 I/O (異步處理) ，但 lpCompletion 參數不是 NULL。

當 lpCompletion 參數為 NULL (輪詢) 時，這個錯誤會當做SIO_NSP_NOTIFY_CHANGE IOCTL 的特殊通知，以指出查詢集仍然有效。

備註

WSANSPIoctl 函式可用來設定或擷取與命名空間提供者查詢句柄相關聯的作業參數。 hLookup 參數是先前由 WSALookupServiceBegin 函式傳回之命名空間提供者查詢的句柄， (不是套接字句柄) 。

傳送至命名空間提供者的任何 IOCTL 可能會無限期地封鎖，視命名空間的實作而定。 如果應用程式無法在 WSANSPIoctl 函數調用中容許封鎖，則應使用重疊的 I/O， 而 lpCompletion 參數應該指向 WSACOMPLETION 結構。 若要讓 WSANSPIoctl 函式呼叫非封鎖並立即傳回，請將 WSACOMPLETION 結構的 Type 成員設定為NSP_NOTIFY_IMMEDIATELY。

如果 lpCompletion 為 NULL，WSANSPIoctl 函式會以封鎖呼叫的形式執行。 命名空間提供者應該立即傳回，不應封鎖。 但每個命名空間都負責強制執行此行為。

數個 Microsoft 名稱空間提供者支援下列 IOCTL 程式代碼：

SIO_NSP_NOTIFY_CHANGE
這項作業會檢查使用 hLookup 參數以先前呼叫傳回的結果是否仍然有效。 這些先前的呼叫包括 WSALookupServiceBegin 函式的初始呼叫，以擷取 hLookup 參數。 這些先前的呼叫也可能包含使用 hLookup 參數呼叫 WSALookupServiceNext 函式。

支援此 IOCTL 的 Microsoft 命名空間提供者包括下列專案

  • NS_NLA - 網路位置感知 (NLA) 命名空間提供者。
  • NS_PNRPNAME - 對等名稱解析通訊協定 (PNRP) 命名空間提供者。
  • NS_PNRPCLOUD - 對等名稱解析通訊協定 (PNRP) 雲端命名空間提供者。

您也可以安裝其他非 Microsoft 命名空間提供者，同時支援此 IOCTL。

當 lpCompletion 參數為 NULL 時，這個 IOCTL 會實作特殊行為。 如果這個 IOCTL 的 lpCompletion 參數為 NULL ，則此作業為輪詢並立即傳回。 如果查詢集維持有效狀態，則會以查詢集保持有效的通知傳回 WSAEWOULDBLOCK 。 如果查詢集已變更且無效，則會傳回 NO_ERROR ，表示輪詢查詢集無效。

如果 lpCompletion 參數不是 NULL ，而且指向 WSACOMPLETION 結構，則 WSANSPIoctl 函式會傳回 WSA_IO_PENDING 如果重疊的作業已成功起始且稍後會指出完成。 WSACOMPLETION 結構中指定的方法可用來在查詢集仍然有效時通知應用程式。

並非所有名稱解析通訊協定都能夠支援此功能，因此，此函式呼叫可能會因為 WSAEOPNOTSUPP 而失敗。 包含來自多個提供者數據的查詢無法呼叫此 IOCTL，而且會傳回 WSAEINVAL。

Microsoft 命名空間提供者目前會忽略 lpvInBuffer、 cbInBuffer、 lpvOutBuffer 和 cbOutBuffer 參數。

對於單個線程應用程式，使用 WSANSPIoctl 函式的一般方法如下所示。 呼叫 WSANSPIoctl 函式，並將 dwControlCode 參數設定為 SIO_NSP_NOTIFY_CHANGE， (而且在每次 WSALookupServiceNext 函數呼叫之後，lpCompletion 參數都設定為 NULL) ，以確保查詢數據仍然有效。 如果數據無效，請呼叫 WSALookupServiceEnd 函式以關閉查詢句柄。 呼叫 WSALookupServiceBegin 函式以擷取新的查詢句柄，然後再次開始查詢。

對於多線程應用程式，使用 WSANSPIoctl 函式的一般方法如下所示。 呼叫 WSANSPIoctl 函式，並將 dwControlCode 參數設定為 SIO_NSP_NOTIFY_CHANGE ，在 WSALookupServiceBegin 函式的初始呼叫之後使用完成例程。 應用程式會使用完成例程中指定的通知機制，在數據不再有效時收到通知。 其中一個常見機制是使用完成例程中指定的事件。 如果數據無效，請呼叫 WSALookupServiceEnd 函式以關閉查詢句柄。 呼叫 WSALookupServiceBegin 和 WSANSPIoctl 函式以擷取新的查詢句柄，然後再次開始查詢。

某些通訊協定可能會直接在本機快取資訊，並在一段時間后失效，在此情況下，可能會發出通知來指出本機快取已失效。

對於不常變更的名稱解析通訊協定，命名空間提供者可能會指出全域變更事件，這些事件可能不適用於要求和發出變更通知的查詢。

即時輪詢作業通常成本較低，因為它們不需要通知物件。 在大部分情況下，這會實作為簡單的布爾變數檢查。 不過，異步通知可能需要建立專用的背景工作線程和/或進程間通道，視命名空間提供者服務的實作而定，而且會產生與發出變更事件訊號之通知對象相關的處理額外負荷。

若要取消異步通知要求，請在受影響的查詢句柄上使用 WSALookupServiceEnd 函式呼叫結束原始查詢。 取消LUP_NOTIFY_HWND的異步通知不會張貼任何訊息，不過，將會完成重疊的作業，並傳送通知並顯示錯誤 WSA_OPERATION_ABORTED。

注意 當該線程結束時，由指定線程起始的所有 I/O 都會取消。 對於重疊的套接字，如果線程在作業完成之前關閉線程，擱置的異步操作可能會失敗。 如需詳細資訊，請參閱 ExitThread 。
 
Windows Phone 8：Windows Phone 8 和更新版本 Windows Phone 市集應用程式支援此函式。

Windows 8.1 和 Windows Server 2012 R2：Windows 8.1、Windows Server 2012 R2 及更新版本上的 Windows 市集應用程式支援此函式。

規格需求

需求 值
最低支援的用戶端 Windows 8.1、Windows Vista [傳統型應用程式 |UWP 應用程式]
最低支援的伺服器 Windows Server 2003 [傳統型應用程式 |UWP 應用程式]
目標平台 Windows
標頭 winsock2.h

另請參閱

ExitThread

WSACOMPLETION

WSAGetLastError

WSALookupServiceBegin

WSALookupServiceEnd

WSALookupServiceNext

Winsock 函式