SHCreateDataObject function (shlobj_core.h)
Creates a data object in a parent folder.
Syntax
SHSTDAPI SHCreateDataObject(
[in, optional] PCIDLIST_ABSOLUTE pidlFolder,
[in] UINT cidl,
[in, optional] PCUITEMID_CHILD_ARRAY apidl,
[in, optional] IDataObject *pdtInner,
[in] REFIID riid,
[out] void **ppv
);
Parameters
[in, optional] pidlFolder
Type: PCIDLIST_ABSOLUTE
A pointer to an ITEMIDLIST (PIDL) of the parent folder that contains the data object.
[in] cidl
Type: UINT
The number of file objects or subfolders specified in the apidl parameter.
[in, optional] apidl
Type: PCUITEMID_CHILD_ARRAY
An array of pointers to constant ITEMIDLIST structures, each of which uniquely identifies a file object or subfolder relative to the parent folder. Each item identifier list must contain exactly one SHITEMID structure followed by a terminating zero.
[in, optional] pdtInner
Type: IDataObject*
A pointer to interface IDataObject. This parameter can be NULL. Specify pdtInner only if the data object created needs to support additional FORMATETC clipboard formats beyond the default formats it is assigned at creation. Alternatively, provide support for populating the created data object using non-default clipboard formats by calling method IDataObject::SetData and specifying the format in the FORMATETC structure passed in parameter pFormatetc.
[in] riid
Type: REFIID
A reference to the IID of the interface to retrieve through ppv. This must be IID_IDataObject.
[out] ppv
Type: void**
When this method returns successfully, contains the IDataObject interface pointer requested in riid.
Return value
Type: HRESULT
If this function succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code.
Remarks
This function is typically called when implementing method IShellFolder::GetUIObjectOf. When an interface pointer of interface ID IID_IDataObject is requested (using parameter riid), the implementer can return the interface pointer on the object created with SHCreateDataObject in response.
This function supports the CFSTR_SHELLIDLIST (also known as HIDA) clipboard format and also has generic support for arbitrary clipboard formats through IDataObject::SetData. For more information on clipboard formats, see Shell Clipboard Formats.
The new data object is intended to be used in operations such as drag-and-drop, in which the data is stored in the clipboard with a given format.
We recommend that you use the IID_PPV_ARGS macro, defined in Objbase.h, to package the riid and ppv parameters. This macro provides the correct IID based on the interface pointed to by the value in ppv, which eliminates the possibility of a coding error in riid that could lead to unexpected results.
Requirements
| Requirement | Value |
|---|---|
| Minimum supported client | Windows Vista [desktop apps only] |
| Minimum supported server | Windows Server 2008 [desktop apps only] |
| Target Platform | Windows |
| Header | shlobj_core.h (include Shlobj.h) |
| DLL | Shell32.dll |
| API set | ext-ms-win-shell-shell32-l1-2-2 (introduced in Windows 10, version 10.0.14393) |