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

See also

CIDLData_CreateFromIDArray