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 パラメーターに使用できる値は、名前空間プロバイダーによって決まります。

次の値は、Network Location Awareness (NS_NLA) 名前空間プロバイダーを含む複数の Microsoft 名前空間プロバイダーでサポートされています。 この IOCTL は Winsock2.h ヘッダー ファイルで定義されています。

値 説明
SIO_NSP_NOTIFY_CHANGE
 この操作は、 hLookup パラメーターを使用して以前の呼び出しで返された結果がまだ有効かどうかを確認します。 これらの以前の呼び出しには、hLookup パラメーターを取得するための NSPLookupServiceBegin 関数の最初の呼び出しが含まれます。 これらの以前の呼び出しには、hLookup パラメーターを使用した NSPLookupServiceNext 関数の呼び出しも含まれる場合があります。

[in] lpvInBuffer

入力バッファーへのポインター。

[in, out] cbInBuffer

入力バッファーのサイズ (バイト単位)。

[out] lpvOutBuffer

出力バッファーへのポインター。

[in] cbOutBuffer

出力バッファーのサイズ (バイト単位)。

[out] lpcbBytesReturned

返されるバイト数へのポインター。

[in] lpCompletion

非同期処理に使用される WSACOMPLETION 構造体へのポインター。 lpCompletion を NULL に設定して、ブロック (同期) 実行を強制します。

[in] lpThreadId

WPUQueueApc への後続の呼び出しでプロバイダーによって使用される WSATHREADID 構造体へのポインター。 プロバイダーは、WPUQueueApc 関数が返されるまで、参照先の WSATHREADID 構造体 (ポインターではなく) を格納する必要があります。

戻り値

エラーが発生せず、操作がすぐに完了した場合、 NSPIoctl 関数は NO_ERROR (ゼロ) を返す必要があります。 この場合、完了ルーチン (指定されている場合) は既にキューに登録されていることに注意してください。

NSPIoctl 関数は、ルーチンが失敗し、WSASetLastError を使用して適切なエラー コードを設定する必要がある場合は、SOCKET_ERROR (つまり 1) を返す必要があります。

エラー コード 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 パラメーターは non-**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 関数はブロッキング呼び出しとして実行されます。 名前空間プロバイダーは直ちに を返す必要があり、ブロックしないでください。 ただし、各名前空間プロバイダーは、この動作を適用する責任があります。

次の IOCTL コードは、いくつかの Microsoft 名前空間プロバイダーでサポートされています。

SIO_NSP_NOTIFY_CHANGE
この操作は、 hLookup パラメーターを使用して以前の呼び出しで返された結果がまだ有効かどうかを確認します。 これらの以前の呼び出しには、hLookup パラメーターを取得するための NSPLookupServiceBegin 関数の最初の呼び出しが含まれます。 これらの以前の呼び出しには、hLookup パラメーターを使用した NSPLookupServiceNext 関数の呼び出しも含まれる場合があります。

この IOCTL をサポートする Microsoft 名前空間プロバイダーには、次のものが含まれます。

  • NS_NLA - ネットワークロケーション認識 (NLA) 名前空間プロバイダー。
  • NS_PNRPNAME - ピア名解決プロトコル (PNRP) 名前空間プロバイダー。
  • NS_PNRPCLOUD - ピア名解決プロトコル (PNRP) クラウド名前空間プロバイダー。

この IOCTL もサポートする他の Microsoft 以外の名前空間プロバイダーがインストールされている場合があります。

lpCompletion パラメーターが NULL の場合、この IOCTL は特別な動作を実装します。 この IOCTL の lpCompletion パラメーターが NULL の 場合、この操作はポーリングであり、直ちにを返します。 クエリ セットが有効なままの場合、 WSAEWOULDBLOCK はクエリ セットが有効なままであることを示す通知として返されます。 クエリ セットが変更され、無効な場合は、クエリ セットの無効化のポーリングで成功したことを示す NO_ERROR が返されます。

lpCompletion パラメーターが NULL ではなく、WSACOMPLETION 構造体を指している場合、重複した操作が正常に開始され、完了が後で示される場合、NSPIoctl 関数はWSA_IO_PENDINGを返します。 WSACOMPLETION 構造体で指定されたメソッドは、クエリ セットがまだ有効な場合にアプリケーションに通知するために使用されます。

すべての名前解決プロトコルでこの機能をサポートできるわけではないため、この関数呼び出しは WSAEOPNOTSUPP で失敗する可能性があります。 複数のプロバイダーからのデータを含むクエリは、この IOCTL を呼び出すことができず、 WSAEINVAL を返します。

現在、lpvInBuffer、cbInBuffer、lpvOutBuffer、cbOutBuffer の各パラメーターは、Microsoft 名前空間プロバイダーでは無視されています。

シングルスレッド アプリケーションの場合、 NSPIoctl 関数を使用する一般的な方法は次のとおりです。 クエリ データが引き続き有効であることを確認するには、NSPLookupServiceNext 関数呼び出しのたびに、完了ルーチン (lpCompletion パラメーターを NULL に設定) なしで、dwControlCode パラメーターを SIO_NSP_NOTIFY_CHANGE に設定して NSPIoctl 関数を呼び出します。 データが無効になった場合は、 NSPLookupServiceEnd 関数を呼び出してクエリ ハンドルを閉じます。 NSPLookupServiceBegin 関数を呼び出して新しいクエリ ハンドルを取得し、クエリを再度開始します。

マルチスレッド アプリケーションの場合、 NSPIoctl 関数を使用する一般的な方法は次のとおりです。 NSPLookupServiceBegin 関数の最初の呼び出しの後、完了ルーチンでSIO_NSP_NOTIFY_CHANGEに設定された dwControlCode パラメーターを使用して NSPIoctl 関数を呼び出します。 アプリケーションは、完了ルーチンで指定された通知のメカニズムを使用して、データが無効になったときに通知を受け取ります。 一般的なメカニズムの 1 つは、完了ルーチンで指定されたイベントを使用することです。 データが無効になった場合は、 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