Edit

SHCreateShellItemArrayFromDataObject function (shobjidl_core.h)

  • Article

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

Requirement Value
Minimum supported client Windows Vista [desktop apps only]
Minimum supported server Windows Server 2008 [desktop apps only]
Target Platform Windows
Header shobjidl_core.h (include Shobjidl.h)
DLL Shell32.dll
API set ext-ms-win-shell-shell32-l1-2-2 (introduced in Windows 10, version 10.0.14393)