PSGetNamedPropertyFromPropertyStorage function (propsys.h)

Gets a value from serialized property storage by property name.

Syntax

PSSTDAPI PSGetNamedPropertyFromPropertyStorage(
  [in]  PCUSERIALIZEDPROPSTORAGE psps,
  [in]  DWORD                    cb,
  [in]  LPCWSTR                  pszName,
  [out] PROPVARIANT              *ppropvar
);

Parameters

[in] psps

Type: PCUSERIALIZEDPROPSTORAGE

A pointer to an allocated buffer that contains the serialized properties. Call IPersistSerializedPropStorage::GetPropertyStorage to obtain the buffer.

[in] cb

Type: DWORD

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

[in] pszName

Type: LPCWSTR

A pointer to a null-terminated, Unicode string that contains the name of the property.

[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 by calling PSCreateMemoryPropertyStore, initializing the property store by calling IPersistSerializedPropStorage::SetPropertyStorage, and using INamedPropertyStore or IPropertyStore to retrieve the properties.

Note that PSGetNamedPropertyFromPropertyStorage 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 and PSGetPropertyFromPropertyStorage).

Examples

The following example, to be included as part of a larger program, demonstrates how to use PSGetNamedPropertyFromPropertyStorage 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 = PSGetNamedPropertyFromPropertyStorage(pStorage, cb, L"MyProperty", &propvar);

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

Requirements

See also

PSGetPropertyFromPropertyStorage