Структура SHFILEOPSTRUCTA (shellapi.h)
Содержит сведения, которые функция SHFileOperation использует для выполнения операций с файлами.
Синтаксис
typedef struct _SHFILEOPSTRUCTA {
HWND hwnd;
UINT wFunc;
PCZZSTR pFrom;
PCZZSTR pTo;
FILEOP_FLAGS fFlags;
BOOL fAnyOperationsAborted;
LPVOID hNameMappings;
PCSTR lpszProgressTitle;
} SHFILEOPSTRUCTA, *LPSHFILEOPSTRUCTA;
Члены
hwnd
Тип: HWND
Дескриптор окна для диалогового окна для отображения сведений о состоянии операции с файлом.
wFunc
Тип: UINT
Значение типа , указывающее, какую операцию следует выполнить. Принимает одно из следующих значений:
FO_COPY
Скопируйте файлы, указанные в элементе pFrom , в расположение, указанное в элементе pTo .
FO_DELETE
Удалите файлы, указанные в pFrom.
FO_MOVE
Переместите файлы, указанные в pFrom , в расположение, указанное в pTo.
FO_RENAME
Переименуйте файл, указанный в pFrom. Этот флаг нельзя использовать для переименования нескольких файлов с помощью одного вызова функции. Вместо этого используйте FO_MOVE .
pFrom
Тип: PCZZTSTR
Стандартные подстановочные знаки MS-DOS, такие как "*", разрешены только в позиции имени файла. Использование подстановочного знака в другом месте строки приведет к непредсказуемым результатам.
Хотя этот элемент объявляется как одна строка, заканчивающаяся нулевым значением, на самом деле это буфер, который может содержать несколько имен файлов с разделителями 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.
Невозможно переоценить, что пути всегда должны быть полными. Если члены pFrom или pTo имеют неквалифицированные имена, текущие каталоги извлекаются из глобальных параметров текущего диска и каталога, управляемых функциями GetCurrentDirectory и SetCurrentDirectory .
Если вы не предоставите полный путь, следующие факты становятся актуальными:
- Отсутствие пути перед именем файла не указывает shFileOperation на то, что этот файл находится в корне текущего каталога.
- Переменная среды PATH не используется SHFileOperation для определения допустимого пути.
- ShFileOperation не может использоваться для использования каталога, который является текущим каталогом при начале выполнения. Каталог, который считается текущим каталогом, является на уровне процесса, и его можно изменить из другого потока во время выполнения операции. Если бы это произошло, результаты SHFileOperation были бы непредсказуемыми.
Если для параметра pFrom задано имя файла без полного пути, удаление файла с FO_DELETE не перемещает его в корзину, даже если установлен флаг FOF_ALLOWUNDO . Чтобы удалить файл в корзину, необходимо указать полный путь.
SHFileOperation завершается сбоем по любому пути с префиксом "\?".
Существует две версии этой структуры: версия ANSI (SHFILEOPSTRUCTA) и версия Юникода (SHFILEOPSTRUCTW). Версия Юникода идентична версии ANSI, за исключением того, что вместо строк символов ANSI (LPCSTR) используются строки расширенных символов (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 и более поздних версий SHFileOperationвсегда возвращает дескриптор в Юникоде из структур SHNAMEMAPPING . Если вы хотите, чтобы приложения работали со всеми версиями Windows, приложение должно использовать условный код для работы с сопоставлениями имен. Пример:
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 или Юникод этой функции на основе определения константы препроцессора UNICODE. Сочетание использования псевдонима, не зависящий от кодировки, с кодом, не зависящим от кодировки, может привести к несоответствиям, которые приводят к ошибкам компиляции или среды выполнения. Дополнительные сведения см. в разделе Соглашения для прототипов функций.
Требования
| Минимальная версия клиента | Windows XP [только классические приложения] |
| Минимальная версия сервера | Windows 2000 Server [только классические приложения] |
| Верхняя часть | shellapi.h |
Обратная связь
Ожидается в ближайшее время: в течение 2024 года мы постепенно откажемся от GitHub Issues как механизма обратной связи для контента и заменим его новой системой обратной связи. Дополнительные сведения см. в разделе https://aka.ms/ContentUserFeedback.
Отправить и просмотреть отзыв по