CIDLData_CreateFromIDArray function
[CIDLData_CreateFromIDArray is available for use in the operating systems specified in the Requirements section. It may be altered or unavailable in subsequent versions.]
Applies to: desktop apps only
Creates a data object with the default vtable pointer.
Syntax
HRESULT CIDLData_CreateFromIDArray( __in PCIDLIST_ABSOLUTE pidlFolder, __in UINT cidl, __in PCUIDLIST_RELATIVE_ARRAY apidl, __out IDataObject **ppdtobj );
Parameters
- pidlFolder [in]
-
Type: PCIDLIST_ABSOLUTE
A fully qualified IDLIST for the root of the items specified in apidl.
- cidl [in]
-
Type: UINT
The number of entries in the apidl array.
- apidl [in]
-
Type: PCUIDLIST_RELATIVE_ARRAY
The array of item IDs relative to pidlFolder. Typically, apidl is an array of child IDs and pidlFolder is a full PIDL for those items. However, pidlFolder can be a null PIDL (desktop IDLISTs). In that case, apidl can contain fully qualified ID lists.
- ppdtobj [out]
-
Type: IDataObject**
The address to a pointer to the object that implements IDataObject.
Return value
Type: HRESULT
If this function succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code.
Remarks
The data object created by this function offers the Shell clipboard format identifier CFSTR_SHELLIDLIST. This data object also supports IDataObject::SetData calls to pick up other clipboard formats.
Requirements
|
Minimum supported client | Windows 2000 Professional |
|---|---|
|
Minimum supported server | Windows 2000 Server |
|
End of client support | Windows Vista |
|
End of server support | Windows Server 2008 |
|
Header |
|
|
Library |
|
|
DLL |
|
See also
Send comments about this topic to Microsoft
Build date: 3/7/2012
The DataObject produced by this method is suitable as a general purpose DataObject implementation in as much as you can add any of your own formats to it using SetData().
BUT there is one exception: CFSTR_FILECONTENTS. It is typical in shell scenarios to store multiple instances of this format in a DataObject (representing a collection of files) by setting the lIndex field of the FORMATETC to values other than the usual -1. However, the DataObject produced by CIDLData_CreateFromIDArray() ignores this field completely and stores all formats with the lIndex -1. This means that you can store *at most one* of any format because subsequent calls to SetData will simply overwrite what is already stored, regardless of lIndex.
One workaround for this is to wrap this DataObject in one of your own and simply forward all calls not related to the CFSTR_FILECONTENTS format to the inner DataObject. Then handle the storage and retrieval of the CFSTR_FILECONTENTS formats in your own code. This save you the hassle of having to implement a general purpose DataObject yourself as the existing one is already adequate in all other respects.
