ホーム › NetworkManagement.WindowsConnectNow › IWCNDevice

IWCNDevice

COM

📘 Microsoft Learn (日本語) · English

IIDc100be9c-d33a-4a4b-bf23-bbef4663d017継承元IUnknown自前メソッド開始 vtbl3

公式ドキュメント

このインターフェイスを使用して、デバイスを構成し、セッションを開始します。

メソッド 11

vtbl = vtable インデックス(0始まり)。HSP等からCOMメソッドをインデックス指定で呼ぶ際に使用します。0〜2 は IUnknown。

vtbl 3 HRESULT SetPassword(WCN_PASSWORD_TYPE Type, DWORD dwPasswordLength, BYTE* pbPassword)

IWCNDevice::SetPassword メソッドは、認証方式の値と、必要に応じて保留中のセッションで使用されるパスワードを構成します。このメソッドは IWCNDevice::Connect の呼び出し前にのみ呼び出せます。

Type

WCN_PASSWORD_TYPE

セッションで使用される認証方式を指定する WCN_PASSWORD_TYPE 値。

値	意味
WCN_PASSWORD_TYPE_PUSH_BUTTON	PushButton 認証を使用します。dwPasswordLength の値は NULL でなければなりません。
WCN_PASSWORD_TYPE_PIN	PIN ベースの認証を使用します。

dwPasswordLength

DWORD

バッファー pbPassword のバイト数。

pbPassword

BYTE*

ASCII でエンコードされたパスワードのバイト配列。

戻り値

このメソッドは次のいずれかの値を返します。

戻り値	説明
S_OK	パスワードは保留中のセッションで使用されます。
E_INVALIDARG	パスワードの種類が WCN_PASSWORD_TYPE_PUSH_BUTTON であるにもかかわらず、パスワードの長さが 0 ではありません。パスワードの種類が WCN_PASSWORD_TYPE_PUSH_BUTTON でも WCN_PASSWORD_TYPE_PIN でもありません。

解説(Remarks)

バイト配列は NULL 終端されません。たとえば、パスワードが 4 桁の PIN の場合、dwPasswordLength に 4 を渡し、pbPassword は ASCII で PIN を格納した 4 バイトの配列を指す必要があります。

vtbl 4 HRESULT Connect(IWCNConnectNotify* pNotify)

IWCNDevice::Connect メソッドはセッションを開始します。

pNotify

IWCNConnectNotify*

inoptional

接続が正常に確立されたかどうかを通知する、実装済みの IWCNConnectNotify コールバックインターフェイスへのポインター。

戻り値

このメソッドは次のいずれかの値を返します。

戻り値	説明
S_OK	操作は成功しました。
HRESULT_FROM_WIN32(ERROR_NOT_SUPPORTED)	デバイスは、IWCNDevice::Set を介してキューに登録された接続オプションをサポートしていません。
WCN_E_PEER_NOT_FOUND	デバイスをネットワーク上で見つけられませんでした。

解説(Remarks)

このメソッドを呼び出した後は、他の IWCNDevice の 'Set' メソッドを呼び出すことはできません。接続が確立された後にデバイス設定を取り消したりロールバックしたりする方法はありません。

接続操作の完了時に通知が送信されないようにするには、IWCNConnectNotify コールバックインターフェイスの代わりに pNotify に NULL を渡すことができます。

vtbl 5 HRESULT GetAttribute(WCN_ATTRIBUTE_TYPE AttributeType, DWORD dwMaxBufferSize, BYTE* pbBuffer, DWORD* pdwBufferUsed)

IWCNDevice::GetAttribute メソッドは、デバイスからキャッシュされた属性を取得します。

AttributeType	WCN_ATTRIBUTE_TYPE	in	特定の属性値(たとえば WCN_PASSWORD_TYPE)を表す WCN_ATTRIBUTE_TYPE 値。
dwMaxBufferSize	DWORD	in	pbBuffer に割り当てられたサイズ(バイト単位)。
pbBuffer	BYTE*	out	ユーザーが割り当てたバッファー。正常に復帰した場合、属性の内容が格納されます。
pdwBufferUsed	DWORD*	out	復帰時に、属性のサイズ(バイト単位)が格納されます。

戻り値

このメソッドは次のいずれかの値を返します。

