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 |
|
|
DLL |
|
See also