LPNSPIOCTL 回呼函式 (ws2spi.h)

  • 發行項

NSPIoctl函式會將 IOCTL 傳送至命名空間服務提供者。

語法

LPNSPIOCTL Lpnspioctl;

INT Lpnspioctl(
  [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]      LPWSATHREADID lpThreadId
)
{...}

參數

[in] hLookup

從先前呼叫 NSPLookupServiceBegin 函式傳回的查閱控制碼。

[in] dwControlCode

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

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

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

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

[in] lpvInBuffer

輸入緩衝區的指標。

[in, out] cbInBuffer

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

[out] lpvOutBuffer

輸出緩衝區的指標。

[in] cbOutBuffer

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

[out] lpcbBytesReturned

傳回位元組數目的指標。

[in] lpCompletion

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

[in] lpThreadId

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

傳回值

如果沒有發生錯誤，而且作業已立即完成， NSPIoctl 函式應該會傳回 NO_ERROR (零) 。 請注意，在此情況下，如果已指定，則完成常式已排入佇列。

NSPIoctl函式應該傳回SOCKET_ERROR (，也就是說，如果常式失敗，則傳回 1) ，而且必須使用WSASetLastError設定適當的錯誤碼。

錯誤碼WSA_IO_PENDING指出已成功起始重迭的作業，且稍後將會指出完成。 任何其他錯誤碼都表示未起始重迭的作業，也不會發生任何完成指示。

錯誤碼 描述
WSA_INVALID_HANDLE
 hLookup參數不是NSPLookupServiceBegin所傳回的有效查詢控制碼。
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 的特殊通知，以指出查詢集仍然有效。

備註

NSPIoctl函式可用來將 I/O 控制項程式碼傳送至命名空間提供者，以設定或擷取與查詢控制碼相關聯的作業參數。 hLookup參數是NSPLookupServiceBegin函式先前傳回之命名空間提供者查詢的控制碼， (不是通訊端控制碼) 。

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

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

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

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

支援此 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 結構， 則 NSPIoctl 函式會傳回 WSA_IO_PENDING 如果重迭的作業已成功起始，且稍後將會指出完成。 WSACOMPLETION結構中指定的方法可用來在查詢集仍然有效時通知應用程式。

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

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

對於單一執行緒應用程式，使用 NSPIoctl 函式的一般方法如下所示。 呼叫NSPIoctl函式，並將dwControlCode參數設定為SIO_NSP_NOTIFY_CHANGE (，而lpCompletion參數會在每次NSPLookupServiceNext函數呼叫之後，將 lpCompletion 參數設定為Null) ，以確保查詢資料仍然有效。 如果資料無效，請呼叫 NSPLookupServiceEnd 函式以關閉查詢控制碼。 呼叫 NSPLookupServiceBegin 函式以擷取新的查詢控制碼，然後再次開始查詢。

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

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

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

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

若要取消非同步通知要求，請在受影響的查詢控制碼上使用 NSPLookupServiceEnd 函式通話結束原始查詢。 取消LUP_NOTIFY_HWND的非同步通知不會張貼任何訊息，不過，將會完成重迭的作業，並傳送通知並顯示錯誤 WSA_OPERATION_ABORTED。

**注意** 當該執行緒結束時，由指定執行緒起始的所有 I/O 都會取消。 對於重迭的通訊端，如果執行緒在作業完成之前關閉執行緒，擱置的非同步作業可能會失敗。 如需詳細資訊，請參閱 ExitThread 。
 

規格需求

   
最低支援的用戶端 Windows XP [僅限傳統型應用程式]
最低支援的伺服器 Windows Server 2003 [僅限傳統型應用程式]
目標平台 Windows
標頭 ws2spi.h

另請參閱

NSPLookupServiceBegin

NSPLookupServiceEnd

NSPLookupServiceNext

NSPStartup

NSP_ROUTINE

WPUQueueApc

WSACOMPLETION

WSATHREADID