Функция SHFileOperationA (shellapi.h)
Копирует, перемещает, переименовывает или удаляет объект файловой системы. Эта функция была заменена в Windows Vista IFileOperation.
Синтаксис
int SHFileOperationA(
[in, out] LPSHFILEOPSTRUCTA lpFileOp
);
Параметры
[in, out] lpFileOp
Тип: LPSHFILEOPSTRUCT
Указатель на структуру SHFILEOPSTRUCT , содержащую сведения, необходимые этой функции для выполнения указанной операции. Этот параметр должен содержать допустимое значение, не равное NULL. Вы несете ответственность за проверку значения. Если вы не проверите его, вы увидите непредвиденные результаты.
Возвращаемое значение
Тип: int
Возвращает ноль в случае успешного выполнения; в противном случае ненулевое значение. Приложения обычно должны просто проверка для нулевого или ненулевого значения.
Рекомендуется изучить значение члена fAnyOperationsAbortedSHFILEOPSTRUCT. SHFileOperation может вернуть 0 для успешного выполнения, если пользователь отменит операцию. Если вы не проверка fAnyOperationsAborted, а также возвращаемое значение, вы не можете знать, что функция выполнила всю задачу, которую вы запросили для нее, и можете продолжить работу с неправильными предположениями.
Не используйте GetLastError с возвращаемыми значениями этой функции.
Чтобы изучить ненулевое значение для устранения неполадок, они в значительной степени сопоставляются с значениями, определенными в Winerror.h. Однако некоторые из возможных возвращаемых значений основаны на кодах ошибок до Win32, которые в некоторых случаях перекрывают более поздние значения Winerror.h без сопоставления их значения. Эти конкретные значения подробно описаны здесь, и для этих конкретных значений только эти значения должны приниматься по кодам Winerror.h. Однако эти значения предоставляются со следующими предупреждениями:
- Это коды ошибок, предшествующих Win32, и они больше не поддерживаются и не определяются ни в одном общедоступном файле заголовка. Чтобы использовать их, необходимо определить их самостоятельно или сравнить с числовым значением.
- Эти коды ошибок могут быть изменены и исторически делали это.
- Эти значения предоставляются только в качестве вспомогательного средства при отладке. Они не должны рассматриваться как окончательные.
| Код ошибки | Значение | Значение |
|---|---|---|
| DE_SAMEFILE | 0x71 | Исходный и целевой файлы являются одинаковыми. |
| DE_MANYSRC1DEST | 0x72 | В исходном буфере было указано несколько путей к файлам, но только один путь к целевому файлу. |
| DE_DIFFDIR | 0x73 | Операция переименования была указана, но конечный путь — это другой каталог. Вместо этого используйте операцию перемещения. |
| DE_ROOTDIR | 0x74 | Источником является корневой каталог, который нельзя переместить или переименовать. |
| DE_OPCANCELLED | 0x75 | Операция была отменена пользователем или автоматически отменена, если соответствующие флаги были предоставлены SHFileOperation. |
| DE_DESTSUBTREE | 0x76 | Назначение является поддеревом источника. |
| DE_ACCESSDENIEDSRC | 0x78 | Параметры безопасности запрещают доступ к источнику. |
| DE_PATHTOODEEP | 0x79 | Исходный или целевой путь превысил или превысит MAX_PATH. |
| DE_MANYDEST | 0x7A | Операция включала несколько конечных путей, что может завершиться ошибкой в случае операции перемещения. |
| DE_INVALIDFILES | 0x7C | Недопустимый путь в источнике или назначении. |
| DE_DESTSAMETREE | 0x7D | Источник и назначение имеют одну и ту же родительскую папку. |
| DE_FLDDESTISFILE | 0x7E | Конечный путь — это существующий файл. |
| DE_FILEDESTISFLD | 0x80 | Конечный путь — это существующая папка. |
| DE_FILENAMETOOLONG | 0x81 | Имя файла превышает MAX_PATH. |
| DE_DEST_IS_CDROM | 0x82 | Назначение — компакт-диск, доступный только для чтения, возможно, неформатирован. |
| DE_DEST_IS_DVD | 0x83 | Назначение — DVD-диск, доступный только для чтения, возможно, неформатирован. |
| DE_DEST_IS_CDRECORD | 0x84 | Место назначения — записываемый компакт-диск, возможно, неформатированные. |
| DE_FILE_TOO_LARGE | 0x85 | Файл, участвующий в операции, слишком велик для целевого носителя или файловой системы. |
| DE_SRC_IS_CDROM | 0x86 | Источником является компакт-диск, доступный только для чтения, возможно, неформатирован. |
| DE_SRC_IS_DVD | 0x87 | Источником является DVD-диск, доступный только для чтения, возможно, неформатирован. |
| DE_SRC_IS_CDRECORD | 0x88 | Источником является записываемый компакт-диск, возможно, неформатируемый. |
| DE_ERROR_MAX | 0xB7 | MAX_PATH превышено во время операции. |
| 0x402 | Произошла неизвестная ошибка. Обычно это происходит из-за недопустимого пути в источнике или назначении. Эта ошибка не возникает в Windows Vista и более поздних версиях. | |
| ERRORONDEST | 0x10000 | В месте назначения произошла неуказаная ошибка. |
| DE_ROOTDIR | ERRORONDEST | 0x10074 | Назначение является корневым каталогом и не может быть переименовано. |
Комментарии
С этой функцией следует использовать полные имена путей. Использование с относительными именами путей не является потокобезопасным.
За двумя исключениями нельзя использовать SHFileOperation для перемещения специальных папок с локального диска на удаленный компьютер, указав сетевой путь. Исключениями являются папки "Мои документы" (CSIDL_PERSONAL, CSIDL_DOCUMENTS) и "Мои рисунки" (CSIDL_MYPICTURES).
При использовании для удаления файла SHFileOperation окончательно удаляет файл, если не установлен флаг FOF_ALLOWUNDO в элементе fFlags структуры SHFILEOPSTRUCT, на которую указывает lpFileOp. При установке этого флага файл отправляется в корзину. Если вы хотите просто удалить файл и гарантировать, что он не будет помещен в корзину, используйте deleteFile.
Если обработчик обратного вызова копирования предоставляется и регистрируется, SHFileOperation вызывает его, если вы не задали флаг , например FOF_NOCONFIRMATION в элементе fFlags структуры, на которую указывает lpFileOp. Дополнительные сведения о реализации обработчиков обратного вызова копирования см. в разделе ICopyHook::CopyCallback .
Удаление файла является рекурсивным, если в lpFileOp не установлен флаг FOF_NORECURSION.
Подключение файлов
В Windows 2000 или более поздней версии можно подключить HTML-файл к папке, содержащей связанные файлы, такие как gif-изображения или таблицы стилей. Если подключение к файлу включено, при перемещении или копировании HTML-файла подключенная папка и все ее файлы также перемещаются или копируются. И наоборот, при перемещении папки со связанными файлами HTML-файл также перемещается.HTML-файл должен иметь расширение .htm или .html. Подключение к связанным файлам создается путем помещения папки, содержащей их, в ту же папку, что и HTML-файл. Имя папки, содержащей подключенные файлы, должно совпадать с именем HTML-файла, за которым следует "_files" или ".files" (это с учетом регистра; например, ". Файлы" не работает). Пример приведен здесь.
- Создайте файл с именем Test.htm в каталоге C:\Files (C:\Files\Test.htm).
- Создайте папку с именем Test.files в каталоге C:\Files (C:\Files\Test.files).
- Заполните папку несколькими файлами. Любой файл, помещенный в эту папку, подключен к Test.htm.
- Переместите или скопируйте файл Test.htm в каталог C:\Files2.
- Обратите внимание, что каталог Test.files теперь также находится в каталоге C:\Files2.
Подключение к файлу включено по умолчанию. Его можно отключить, добавив запись REG_DWORD NoFileFolderConnection, как показано ниже:
HKEY_CURRENT_USER Software Microsoft Windows CurrentVersion Explorer NoFileFolderConnection
Если для параметра NoFileFolderConnection задано значение 1, подключение к файлу отключается. Если значение равно нулю или отсутствует, подключение к файлу включено.
Чтобы переместить только указанные файлы и ни один из подключенных файлов, установите флаг FOF_NO_CONNECTED_ELEMENTS в элементе fFlags структуры, на которую указывает lpFileOp.
Обратите внимание, что использование папки с таким именем, как "MyFile_files", для определения подключения может быть недопустимым для локализованных версий Windows. Термин "файлы" может потребоваться заменить эквивалентным словом на местном языке.
Примечание
Заголовок shellapi.h определяет SHFileOperation в качестве псевдонима, который автоматически выбирает версию ANSI или Юникод этой функции на основе определения константы препроцессора ЮНИКОД. Использование псевдонима, не зависящий от кодирования, с кодом, который не является нейтральным для кодировки, может привести к несоответствиям, которые приводят к ошибкам компиляции или времени выполнения. Дополнительные сведения см. в разделе Соглашения для прототипов функций.
Требования
| Требование | Значение |
|---|---|
| Минимальная версия клиента | Windows XP [только классические приложения] |
| Минимальная версия сервера | Windows 2000 Server [только классические приложения] |
| Целевая платформа | Windows |
| Header | shellapi.h |
| Библиотека | Shell32.lib |
| DLL | Shell32.dll (версия 4.0 или более поздняя) |
| Набор API | ext-ms-win-shell-shell32-l1-2-1 (представлено в Windows 10 версии 10.0.10240) |
Обратная связь
Ожидается в ближайшее время: в течение 2024 года мы постепенно откажемся от GitHub Issues как механизма обратной связи для контента и заменим его новой системой обратной связи. Дополнительные сведения см. в разделе https://aka.ms/ContentUserFeedback.
Отправить и просмотреть отзыв по