PSGetItemPropertyHandlerWithCreateObject function

Retrieves a property handler for a Shell item.


PSSTDAPI PSGetItemPropertyHandlerWithCreateObject(
  _In_  IUnknown *punkItem,
  _In_  BOOL     fReadWrite,
  _In_  IUnknown *punkCreateObject,
  _In_  REFIID   riid,
  _Out_ void     **ppv


punkItem [in]

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.

fReadWrite [in]

Type: BOOL

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

punkCreateObject [in]

Type: IUnknown*

Pointer to the IUnknown interface of a class factory object that supports ICreateObject.

riid [in]


A reference to the IID of the interface to retrieve through ppv.

ppv [out]

Type: void**

When this function returns successfully, contains the interface pointer requested in riid. This is typically IPropertyStore or IPropertyStoreCapabilities.

Return value


Returns S_OK if successful, or an error value otherwise.


This function is supported in Windows XP as part of the Microsoft Windows Desktop Search (WDS) redistributable which includes IPropertyStore and supporting interfaces. For applications supported only on Windows Vista or later, we recommend that you use IShellItem2::GetPropertyStoreWithCreateObject instead of PSGetItemPropertyHandlerWithCreateObject because IShellItem2::GetPropertyStoreWithCreateObject 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::GetPropertyStoreWithCreateObject.

The punkCreateObject parameter enables the creation of a property store in a different context than that of the caller. For instance, the ICreateObject implementation can cause the property store to be created in another process. This parameter is used only for property handlers that support it and that are registered under HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\PropertySystem\PropertyHandlers

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


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

// IShellItem *psi;
// ICreateObject *pco;
// Assume variables pco and psi are valid and initialized.
IPropertyStore *pStore;

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

if (SUCCEEDED(hr))
    // pStore is now valid and contains properties exposed through the 
    // property handler for the item.


Minimum supported client

Windows XP with SP2, Windows Vista [desktop apps only]

Minimum supported server

Windows Server 2003 with SP1 [desktop apps only]


Windows Desktop Search (WDS) 3.0






Propsys.dll (version 6.0 or later)

See also

Initializing Property Handlers