IWDFPropertyStoreFactory::RetrieveDevicePropertyStore メソッド (wudfddi.h)

[警告: UMDF 2 は UMDF の最新バージョンであり、UMDF 1 よりも優先されます。 すべての新しい UMDF ドライバーは、UMDF 2 を使用して記述する必要があります。 UMDF 1 には新機能が追加されておらず、新しいバージョンのWindows 10では UMDF 1 のサポートが制限されています。 ユニバーサル Windows ドライバーでは UMDF 2 を使用する必要があります。 詳細については、「UMDF を使用したはじめに」を参照してください。

RetrieveDevicePropertyStore メソッドは、ドライバーがレジストリへのアクセスに使用できるプロパティ ストア インターフェイスを取得します。

構文

HRESULT RetrieveDevicePropertyStore(
  [in]  PWDF_PROPERTY_STORE_ROOT          RootSpecifier,
  [in]  WDF_PROPERTY_STORE_RETRIEVE_FLAGS Flags,
  [in]  REGSAM                            DesiredAccess,
  [in]  PCWSTR                            SubkeyPath,
  [out] IWDFNamedPropertyStore2           **PropertyStore,
  [out] WDF_PROPERTY_STORE_DISPOSITION    *Disposition
);

パラメーター

[in] RootSpecifier

ドライバーによって割り当てられたWDF_PROPERTY_STORE_ROOT構造体 の アドレス。 ドライバーは、この構造体を入力して、 RetrieveDevicePropertyStore が取得するプロパティ ストアを識別します。

[in] Flags

UMDF が存在しない場合に指定したレジストリ エントリを作成するかどうか、および Windows の再起動時に新しいエントリを削除するかどうかを指定する、 WDF_PROPERTY_STORE_RETRIEVE_FLAGS型のフラグ。

[in] DesiredAccess

ドライバーが持つレジストリへのアクセスの種類を指定する REGSAM 型のビット マスク。 REGSAM 型は Winreg.h で定義され、REGSAM のWindows SDKで説明されています。 ビット マスクでは、GENERIC_WRITE、KEY_CREATE_SUB_KEY、またはWRITE_DACアクセスを指定することはできません。 (ドライバーはKEY_CREATE_SUB_KEYを指定できませんが、 RetrieveDevicePropertyStore の呼び出しでサブキーを作成できます)。

[in] SubkeyPath

RootSpecifier パラメーターが指定するレジストリ キーの下にあるサブキーの名前を表す、呼び出し元が指定した文字列へのポインター。 このパラメーターは省略可能であり、 NULL にすることができます。 詳細については、「解説」を参照してください。

[out] PropertyStore

IWDFNamedPropertyStore2 インターフェイスへのポインターを受け取る場所のアドレス。 ドライバーは、このインターフェイスを使用してレジストリ内の値にアクセスします。

[out] Disposition

WDF_PROPERTY_STORE_DISPOSITION型指定された値を受け取る場所のアドレス。

戻り値

RetrieveDevicePropertyStore は、操作が成功した場合にS_OKを返します。 それ以外の場合、メソッドは次のいずれかの値を返す可能性があります。

このメソッドは、Winerror.h に含まれる他の値のいずれかを返す場合があります

注釈

ドライバーは RetrieveDevicePropertyStore を呼び出して、ドライバーのソフトウェア キー、現在のデバイスのハードウェア キー、現在のデバイスでサポートされているデバイス インターフェイスのキー、または DEVICEMAP キーへのアクセスを取得できます。

SubkeyPath パラメーターを指定する場合は、ドライバーのサービス名などの一意の名前を使用する必要があります。 ドライバーは、サブキーを使用してデバイス固有の情報を格納する場合があります。

RetrieveDevicePropertyStore を使用してレジストリにアクセスする方法の詳細については、「UMDF ベースのドライバーでのレジストリの使用」を参照してください。

例

次のコード例では、デバイスのハードウェア キーの 下にある PortName エントリに割り当てられている値を取得します。

IWDFPropertyStoreFactory *pPropertyStoreFactory = NULL;
WDF_PROPERTY_STORE_ROOT RootSpecifier;
IWDFNamedPropertyStore2 * pHardwarePropertyStore2 = NULL;
PROPVARIANT comPortPV;
WCHAR portName[] = L"PortName";
HRESULT hr;
...
//
// Get the property store factory interface.
//
hr = m_FxDevice->QueryInterface(IID_PPV_ARGS(&pPropertyStoreFactory));
if (FAILED(hr))
{
    goto Exit;
}
//
//Initialize the WDF_PROPERTY_STORE_ROOT structure. We want to open the 
// \Device Parameters subkey under the device's hardware key.
//
RtlZeroMemory(&RootSpecifier,
              sizeof(WDF_PROPERTY_STORE_ROOT));
RootSpecifier.LengthCb = sizeof(WDF_PROPERTY_STORE_ROOT);
RootSpecifier.RootClass = WdfPropertyStoreRootClassHardwareKey;
RootSpecifier.Qualifier.HardwareKey.ServiceName = WDF_PROPERTY_STORE_HARDWARE_KEY_ROOT;

//
// Get the property store interface for the hardware key of the
// device that m_FxDevice represents.
//
hr = pPropertyStoreFactory->RetrieveDevicePropertyStore(
                                           &RootSpecifier,
                                           WdfPropertyStoreNormal,
                                           KEY_QUERY_VALUE,
                                           NULL,
                                           &pHardwarePropertyStore2,
                                           NULL
                                           );
if (FAILED(hr))
{
    goto Exit;
}

//
// Get the value of the "PortName" entry, which is stored under 
// the device's \Device Parameters subkey.
//
PropVariantInit(&comPortPV);
hr = pHardwarePropertyStore2->GetNamedValue(portName,
                                            &comPortPV);
if (FAILED(hr))
{
   goto Exit;
}
...
Exit:
    SAFE_RELEASE(pHardwarePropertyStore2);
    SAFE_RELEASE(pPropertyStoreFactory);
...

要件

こちらもご覧ください

IWDFDevice::RetrieveDevicePropertyStore

IWDFDeviceInitialize::RetrieveDevicePropertyStore

IWDFPropertyStoreFactory