PSCreateDelayedMultiplexPropertyStore 関数 (propsys.h)

複数のプロパティ ストアを含む読み取り専用の遅延バインディング プロパティ ストアを作成します。

構文

PSSTDAPI PSCreateDelayedMultiplexPropertyStore(
        GETPROPERTYSTOREFLAGS        flags,
        IDelayedPropertyStoreFactory *pdpsf,
  [in]  const DWORD                  *rgStoreIds,
  [in]  DWORD                        cStores,
  [in]  REFIID                       riid,
  [out] void                         **ppv
);

パラメーター

flags

型: GETPROPERTYSTOREFLAGS

1 つ以上 の GETPROPERTYSTOREFLAGS 値。 これらの値は、作成されたプロパティ ストア オブジェクトの詳細を指定します。

pdpsf

種類: IDelayedPropertyStoreFactory*

IDelayedPropertyStoreFactory のインスタンスへのインターフェイス ポインター。

[in] rgStoreIds

型: const DWORD*

プロパティ ストア ID の配列へのポインター。 この配列を初期化する必要はありません。

[in] cStores

型: DWORD

rgStoreIds が指す配列内の要素の数。

[in] riid

種類: REFIID

作成されたプロパティ ストアを表すインターフェイスの要求された IID への参照。

[out] ppv

型: void**

この関数が戻るとき、 には 、riid で要求されたインターフェイス ポインターが含まれます。 これは通常 、IPropertyStore です。

戻り値

種類: HRESULT

この関数が成功すると、 S_OKが返されます。 そうでない場合は、HRESULT エラー コードを返します。

注釈

この関数は、IPropertyStore、INamedPropertyStore、IObjectProvider、および IPropertyStoreCapabilities を実装するコンポーネント オブジェクト モデル (COM) オブジェクトを作成します。

アプリケーションは、一度に 1 つのスレッドからこのオブジェクトを呼び出す必要があります。

PSCreateDelayedMultiplexPropertyStore を呼び出す前に、CoInitialize または OleInitialize を使用して COM を初期化する必要があります。 COM は、このオブジェクトの有効期間にわたって初期化されたままになります。

PSCreateDelayedMultiplexPropertyStore は 、PSCreateMultiplexPropertyStore の代わりに設計されています。この場合、多重化プロパティ ストアを作成する前に、プロパティ ストアの配列を初期化する必要があります。

遅延バインディング メカニズムは、多重化プロパティ ストアでの IPropertyStore::GetValue の呼び出しのパフォーマンス向上として設計されています。 プロパティの値を求められた場合、遅延多重プロパティ ストアは各プロパティ ストアで値をチェックします。 値が見つかったら、後続のストアを作成して初期化する必要はありません。 遅延多重プロパティ ストアは、いずれかのプロパティ ストアが成功コードとVT_EMPTY以外の値を返すと、値の検索を停止します。

遅延多重プロパティ ストアが特定のプロパティ ストアにアクセスする必要がある場合、最初にそのプロパティ ストアへのインターフェイスが既に取得されているかどうかを確認します。 そうでない場合は、適切なプロパティ ストア ID を使用 して IDelayedPropertyStoreFactory::GetDelayedPropertyStore を呼び出してプロパティ ストアを取得します。 プロパティ ストア ID は、アプリケーションによって提供される順序で常に使用されます。 すべての ID が使用されない可能性があります。

IDelayedPropertyStoreFactory の呼び出しが、特定のプロパティ ストア ID のE_NOTIMPLまたはE_ACCESSDENIEDで失敗した場合、またはアプリケーションがGPS_BESTEFFORT指定した場合、エラーは無視され、遅延多重プロパティ ストアは次のプロパティ ストアに移動します。

場合によっては、 PSCreateMultiplexPropertyStore の代わりに PSCreateDelayedMultiplexPropertyStoreを使用すると便利な場合があります。 たとえば、アプリケーションで 2 つのプロパティ ストアを多重化する必要があり、最初のプロパティ ストアが初期化にメモリを消費せず、PKEY_Size情報を提供する場合です。 多くの場合、呼び出し元のアプリケーションは多重プロパティ ストアを要求し、オブジェクトを解放する前にPKEY_Sizeのみを要求します。 このような場合、アプリケーションは PSCreateDelayedMultiplexPropertyStore を呼び出して IDelayedPropertyStoreFactory を実装することで、2 番目のプロパティ ストアを初期化するコストを回避できます。

例

大規模なプログラムの一部として含める次の例は、IPropertyStoreFactory::GetPropertyStore の実装で PSCreateDelayedMultiplexPropertyStore を使用する方法を示しています。

// CMyFactory is a reference-counted COM object that implements both IPropertyStoreFactory and IDelayedPropertyStoreFactory.

// CMyFactory is assumed to be fully implemented, but for the sake of brevity, 
// many functions are not shown here. 

// Private functions are indicated with an underscore prefix.

// The hope is that the fastest property store satisfies the caller's queries 
// so that the slower property stores are never created.
 
// CMyFactory implementation for IPropertyStoreFactory::GetPropertyStore
HRESULT CMyFactory::GetPropertyStore( __in GETPROPERTYSTOREFLAGS flags,
                                      __in_opt IUnknown *pUnkFactory,
                                      __in REFIID riid,
                                      __deref_out void **ppv)
{
    *ppv = NULL;
    HRESULT hr;
 
    // This application creates only read-only stores.
    if (flags & GPS_READWRITE)
    {
        hr = STG_E_ACCESSDENIED;
    }
    else
    {
        // More advanced applications would check other GETPROPERTYSTOREFLAGS 
        // flags and respond appropriately.
 
        // This application always creates its stores in-process, so it 
        // ignores the pUnkFactory value.
        
        DWORD rgStoreIds[] = {0, 1, 2};
        
        hr = PSCreateDelayedMultiplexPropertyStore(flags, this, rgStoreIds, ARRAYSIZE(rgStoreIds), riid, ppv);
    }
 
    return hr;
}
 
// CMyFactory implementation of IDelayedPropertyStoreFactory::GetDelayedPropertyStore
HRESULT CMyFactory::GetDelayedPropertyStore(GETPROPERTYSTOREFLAGS flags,
                                            DWORD dwStoreId,
                                            REFIID riid,
                                            void **ppv)
{
    *ppv = NULL;
    HRESULT hr;
    
    // Note: The IDs here match the IDs in rgStoreIds above.

    if (dwStoreId == 0)
    {
        // This store is the fastest at returning properties.

        hr = _CreateFastestPropertyStore(flags, riid, ppv);
    }
    else if (dwStoreId == 1)
    {
        // This store is slower at returning properties.
        hr = _CreateSlowerPropertyStore(flags, riid, ppv);
    }
    else if (dwStoreId == 2)
    {
        // This store is very slow at returning properties.
        hr = _CreateSlowestPropertyStore(flags, riid, ppv);
    }
    else
    {
        // This should never happen.
        hr = E_UNEXPECTED;
    }
    
    return hr;
}

要件

こちらもご覧ください

IPropertyStoreFactory

PSCreateMultiplexPropertyStore