戻り値	説明
S_OK	属性が正常に取得されました。
HRESULT_FROM_WIN32(ERROR_NOT_FOUND)	指定された属性は利用できません。
HRESULT_FROM_WIN32(ERROR_INSUFFICIENT_BUFFER)	pbBuffer で指定されたバッファーは、返される属性値を格納するのに十分な大きさではありません。

解説(Remarks)

属性のサイズのみを問い合わせるには、dwMaxBufferSize に 0(ゼロ)を渡すことができます。この場合、pdwBufferUsed に適切な値が設定されます。

vtbl 6 HRESULT GetIntegerAttribute(WCN_ATTRIBUTE_TYPE AttributeType, DWORD* puInteger)

GetIntegerAttribute メソッドは、デバイスからキャッシュされた属性を整数として取得します。

AttributeType	WCN_ATTRIBUTE_TYPE	in	特定の属性値(たとえば WCN_PASSWORD_TYPE)を表す WCN_ATTRIBUTE_TYPE 値。
puInteger	DWORD*	out	取得した属性値を表す符号なし整数へのポインター。

戻り値

このメソッドは次のいずれかの値を返します。

戻り値	説明
S_OK	属性が正常に取得されました。
HRESULT_FROM_WIN32(ERROR_NOT_FOUND)	指定された属性は利用できません。
HRESULT_FROM_WIN32(ERROR_INSUFFICIENT_BUFFER)	pbBuffer で指定されたバッファーは、返される属性値を格納するのに十分な大きさではありません。
HRESULT_FROM_WIN32(ERROR_INVALID_DATATYPE)	この属性は整数として表現できません。たとえば、文字列である場合です。

vtbl 7 HRESULT GetStringAttribute(WCN_ATTRIBUTE_TYPE AttributeType, DWORD cchMaxString, LPWSTR wszString)

IWCNDevice::GetStringAttribute メソッドは、デバイスからキャッシュされた属性を文字列として取得します。

AttributeType	WCN_ATTRIBUTE_TYPE	in	特定の属性値(たとえば WCN_PASSWORD_TYPE)を表す WCN_ATTRIBUTE_TYPE 値。属性が本来文字列データ型でない場合(たとえば WCN_TYPE_VERSION は本来整数であり、WNC_TYPE_SSID は本来 BLOB です)、この関数は HRESULT_FROM_WIN32(ERROR_INVALID_DATATYPE) で失敗します。
cchMaxString	DWORD	in	バッファー wszString のサイズ(文字数)。
wszString	LPWSTR	out	ユーザーが割り当てたバッファー。正常に復帰した場合、ベンダー拡張の NULL 終端文字列値が格納されます。

戻り値

...

戻り値	説明
S_OK	属性が正常に取得されました。
HRESULT_FROM_WIN32(ERROR_NOT_FOUND)	指定された属性は利用できません。
HRESULT_FROM_WIN32(ERROR_INSUFFICIENT_BUFFER)	wszString で指定されたバッファーは、返される属性値を格納するのに十分な大きさではありません。
HRESULT_FROM_WIN32(ERROR_INVALID_DATATYPE)	この属性は文字列として表現できません。たとえば、整数である場合です。

vtbl 8 HRESULT GetNetworkProfile(DWORD cchMaxStringLength, LPWSTR wszProfile)

IWCNDevice::GetNetworkProfile メソッドは、デバイスからネットワークプロファイルを取得します。

cchMaxStringLength	DWORD	in	wszProfile に割り当てられたサイズ(文字数)。
wszProfile	LPWSTR	out	XML WLAN ネットワークプロファイルの種類を指定する文字列。

戻り値

このメソッドは次のいずれかの値を返します。

戻り値	説明
S_OK	ネットワークプロファイルが正常に取得されました。

解説(Remarks)

この関数は、IWCNDevice::Connect が呼び出され、セッションが正常に完了した後にのみ呼び出せます。

vtbl 9 HRESULT SetNetworkProfile(LPWSTR pszProfileXml)

IWCNDevice::SetNetworkProfile メソッドは、デバイスにプロビジョニングする XML WLAN プロファイルをキューに登録します。このメソッドは IWCNDevice::Connect の呼び出し前にのみ呼び出せます。

pszProfileXml

LPWSTR

XML WLAN プロファイルの XML 文字列。

戻り値

このメソッドは次のいずれかの値を返します。

