WlanSetPsdIEDataList 関数 (wlanapi.h)
WlanSetPsdIeDataList 関数は、近接サービス探索 (PSD) 情報要素 (IE) データ リストを設定します。
構文
DWORD WlanSetPsdIEDataList(
[in] HANDLE hClientHandle,
[in] LPCWSTR strFormat,
[in] const PWLAN_RAW_DATA_LIST pPsdIEDataList,
PVOID pReserved
);
パラメーター
[in] hClientHandle
WlanOpenHandle 関数の以前の呼び出しによって取得されたクライアントのセッション ハンドル。
[in] strFormat
pPsdIEDataList パラメーターで渡される PSD IE データ リスト内の PSD IE の形式。 これは、検出に使用されるプロトコルの名前空間を指定する NULL で終わる URI 文字列です。
[in] pPsdIEDataList
設定する PSD IE データ リストを含む WLAN_RAW_DATA_LIST 構造体へのポインター。
pReserved
将来利用するために予約されています。 NULL に設定する必要があります。
戻り値
関数が成功した場合、戻り値は ERROR_SUCCESS です。
関数が失敗した場合、戻り値は次のいずれかの戻りコードになる可能性があります。
| リターン コード | 説明 |
|---|---|
|
パラメーターが正しくありません。 このエラーは、 hClientHandle が NULL であるか無効であるか、 pReserved が NULL でない場合に返されます。 |
|
ハンドル テーブルにハンドル hClientHandle が見つかりませんでした。 |
|
この関数は、サポートされていないプラットフォームから呼び出されました。 この値は、関数が SP3 の Windows XP から呼び出された場合、または SP2 クライアントを使用した Windows XP 用ワイヤレス LAN API から呼び出された場合に返されます。 |
|
さまざまなエラー コード。 |
解説
近接サービス探索プロトコルは、クライアントが物理的な近接通信でサービスを検出できるようにする Microsoft 独自のプロトコルです。これは、無線範囲によって定義されます。 近接サービス探索プロトコルの目的は、ビーコン フレームの一部としてサービスアドバタイズなどのサービス検出情報を伝達することです。 アドホック モードで動作するアクセス ポイント (AP) とステーション (STA) は、ビーコン フレームを定期的にブロードキャストします。 ビーコン フレームには、デバイスが提供するサービスに関連する検出情報を保持する 1 つまたは複数の独自の情報要素を含めることができます。
PSD IE は、パッシブ検出を目的として、上位レベルの探索プロトコルによって提供される圧縮された情報を送信するために使用されます。 検出に使用されるこのような上位レベルのプロトコルの 1 つは、WS-Discovery プロトコルです。 任意のプロトコルを検出に使用できます。
ワイヤレス LAN サービスがインストールされた Windows Vista および Windows Server 2008 では、アドホック クライアント、アドホック サービス、インフラストラクチャ クライアントのパッシブ検出がサポートされています。 つまり、アドホック サービスは、1 つ以上のビーコンで PSD IE を送信することで、利用可能なリソースまたはサービスをアドバタイズできます。 このビーコンがアドホックまたはインフラストラクチャ クライアントによって受信される保証はありません。
ワイヤレス LAN サービスがインストールされた Windows 7 および Windows Server 2008 R2 では、Windows Vista と同じ方法で、アドホック クライアント、アドホック サービス、インフラストラクチャ クライアントのパッシブ検出がサポートされます。 さらに、PSD IE は、ソフトウェアベースのワイヤレス アクセス ポイント (AP) であるワイヤレス ホステッド ネットワークでもサポートされています。 ワイヤレス Hosted Network を実行するローカル コンピューター上のアプリケーションでは、 WlanSetPsdIeDataList 関数を使用して、ワイヤレスホスト型ネットワークを開始する前に PSD IE を設定できます。 設定すると、PSD IEは、ワイヤレスホステッドネットワークが開始された後にビーコンとプローブの応答に含まれます。
ビーコンを送受信する各アプリケーションは、独自のPSD IEデータリストを維持します。 pPsdIEDataList パラメーターは、アプリケーションによって生成された PSD IEs のリストを指します。 各PSD IEの形式は次のとおりです。
| フィールド | 説明と値 |
|---|---|
| 要素 ID (1 バイト) | 221 |
| 長さ (1 バイト) | データ フィールドの長さ (バイト単位) に 8 を加えた値。 |
| OUI (3 バイト) | 組織一意識別子 (OUI) には、00 から 50-F2 の値が含まれている必要があります。 このパブリック OUI は Microsoft に登録されています。 |
| OUI 型 (1 バイト) | 近接サービス探索プロトコルの場合、OUI の種類には値 6 が含まれている必要があります。 |
| 識別子ハッシュの書式設定 (4 バイト) | strFormat パラメーターから計算された HMAC のビット 31 から 0。 |
| データ (変数) | 検出用のユーザー定義データが含まれます。 このフィールドの長さは 240 バイトを超えることはできません。 |
[Format identifier hash]\(識別子ハッシュのフォーマット\) フィールドには、PSD IE で実行される情報の形式が記述されています。 書式識別子の一元管理の必要性を回避しながら一意性を確保するために、 RFC 3986 で指定されている URI (Uniform Resource Identifier) の形式の文字列を使用して、形式を区別します。 ただし、転送は効率的である必要があり、information 要素内のスペースは限られているため、文字列は実際には送信されませんが、代わりにハッシュが送信されます。 ビーコンの受信側であるクライアントでは、ハッシュは既知の形式識別子のセットと照合されます。
[Format identifier hash]\(識別子の書式設定\) ハッシュ フィールドは、ビット 0... で表されます。 strFormat パラメーターで指定された形式識別子文字列に対するハッシュベースのメッセージ認証コード (HMAC) の 31。 HMAC は、PSD IE のデータ フィールドの形式を指定するために使用されます。 HMAC の計算に使用される数式は RFC 2104 で説明されています。 HMAC の計算のサンプル コードは、 RFC 4634 で指定されています。 HMAC を計算するときは、ハッシュ関数に SHA-256 を使用します。 使用されるキーは、"null" キー (認証キーへの NULL ポインター、 RFC 4634 のソース コードごとの長さ 0 の認証キー) です。 リトル エンディアン形式で Unicode UTF-16 としてエンコードされた入力テキストとして 、strFormat パラメーターの値 (スペースを含むが NULL 終端文字を除く) を使用します。
たとえば、 strFormat パラメーターが の場合、 http://schemas.xmlsoaps.org/ws/2004/10/discovery対応する HMAC の最初の 4 つのオクテットは になります 0xF8 0xCB 0x35 0x15。
strFormat パラメーターが の場合、http://schemas.microsoft.com/networking/discoveryformat/v2対応する HMAC の 4 つのオクテットは になります0xCF 0xF1 0x64 0x17。
ネットワーク経由で HMAC の最初の 4 オクテットを送信する場合は、最初の (左端の) オクテットを最初に送信します。
切り捨てられた HMAC に競合が発生する可能性があることに注意してください。つまり、HMAC の特定のビットから PSD IE のペイロードに対応する探索プロトコルを一意に判断できない可能性があります。 PSD IE を受信するアプリケーションは、特定の HMAC から使用される探索プロトコルで最適な推測を行い、接続が確立されたら、より高いレベルの検出プロトコルを再実行する必要があります。
最大で、5 つの PSD IEs をリストに渡すことができます。 また、PSD IE リストの合計長 (バイト単位) は、ビーコンの長さに関するハードウェアの制限によって制限される場合があります。
アプリケーションは WlanSetPsdIeDataList を何度も呼び出すことができます。 WlanSetPsdIeDataList が同じ strFormat で 2 回呼び出されると、最初の関数呼び出しによって設定されたWLAN_RAW_DATA_LISTの内容は、2 番目の呼び出しの WLAN_RAW_DATA_LIST ペイロードによって上書きされます。 pPsdIEDataList パラメーターを NULL に設定して WlanSetPsdIeDataList を呼び出すと、strFormat に関連付けられている PSD IE リストがクリアされます。 pPsdIEDataList パラメーターと strFormat パラメーターの両方を NULL に設定して WlanSetPsdIeDataList を呼び出すと、アプリケーションによって設定されたすべての PSD IE リストがクリアされます。
ワイヤレス サービスは、さまざまなアプリケーションによって設定された PSD IE データ リストを処理し、生 IE データ BLOB を生成します。 コンピューターは、任意のワイヤレス アダプターでアドホック ネットワークを作成または参加すると、ネットワークに関連付けられている PSD IE データ BLOB を含むビーコンを他のマシンに送信します。
ステーションは WlanExtractPsdIEDataList 関数を呼び出して、マシンからビーコンを受信した後に PSD IE データ リストを取得できます。
要件
| サポートされている最小のクライアント | Windows Vista [デスクトップ アプリのみ] |
| サポートされている最小のサーバー | Windows Server 2008 [デスクトップ アプリのみ] |
| 対象プラットフォーム | Windows |
| ヘッダー | wlanapi.h (Wlanapi.h を含む) |
| Library | Wlanapi.lib |
| [DLL] | Wlanapi.dll |