Структура SHFILEOPSTRUCTW (shellapi.h)
Содержит сведения о том, что функция SHFileOperation
Синтаксис
typedef struct _SHFILEOPSTRUCTW {
HWND hwnd;
UINT wFunc;
PCZZWSTR pFrom;
PCZZWSTR pTo;
FILEOP_FLAGS fFlags;
BOOL fAnyOperationsAborted;
LPVOID hNameMappings;
PCWSTR lpszProgressTitle;
} SHFILEOPSTRUCTW, *LPSHFILEOPSTRUCTW;
Члены
hwnd
Тип: HWND
Дескриптор окна в диалоговом окне для отображения сведений о состоянии операции файла.
wFunc
Тип: UINT
Значение, указывающее, какая операция выполняется. Одно из следующих значений:
FO_COPY
Скопируйте файлы, указанные в элементе pFrom
FO_DELETE
Удалите файлы, указанные в pFrom.
FO_MOVE
Переместите файлы, указанные в pFrom, в расположение, указанное в pTo.
FO_RENAME
Переименуйте файл, указанный в pFrom. Этот флаг нельзя использовать для переименования нескольких файлов с одним вызовом функции. Вместо этого используйте FO_MOVE.
pFrom
Тип: PCZZTSTR
Стандартные MS-DOS подстановочные знаки, такие как "*", разрешены только в позиции имени файла. Использование подстановочного знака в другом месте строки приведет к непредсказуемым результатам.
Хотя этот элемент объявлен как одна строка, завершающаяся значением NULL, фактически это буфер, который может содержать несколько имен файлов с разделителями NULL. Каждое имя файла завершается одним символом NULL. Последнее имя файла завершается двойным символом NULL ("\0\0") для указания конца буфера.
pTo
Тип: PCZZTSTR
Как и pFrom, элемент pTo также является строкой с двойным значением NULL и обрабатывается точно так же. Однако pTo должны соответствовать следующим спецификациям:
- Подстановочные знаки не поддерживаются.
- Операции копирования и перемещения могут указывать конечные каталоги, которые не существуют. В этих случаях система пытается создать их и обычно отображает диалоговое окно, чтобы попросить пользователя создать новый каталог. Чтобы отключить это диалоговое окно и создать каталоги автоматически, задайте флаг FOF_NOCONFIRMMKDIR в fFlags.
- Для операций копирования и перемещения буфер может содержать несколько имен целевых файлов, если элемент fFlags указывает FOF_MULTIDESTFILES.
- Упаковайте несколько имен в строку
pTo так же, как и для pFrom . - Используйте полные пути. Использование относительных путей не запрещено, но может иметь непредсказуемые результаты.
fFlags
Тип: FILEOP_FLAGS
Флаги, управляющие операцией файла. Этот элемент может использовать сочетание следующих флагов.
FOF_ALLOWUNDO
При возможности сохраните сведения об отмене.
До Windows Vista операции можно отменить только из того же процесса, который выполнял исходную операцию.
В Системах Windows Vista и более поздних версий область действия отмены — это сеанс пользователя. Любой процесс, выполняемый в сеансе пользователя, может отменить другую операцию. Состояние отмены хранится в процессе Explorer.exe и до тех пор, пока этот процесс выполняется, он может координировать функции отмены.
Если параметр исходного файла не содержит полный путь и имена файлов, этот флаг игнорируется.
FOF_CONFIRMMOUSE
Не используется.
FOF_FILESONLY
Выполните операцию только в файлах (а не в папках), если указано имя файла подстановочного знака (.) .
FOF_MULTIDESTFILES
Элемент pTo указывает несколько целевых файлов (один для каждого исходного файла в pFrom), а не один каталог, в котором должны быть отложены все исходные файлы.
FOF_NOCONFIRMATION
Ответьте "Да" на все для любого диалогового окна, отображаемого.
FOF_NOCONFIRMMKDIR
Не попросите пользователя подтвердить создание нового каталога, если операция требует создания.
FOF_NO_CONNECTED_ELEMENTS
Версия 5.0. Не перемещайте подключенные файлы как группу. Перемещайте только указанные файлы.
FOF_NOCOPYSECURITYATTRIBS
Версия 4.71. Не копируйте атрибуты безопасности файла. Целевой файл получает атрибуты безопасности новой папки.
FOF_NOERRORUI
Не отображайте диалоговое окно пользователю, если возникает ошибка.
FOF_NORECURSEREPARSE
Не используется.
FOF_NORECURSION
Выполните операцию только в локальном каталоге. Не действовать рекурсивно в подкаталогах, что является поведением по умолчанию.
FOF_NO_UI
Windows Vista. Выполняйте операцию автоматически, не показыв пользовательский интерфейс пользователю. Это эквивалентно FOF_SILENT | FOF_NOCONFIRMATION | FOF_NOERRORUI | FOF_NOCONFIRMMKDIR.
FOF_RENAMEONCOLLISION
Присвойте файлу новое имя в операции перемещения, копирования или переименования, если файл с целевым именем уже существует в месте назначения.
FOF_SILENT
Не отображайте диалоговое окно хода выполнения.
FOF_SIMPLEPROGRESS
Отображает диалоговое окно хода выполнения, но не отображает отдельные имена файлов, так как они работают.
FOF_WANTMAPPINGHANDLE
Если FOF_RENAMEONCOLLISION указан и все файлы были переименованы, назначьте объект сопоставления имен, содержащий старые и новые имена элементу hNameMappings. Этот объект должен быть освобожден с помощью SHFreeNameMappings, если он больше не нужен.
FOF_WANTNUKEWARNING
Версия 5.0. Отправьте предупреждение, если файл окончательно уничтожается во время операции удаления, а не перезапускается. Этот флаг частично переопределяет FOF_NOCONFIRMATION.
fAnyOperationsAborted
Тип: BOOL
Когда функция возвращается, этот элемент содержит TRUE, если все операции с файлами прерваны, прежде чем они были завершены; в противном случае FALSE. Операция может быть прервана пользователем с помощью пользовательского интерфейса или она может быть прервана системой, если были заданы флаги FOF_NOERRORUI или FOF_NOCONFIRMATION.
hNameMappings
Тип: LPVOID
Когда функция возвращается, этот элемент содержит дескриптор объекта сопоставления имен, который содержит старые и новые имена переименованных файлов. Этот элемент используется только в том случае, если элемент fFlags включает флаг FOF_WANTMAPPINGHANDLE. Дополнительные сведения см. в примечаниях.
lpszProgressTitle
Тип: PCTSTR
Указатель на заголовок диалогового окна хода выполнения. Это строка, завершающаяся значением NULL. Этот элемент используется только в том случае, если fFlags включает флаг FOF_SIMPLEPROGRESS.
Замечания
// WRONG
LPTSTR pszSource = L"C:\\Windows\\*";
// RIGHT
LPTSTR pszSource = L"C:\\Windows\\*\0";
Чтобы учесть два конечных символа NULL, обязательно создайте буферы, достаточно большие для хранения MAX_PATH (который обычно включает один завершающийся символ NULL) плюс 1.
Невозможно переоценить, что пути всегда должны быть полными. Если
Если вы не предоставляете полный путь, следующие факты становятся актуальными:
- Отсутствие пути перед именем файла не указывает на SHFileOperation, что этот файл находится в корне текущего каталога.
- Переменная среды PATH не используется SHFileOperation для определения допустимого пути.
- SHFileOperation нельзя использовать каталог, который является текущим каталогом при начале выполнения. Каталог, который рассматривается как текущий каталог, является процессным, и его можно изменить с другого потока во время выполнения операции. Если бы это произошло, результаты SHFileOperation будут непредсказуемыми.
Если pFrom задано имя файла без полного пути, удаление файла с FO_DELETE не перемещает его в корзину, даже если установлен флаг FOF_ALLOWUNDO. Чтобы удалить файл в корзину, необходимо предоставить полный путь.
SHFileOperation не удается выполнить префикс пути с помощью "\?".
Существует две версии этой структуры, версия ANSI (SHFILEOPSTRUCTA) и версия Юникода (SHFILEOPSTRUCTW). Версия Юникода идентична версии ANSI, за исключением того, что широкие символьные строки (LPCWSTR) используются вместо строк символов ANSI (LPCSTR). В Windows 98 и более ранних версиях поддерживается только версия ANSI. В Microsoft Windows NT 4.0 и более поздней версии поддерживаются версии ANSI и Юникод этой структуры. SHFILEOPSTRUCTW и SHFILEOPTSTRUCTA никогда не следует использовать напрямую; Соответствующая структура определена как SHFILEOPSTRUCT предварительной компиляцией в зависимости от того, компилируется ли приложение для ANSI или Юникода.
SHNAMEMAPPING имеет аналогичные версии ANSI и Юникода. Для приложений ANSI hNameMappings указывает на int за массивом структур ANSI SHNAMEMAPPING. Для приложений Юникода hNameMappings указывает на int за массивом структур Юникода SHNAMEMAPPING. Однако в Microsoft Windows NT 4.0 и более поздних версий
x = SHFileOperation(&shop);
if (fWin9x)
HandleAnsiNameMappings(shop.hNameMappings);
else
HandleUnicodeNameMappings(shop.hNameMappings);
Рассматривать hNameMappings как указатель на структуру, члены которой являются значением UINT, за которым следует указатель на массив структур SHNAMEMAPPING, как показано в объявлении:
struct HANDLETOMAPPINGS
{
UINT uNumberOfMappings; // Number of mappings in the array.
LPSHNAMEMAPPING lpSHNameMapping; // Pointer to the array of mappings.
};
Значение UINT указывает количество структур SHNAMEMAPPING в массиве. Каждая структура SHNAMEMAPPING содержит старый и новый путь для одного из переименованных файлов.
Заметка
Заголовок shellapi.h определяет SHFILEOPSTRUCT как псевдоним, который автоматически выбирает версию ANSI или Юникод этой функции на основе определения константы препроцессора ЮНИКОДа. Сочетание использования псевдонима, нейтрального для кодирования, с кодом, не зависящим от кодирования, может привести к несоответствиям, которые приводят к ошибкам компиляции или среды выполнения. Дополнительные сведения см. в соглашениях о прототипах функций.
Требования
| Требование | Ценность |
|---|---|
| минимальные поддерживаемые клиентские | Windows XP [только классические приложения] |
| минимальный поддерживаемый сервер | Windows 2000 Server [только классические приложения] |
| заголовка | shellapi.h |