Поделиться через


Функция 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. Термин "файлы" может потребоваться заменить эквивалентным словом на местном языке.

Примечание

Заголовок 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)