戻り値	説明
S_OK	属性が正常に取得されました。
HRESULT_FROM_WIN32(ERROR_NOT_SUPPORTED)	この WLAN プロファイルは WCN 接続ではサポートされていません。
HRESULT_FROM_WIN32(ERROR_BAD_PROFILE)	指定された XML プロファイルを読み取れません。

解説(Remarks)

現在、Windows Connect Now API(WCNAPI)は次のプロファイルの種類をサポートしています。

なし(Open または Shared)
WEP(Open または Shared)
WPA-PSK(TKIP または AES)
WPA2-PSK(TKIP または AES)

指定された WLAN プロファイルに無関係な設定(IHV 設定など)が含まれている場合、それらの設定は無視されます。WLAN プロファイルが WCNAPI と互換性がない場合は、HRESULT_FROM_WIN32(ERROR_NOT_SUPPORTED) が返されます。

vtbl 10 HRESULT GetVendorExtension(WCN_VENDOR_EXTENSION_SPEC* pVendorExtSpec, DWORD dwMaxBufferSize, BYTE* pbBuffer, DWORD* pdwBufferUsed)

GetVendorExtension メソッドは、デバイスからキャッシュされたベンダー拡張を取得します。

pVendorExtSpec	WCN_VENDOR_EXTENSION_SPEC*	in	問い合わせるベンダー拡張を記述する、ユーザー定義の WCN_VENDOR_EXTENSION_SPEC 構造体へのポインター。
dwMaxBufferSize	DWORD	in	pbBuffer のサイズ(バイト単位)。
pbBuffer	BYTE*	out	割り当て済みのバッファー。復帰時に、ベンダー拡張の内容が格納されます。
pdwBufferUsed	DWORD*	out	復帰時に、ベンダー拡張のサイズ(バイト単位)が格納されます。

戻り値

このメソッドは次のいずれかの値を返します。

戻り値	説明
S_OK	ベンダー拡張が正常に取得されました。
HRESULT_FROM_WIN32(ERROR_NOT_FOUND)	指定されたベンダー拡張は利用できません。
HRESULT_FROM_WIN32(ERROR_INSUFFICIENT_BUFFER)	pbBuffer で指定されたバッファーは、返されるベンダー拡張を格納するのに十分な大きさではありません。

解説(Remarks)

ベンダー拡張のサイズを問い合わせるには、dwMaxBufferSize パラメーターに 0 を渡します。この場合、pdwBufferUsed がサイズを受け取ります。

vtbl 11 HRESULT SetVendorExtension(WCN_VENDOR_EXTENSION_SPEC* pVendorExtSpec, DWORD cbBuffer, BYTE* pbBuffer)

IWCNDevice::SetVendorExtension メソッドは、保留中のセッションで使用するベンダー拡張をキューに登録します。この関数は IWCNDevice::Connect の呼び出し前にのみ呼び出せます。

pVendorExtSpec	WCN_VENDOR_EXTENSION_SPEC*	in	ベンダー拡張の仕様を格納する WCN_VENDOR_EXTENSION_SPEC 構造体へのポインター。
cbBuffer	DWORD	in	pbBuffer に格納されているバイト数。
pbBuffer	BYTE*	in	ベンダー拡張に設定するデータを格納するバッファーへのポインター。

戻り値

このメソッドは次のいずれかの値を返します。

戻り値	説明
S_OK	ベンダー拡張は保留中のセッションで送信されます。
E_INVALIDARG	指定された WCN_VENDOR_EXTENSION_SPEC に不正な VendorID、サブタイプ、またはフラグが含まれています。
HRESULT_FROM_WIN32(ERROR_IMPLEMENTATION_LIMIT)	ベンダー拡張の数が現在の実装上の制限を超えました。現在の制限は 1 セッションあたり 25 個のベンダー拡張です。

vtbl 12 HRESULT Unadvise()

IWCNDevice::Unadvise メソッドは、IWCNDevice::Connect を介して以前に設定されたコールバックを削除します。

戻り値

このメソッドは値を返しません。

解説(Remarks)

アプリケーションがシャットダウン中で、IWCNConnectNotify コールバックでこれ以上コールバックを受け取らないようにする必要がある場合を除き、IWCNDevice::Unadvise を呼び出す必要はありません。 IWCNConnectNotify コールバック内から IWCNDevice::Unadvise を呼び出さないでください。デッドロックの原因となります。なお、IWCNDevice::Unadvise は、通信経路上の接続操作をキャンセルするものではありません。

