PSGetItemPropertyHandlerWithCreateObject function (propsys.h)

Retrieves a property handler for a Shell item.

Syntax

PSSTDAPI PSGetItemPropertyHandlerWithCreateObject(
  [in]  IUnknown *punkItem,
  [in]  BOOL     fReadWrite,
  [in]  IUnknown *punkCreateObject,
  [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] punkCreateObject

Type: IUnknown*

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

[in] riid

Type: REFIID

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

[out] ppv

Type: void**

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

Return value

Type: PSSTDAPI

Returns S_OK if successful, or an error value otherwise.

Remarks

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.

Examples

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.
 
    pStore->Release();
}

Requirements

See also

IShellItem2::GetPropertyStoreWithCreateObject

Initializing Property Handlers