PSGetItemPropertyHandler function (propsys.h)

Retrieves a property handler for a Shell item.

Syntax

PSSTDAPI PSGetItemPropertyHandler(
  [in]  IUnknown *punkItem,
  [in]  BOOL     fReadWrite,
  [in]  REFIID   riid,
  [out] void     **ppv
);

Parameters

[in] punkItem

Type: IUnknown*

A pointer to the IUnknown interface of a Shell item that supports IShellItem.

Windows XP: Use SHCreateShellItem to create the Shell item.

Windows Vista: Use SHCreateItemFromIDList, SHCreateItemFromParsingName, SHCreateItemFromRelativeName, SHCreateItemInKnownFolder, or SHCreateItemWithParent to create the Shell item.

[in] fReadWrite

Type: BOOL

TRUE to retrieve a read/write property handler. FALSE to retrieve a read-only property handler.

[in] riid

Type: REFIID

Reference to the IID of the interface the handler object should return. This should be IPropertyStore or an interface derived from IPropertyStore.

[out] ppv

Type: void**

When this function returns, contains the interface pointer requested in riid.

Return value

Type: PSSTDAPI

Returns S_OK if successful, or an error value otherwise.

Remarks

This function is supported in Windows XP and Windows Vista. For applications supported only on Windows Vista or later, it is recommended that you use IShellItem2::GetPropertyStore instead of PSGetItemPropertyHandler. That method provides a richer set of properties in the property store that is returned.

This function is approximately equivalent to passing the GPS_HANDLERPROPERTIESONLY flag to IShellItem2::GetPropertyStore.

You must initialize Component Object Model (COM) with CoInitialize or OleInitialize before you call PSGetItemPropertyHandler. COM must remain initialized for the lifetime of this object.

Examples

The following example, to be included as part of a larger program, demonstrates how to use PSGetItemPropertyHandler to obtain a property handler for an item.

// IShellItem *psi;
// Assume variable psi is valid and initialized.
IPropertyStore *pStore;

HRESULT hr = PSGetItemPropertyHandler(psi, FALSE, IID_PPV_ARGS(&pStore));

if (SUCCEEDED(hr))
{
    // pStore is now valid and contains properties exposed through the 
    // property handler for the item.
 
    pStore->Release();
}

Requirements