WSANSPIoctl 関数 (winsock2.h)

  • [アーティクル]

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

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

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

[in] lpvInBuffer

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

[in, out] cbInBuffer

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

[out] lpvOutBuffer

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

[in] cbOutBuffer

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

[out] lpcbBytesReturned

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

[in] lpCompletion

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

戻り値

Success はNO_ERRORを返します。 Failure は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 関数はブロッキング呼び出しとして実行されます。 名前空間プロバイダーは直ちに を返す必要があり、ブロックしないでください。 ただし、各名前空間は、この動作を適用する役割を担います。

次の IOCTL コードは、いくつかの Microsoft ネーム スペース プロバイダーでサポートされています。

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

この 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 構造体を指している場合、重複した操作が正常に開始され、後で完了が示される場合、WSANSPIoctl 関数はWSA_IO_PENDINGを返します。 WSACOMPLETION 構造体で指定されたメソッドは、クエリ セットがまだ有効な場合にアプリケーションに通知するために使用されます。

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

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

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

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