PSGetPropertyFromPropertyStorage function (propsys.h)

Article
02/22/2024

Gets the value of a property as stored in serialized property storage.

Syntax

PSSTDAPI PSGetPropertyFromPropertyStorage(
  [in]  PCUSERIALIZEDPROPSTORAGE psps,
  [in]  DWORD                    cb,
  [in]  REFPROPERTYKEY           rpkey,
  [out] PROPVARIANT              *ppropvar
);

Parameters

[in] psps

Type: PCUSERIALIZEDPROPSTORAGE

Pointer to an allocated buffer that contains the serialized properties. This buffer is obtained by a call to IPersistSerializedPropStorage::GetPropertyStorage.

[in] cb

Type: DWORD

The size, in bytes, of the USERIALIZESPROPSTORAGE buffer pointed to by psps.

[in] rpkey

Type: REFPROPERTYKEY

Reference to the PROPERTYKEY that identifies the property for which to get the value.

[out] ppropvar

Type: PROPVARIANT**

When this function returns, contains the requested value.

Return value

Type: PSSTDAPI

Returns S_OK if successful, or an error value otherwise.

Remarks

This function is intended to be called if the calling application already has a serialized property storage and needs no more than a few properties from storage. If many properties need to be retrieved, performance can be enhanced by creating a memory property store through PSCreateMemoryPropertyStore, initializing the property store by calling IPersistSerializedPropStorage::SetPropertyStorage, and by using IPropertyStore to retrieve the properties.

Note that PSGetPropertyFromPropertyStorage works only on serialized buffers created by the system implementation of IPersistSerializedPropStorage. You must first obtain a memory property store by calling PSCreateMemoryPropertyStore. That store can then create a serialized buffer using the IPersistSerializedPropStorage interface.

Although SERIALIZEDPROPSTORAGE is an opaque serialized data structure whose format may change in the future, earlier formats will be supported on subsequent versions of Windows. Because the format is opaque, applications should use supported property storage APIs to access and manipulate the serialized buffer (see IPersistSerializedPropStorage).

Examples

The following example, to be included as part of a larger program, demonstrates how to use PSGetPropertyFromPropertyStorage to read a value from serialized property storage.

// SERIALIZEDPROPSTORAGE *pStorage;
// DWORD cbStorage;
// Assume the variables pStorage and cbStorage are initialized and valid.  
PROPVARIANT propvar;

HRESULT hr = PSGetPropertyFromPropertyStorage(pStorage, cb, PKEY_Rating, &propvar);

if (SUCCEEDED(hr))
{
    // propvar is now valid.
 
    PropVariantClear(&propvar);
}

Requirements

Requirement	Value
Minimum supported client	Windows XP with SP2, Windows Vista [desktop apps only]
Minimum supported server	Windows Server 2003 with SP1 [desktop apps only]
Target Platform	Windows
Header	propsys.h
Library	Propsys.lib
DLL	Propsys.dll (version 6.0 or later)
Redistributable	Windows Desktop Search (WDS) 3.0

Share via