DragQueryFile function
Applies to: desktop apps only
Retrieves the names of dropped files that result from a successful drag-and-drop operation.
Syntax
UINT DragQueryFile( __in HDROP hDrop, __in UINT iFile, __out LPTSTR lpszFile, UINT cch );
Parameters
- hDrop [in]
-
Type: HDROP
Identifier of the structure that contains the file names of the dropped files.
- iFile [in]
-
Type: UINT
Index of the file to query. If the value of this parameter is 0xFFFFFFFF, DragQueryFile returns a count of the files dropped. If the value of this parameter is between zero and the total number of files dropped, DragQueryFile copies the file name with the corresponding value to the buffer pointed to by the lpszFile parameter.
- lpszFile [out]
-
Type: LPTSTR
The address of a buffer that receives the file name of a dropped file when the function returns. This file name is a null-terminated string. If this parameter is NULL, DragQueryFile returns the required size, in characters, of this buffer.
- cch
-
Type: UINT
The size, in characters, of the lpszFile buffer.
Return value
Type: UINT
A nonzero value indicates a successful call.
When the function copies a file name to the buffer, the return value is a count of the characters copied, not including the terminating null character.
If the index value is 0xFFFFFFFF, the return value is a count of the dropped files. Note that the index variable itself returns unchanged, and therefore remains 0xFFFFFFFF.
If the index value is between zero and the total number of dropped files, and the lpszFile buffer address is NULL, the return value is the required size, in characters, of the buffer, not including the terminating null character.
Requirements
|
Minimum supported client | Windows XP |
|---|---|
|
Minimum supported server | Windows 2000 Server |
|
Header |
|
|
Library |
|
|
DLL |
|
|
Unicode and ANSI names | DragQueryFileW (Unicode) and DragQueryFileA (ANSI) |
See also
Send comments about this topic to Microsoft
Build date: 3/7/2012
- 3/19/2012
- unixstudio
- 3/19/2012
- unixstudio
The sentence "If the value of this parameter is between zero and the total number of files dropped, DragQueryFile copies the file name [...]" is slightly incorrect.
Of course, zero is a valid index value as well, but COUNT is not.
:-)
- 5/26/2011
- JensG
- 7/30/2011
- Thomas Lee
Actually, this is normal behaviour and well known throughout the whole Windows-API. In fact, it would be strange if it was NOT like this - sizes must be absolute und precise or else one will run into heap corruptions hence the API has to deliver the amount of space it REALLY needs and the developer has to state how much he REALLY is able to deliver. Although it would be better if microsoft explicitly stated this (again) in this article .... for completeness-reasons, you sure got a point there.
Oh and by the way : On Unicode-builds the size of the buffer must be of course (nChars+1)*sizeof(WCHAR)
If you don’t pass a buffer pointer, it will return the total number of characters, without the terminator.
If you do pass the buffer pointer, it will return the number of characters copied (not necessarily the whole string), again without the terminator.
However, the size you are expected to pass in the call must include the terminator.
In plain C++:
UINT size = DragQueryFile(hdrop, i, 0, 0);
if (size == 0) { /* handle error... */ }
TCHAR * buffer = new TCHAR[size + 1];
UINT result_size = DragQueryFile(hdrop, index, buffer, size + 1);
if (result_size == 0) { /* something's wrong... */ }
assert(result_size = size);
/*...*/
It’s all there, just a bit hard to follow.
- 7/29/2010
- Florin Crişan
[DllImport("shell32.dll", CharSet=CharSet.Auto)]
public static extern int DragQueryFile(HandleRef hDrop, int iFile, StringBuilder lpszFile, int cch);
- 4/25/2009
- dmex