vtbl 13 HRESULT SetNFCPasswordParams(WCN_PASSWORD_TYPE Type, DWORD dwOOBPasswordID, DWORD dwPasswordLength, BYTE* pbPassword, DWORD dwRemotePublicKeyHashLength, BYTE* pbRemotePublicKeyHash, DWORD dwDHKeyBlobLength, BYTE* pbDHKeyBlob)

Type	WCN_PASSWORD_TYPE	in	設定するパスワードの種類を示す WCN_PASSWORD_TYPE 列挙値を指定する。
dwOOBPasswordID	DWORD	in	NFC 経由で取得した帯域外(OOB)パスワードの識別子を指定する。
dwPasswordLength	DWORD	in	pbPassword が指すパスワードのバイト数を指定する。
pbPassword	BYTE*	inoptional	デバイスパスワードデータが格納されたバッファへのポインタである。
dwRemotePublicKeyHashLength	DWORD	in	pbRemotePublicKeyHash が指すハッシュのバイト数を指定する。
pbRemotePublicKeyHash	BYTE*	inoptional	リモートデバイスの公開鍵ハッシュが格納されたバッファへのポインタである。
dwDHKeyBlobLength	DWORD	in	pbDHKeyBlob が指す鍵 BLOB のバイト数を指定する。
pbDHKeyBlob	BYTE*	inoptional	Diffie-Hellman 鍵 BLOB が格納されたバッファへのポインタである。

出典・ライセンス: 上記「公式ドキュメント」の内容は Microsoft の Win32 API ドキュメント(MicrosoftDocs/sdk-api)を日本語に翻訳・改変したものです。© Microsoft Corporation. CC BY 4.0 で提供。
Microsoft 公式リファレンス: 英語 (en-us) · 日本語 (ja-jp) · 原文ソース (GitHub)

HSP用 COM定義

#usecom / #comfunc によるHSPのCOM呼び出し定義。数字は vtbl インデックス(0始まり)。クラスIDが無い場合 #usecom の末尾は "{}"、ある場合は "{CLSID}"。

出力引数:

#define global IID_IWCNDevice "{C100BE9C-D33A-4A4B-BF23-BBEF4663D017}"
#usecom global IWCNDevice IID_IWCNDevice "{}"
#comfunc global IWCNDevice_SetPassword           3 int,int,var
#comfunc global IWCNDevice_Connect               4 sptr
#comfunc global IWCNDevice_GetAttribute          5 int,int,var,var
#comfunc global IWCNDevice_GetIntegerAttribute   6 int,var
#comfunc global IWCNDevice_GetStringAttribute    7 int,int,var
#comfunc global IWCNDevice_GetNetworkProfile     8 int,var
#comfunc global IWCNDevice_SetNetworkProfile     9 wstr
#comfunc global IWCNDevice_GetVendorExtension    10 var,int,var,var
#comfunc global IWCNDevice_SetVendorExtension    11 var,int,var
#comfunc global IWCNDevice_Unadvise              12
#comfunc global IWCNDevice_SetNFCPasswordParams  13 int,int,int,var,int,var,int,var
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※出力/バッファ引数は var(変数直渡し)。varptr 方式にも切替可。
; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。#define global IID_IWCNDevice "{C100BE9C-D33A-4A4B-BF23-BBEF4663D017}"
#usecom global IWCNDevice IID_IWCNDevice "{}"
#comfunc global IWCNDevice_SetPassword           3 int,int,sptr
#comfunc global IWCNDevice_Connect               4 sptr
#comfunc global IWCNDevice_GetAttribute          5 int,int,sptr,sptr
#comfunc global IWCNDevice_GetIntegerAttribute   6 int,sptr
#comfunc global IWCNDevice_GetStringAttribute    7 int,int,sptr
#comfunc global IWCNDevice_GetNetworkProfile     8 int,sptr
#comfunc global IWCNDevice_SetNetworkProfile     9 wstr
#comfunc global IWCNDevice_GetVendorExtension    10 sptr,int,sptr,sptr
#comfunc global IWCNDevice_SetVendorExtension    11 sptr,int,sptr
#comfunc global IWCNDevice_Unadvise              12
#comfunc global IWCNDevice_SetNFCPasswordParams  13 int,int,int,sptr,int,sptr,int,sptr
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。
; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。