SHCreateShellItemArrayFromDataObject function (shobjidl_core.h)

Creates a Shell item array object from a data object.

Syntax

SHSTDAPI SHCreateShellItemArrayFromDataObject(
  [in]  IDataObject *pdo,
  [in]  REFIID      riid,
  [out] void        **ppv
);

Parameters

[in] pdo

Type: IDataObject*

A pointer to IDataObject interface.

[in] riid

Type: REFIID

A reference to the desired interface ID.

[out] ppv

Type: void**

When this method returns, contains the interface pointer requested in riid. This is typically IShellItemArray.

Return value

Type: HRESULT

If this function succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code.

Remarks

This function is useful for Shell extensions that implement IShellExtInit and are passed a data object to the IShellExtInit::Initialize method; for example, context menu handlers.

This API lets you convert the data object into a Shell item that the handler can consume. It is recommend that handlers use a Shell item array rather than clipboard formats like CF_HDROP and CFSTR_SHELLIDLIST (also known as HIDA) as it leads to simpler code and allows some performance improvements.

The resulting shell item array holds a reference to the source data object. Therefore, that data object must remain valid for the lifetime of the shell item array. Notably, the data objects passed to IDropTarget methods are no longer valid after the drop operation completes.

Requirements