Export (0) Print
Expand All
Expand Minimize
This topic has not yet been rated - Rate this topic

SHCreateDataObject function

Creates a data object in a parent folder.

Syntax


HRESULT SHCreateDataObject(
  _In_opt_  PCIDLIST_ABSOLUTE pidlFolder,
  _In_      UINT cidl,
  _In_opt_  PCUITEMID_CHILD_ARRAY apidl,
  _In_opt_  IDataObject *pdtInner,
  _In_      REFIID riid,
  _Out_     void **ppv
);

Parameters

pidlFolder [in, optional]

Type: PCIDLIST_ABSOLUTE

A pointer to an ITEMIDLIST (PIDL) of the parent folder that contains the data object.

cidl [in]

Type: UINT

The number of file objects or subfolders specified in the apidl parameter.

apidl [in, optional]

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.

pdtInner [in, optional]

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.

riid [in]

Type: REFIID

A reference to the IID of the interface to retrieve through ppv. This must be IID_IDataObject.

ppv [out]

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

Minimum supported client

Windows Vista [desktop apps only]

Minimum supported server

Windows Server 2008 [desktop apps only]

Header

Shlobj.h

DLL

Shell32.dll

See also

CIDLData_CreateFromIDArray

 

 

Did you find this helpful?
(1500 characters remaining)
Thank you for your feedback

Community Additions

ADD
Show:
© 2014 Microsoft. All rights reserved.