IWDFUnifiedPropertyStore::GetPropertyData メソッド (wudfddi.h)
[警告: UMDF 2 は UMDF の最新バージョンであり、UMDF 1 よりも優先されます。 すべての新しい UMDF ドライバーは、UMDF 2 を使用して記述する必要があります。 UMDF 1 には新機能が追加されておらず、新しいバージョンのWindows 10では UMDF 1 のサポートが制限されています。 ユニバーサル Windows ドライバーでは UMDF 2 を使用する必要があります。 詳細については、「UMDF を使用したはじめに」を参照してください。
GetPropertyData メソッドは、デバイス プロパティの現在の設定を取得します。
構文
HRESULT GetPropertyData(
[in] const DEVPROPKEY *PropertyKey,
[in] LCID Lcid,
[in] ULONG Flags,
[in] ULONG PropertyDataSize,
[out, optional] PVOID PropertyData,
[out] ULONG *PropertyDataRequiredSize,
[out] DEVPROPTYPE *PropertyType
);
パラメーター
[in] PropertyKey
デバイス プロパティ キーを指定する DEVPROPKEY 構造体へのポインター。
[in] Lcid
ロケール識別子を指定します。 このパラメーターは、言語固有の LCID 値または LOCALE_NEUTRALに設定します。 LOCALE_NEUTRAL LCID は、 プロパティが言語に依存しないことを指定します (つまり、どの言語にも固有ではありません)。 このパラメーターは、LOCALE_SYSTEM_DEFAULTまたはLOCALE_USER_DEFAULTに設定しないでください。 言語固有の LCID 値の詳細については、「 LCID 構造体」を参照してください。
[in] Flags
システムで使用するために予約されています。 ドライバーは、この値を 0 に設定する必要があります。
[in] PropertyDataSize
PropertyData が指すバッファーのサイズ (バイト単位)。
[out, optional] PropertyData
デバイス プロパティ データへのポインター。
[out] PropertyDataRequiredSize
PropertyData で返されるプロパティ情報のサイズを受け取る ULONG へのポインター。
[out] PropertyType
DEVPROPTYPE 値へのポインター。 GetPropertyData が正常に完了した場合、メソッドは PropertyType を使用して PropertyData バッファーで返されるデータの型を指定します。
戻り値
GetPropertyData は、操作が成功した場合にS_OKを返します。 それ以外の場合、メソッドは次の値を返す可能性があります。
| リターン コード | 説明 |
|---|---|
|
フレームワークのメモリの割り当て試行が失敗しました。 |
|
PropertyDataRequiredSize パラメーターには、必要なバッファーのサイズが含まれています。 |
|
ドライバーが WdfPropertyStoreRootClassDeviceInterfaceKey を指定する場合、要求されたインターフェイスは、UMDF ドライバーが以前に登録したインターフェイスである必要があります。 |
|
ドライバーは、Windows 8以降でのみ、デバイス インターフェイスのプロパティ データを要求できます。 |
このメソッドは 、Winerror.h に含まれる他の値のいずれかを返す場合があります。
注釈
フレームワーク ベースのドライバーは 、GetPropertyData メソッドを使用して、統合デバイス プロパティ モデルの一部として定義されているデバイス プロパティを取得します。
特に、このメソッドを使用して、デバイスの ハードウェア キー またはデバイス インターフェイス クラスのインスタンスを取得できます。 IWDFUnifiedPropertyStoreFactory::RetrieveUnifiedDevicePropertyStore を呼び出すときに、RootSpecifier パラメーターの RootClass メンバーを WdfPropertyStoreRootClassHardwareKey または WdfPropertyStoreRootClassDeviceInterfaceKey に設定します。
WdfPropertyStoreRootClassHardwareKey を指定した場合は、GetPropertyData を呼び出すときに、PnP で定義されたキーではなく、PropertyKey パラメーターにカスタム DEVPROPKEY 値を指定する必要があります。 値は、 SetPropertyData、 SetupDI デバイス プロパティ関数、または INF AddProperty ディレクティブを使用して、以前に設定されている必要があります。
デバイスのプロパティの詳細については、「 デバイスのプロパティ」を参照してください。
レジストリへのアクセスの詳細については、「 UMDF ベースのドライバーでのレジストリの使用」を参照してください。
例
可変サイズのプロパティの場合、ドライバーはプロパティ データを取得するために 2 つのパスを作成する必要があります。 最初に、ドライバーは PropertyData パラメーターに NULL バッファーを渡し、 PropertyDataSize を 0 に設定する必要があります。 次に、ドライバーは返された PropertyDataRequiredSize に基づいてバッファーを割り当て、割り当てられたバッファーを渡して GetPropertyData を再度呼び出す必要があります。
次の例でそのパターンを示します。
HRESULT
GetFriendlyName(
_In_ IWDFUnifiedPropertyStore * pUnifiedPropertyStore
)
{
HRESULT hr = S_OK;
DEVPROPTYPE type;
ULONG requiredSize;
BYTE * friendlyNameBuffer = NULL;
ULONG friendlyNameBufferSize;
hr = pUnifiedPropertyStore->GetPropertyData(
&DEVPKEY_Device_FriendlyName,
0, //Lcid
0, //Flags
0, //BufferSize
NULL, //Buffer
&requiredSize,
&type
);
if (HRESULT_CODE(hr) != ERROR_INSUFFICIENT_BUFFER)
{
TraceEvents(
TRACE_LEVEL_ERROR,
TEST_TRACE_DEVICE,
"GetPropertyData failed: hr = %!HRESULT!",
hr
);
goto exit;
}
friendlyNameBufferSize = requiredSize;
friendlyNameBuffer = new BYTE[requiredSize];
if (NULL == friendlyNameBuffer)
{
hr = E_OUTOFMEMORY;
TraceEvents(
TRACE_LEVEL_ERROR,
TEST_TRACE_DEVICE,
"Out of memory while allocating property data buffer returning:”
“ %!HRESULT!",
hr
);
goto exit;
}
hr = pUnifiedPropertyStore->GetPropertyData(
&DEVPKEY_Device_FriendlyName,
0, //Lcid
0, //Flags
friendlyNameBufferSize,
friendlyNameBuffer,
&requiredSize,
&type
);
if (FAILED(hr))
{
TraceEvents(
TRACE_LEVEL_ERROR,
TEST_TRACE_DEVICE,
"GetPropertyData failed: hr = %!HRESULT!",
hr
);
goto exit;
}
if (type != DEVPROP_TYPE_STRING)
{
TraceEvents(
TRACE_LEVEL_ERROR,
TEST_TRACE_DEVICE,
"Expected type %d, actual type: %d",
DEVPROP_TYPE_STRING,
type
);
hr = E_UNEXPECTED;
goto exit;
}
exit:
delete [] friendlyNameBuffer;
friendlyNameBuffer = NULL;
return hr;
}
要件
| 要件 | 値 |
|---|---|
| サポート終了 | UMDF 2.0 以降では使用できません。 |
| 対象プラットフォーム | デスクトップ |
| 最小 UMDF バージョン | 1.11 |
| Header | wudfddi.h |
| [DLL] | WUDFx.dll |
こちらもご覧ください
IWDFUnifiedPropertyStoreFactory