Функция SHFileOperationW (shellapi.h)
Копирует, перемещает, переименовывает или удаляет объект файловой системы. Эта функция была заменена в Windows Vista IFileOperation.
Синтаксис
int SHFileOperationW(
[in, out] LPSHFILEOPSTRUCTW lpFileOp
);
Параметры
[in, out] lpFileOp
Тип: LPSHFILEOPSTRUCT
Указатель на структуру SHFILEOPSTRUCT, содержащую сведения, необходимые для выполнения указанной операции. Этот параметр должен содержать допустимое значение, которое не NULL. Вы несете ответственность за проверку значения. Если вы не проверяете его, вы получите непредвиденные результаты.
Возвращаемое значение
Тип: int
Возвращает ноль в случае успешного выполнения; в противном случае ненулевое значение. Приложения обычно должны просто проверять ноль или ненулевое значение.
Рекомендуется изучить значение fAnyOperationsAborted члена SHFILEOPSTRUCT. 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, на которую указывает lpFileOpOp. Установка этого флага отправляет файл в корзину. Если вы хотите просто удалить файл и гарантировать, что он не помещается в корзину, используйте DeleteFile.
Если обработчик обратного вызова копирования предоставляется и зарегистрирован, SHFileOperation вызывает его, если только не задан флаг, например FOF_NOCONFIRMATION в fFlags член структуры, на который указывает lpFileOp. Дополнительные сведения о реализации обработчиков обратного вызова копирования см. в ICopyHook::CopyCallback.
Удаление файлов рекурсивно, если вы не задали флаг FOF_NORECURSION в lpFileOp.
подключение файлов
С помощью 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. Термин "files" может потребоваться заменить эквивалентным словом на локальном языке.
Заметка
Заголовок shellapi.h определяет SHFileOperation как псевдоним, который автоматически выбирает версию ANSI или Юникод этой функции на основе определения константы препроцессора ЮНИКОДа. Сочетание использования псевдонима, нейтрального для кодирования, с кодом, не зависящим от кодирования, может привести к несоответствиям, которые приводят к ошибкам компиляции или среды выполнения. Дополнительные сведения см. в соглашениях о прототипах функций.
Требования
| Требование | Ценность |
|---|---|
| минимальные поддерживаемые клиентские | Windows XP [только классические приложения] |
| минимальный поддерживаемый сервер | Windows 2000 Server [только классические приложения] |
| целевая платформа | Виндоус |
| заголовка | shellapi.h |
| библиотеки |
Shell32.lib |
| DLL | Shell32.dll (версия 4.0 или более поздняя версия) |
| набор API | ext-ms-win-shell-shell32-l1-2-1 (представлено в Windows 10 версии 10.0.10240) |