Функция 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" (это с учетом регистра; например, ". Файлы" не работает). Пример приведен здесь.

1. Создайте файл с именем Test.htm в каталоге C:\Files (C:\Files\Test.htm).
2. Создайте папку с именем Test.files в каталоге C:\Files (C:\Files\Test.files).
3. Заполните папку несколькими файлами. Любой файл, помещенный в эту папку, подключен к Test.htm.
4. Переместите или скопируйте файл Test.htm в каталог C:\Files2.
5. Обратите внимание, что каталог 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. Термин "файлы" может потребоваться заменить эквивалентным словом на местном языке.

Требования

Требование	Значение
Минимальная версия клиента	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)