SHFILEOPSTRUCTA 结构 (shellapi.h)

包含 SHFileOperation 函数用于执行文件操作的信息。

注意 从 Windows Vista 起，建议使用此函数的 IFileOperation 接口。

 

语法

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

注意 此字符串必须以双 null 结尾。

 

指向一个或多个源文件名称的指针。 这些名称应是完全限定的路径，以防止出现意外结果。

标准 MS-DOS 通配符（如“*”） 仅 允许在文件名位置中使用。 在字符串中的其他位置使用通配符将导致不可预知的结果。

尽管此成员声明为单个以 null 结尾的字符串，但它实际上是一个可以保存多个以 null 分隔的文件名的缓冲区。 每个文件名以单个 NULL 字符结尾。 最后一个文件名以双 NULL 字符 (“\0\0”) 终止，以指示缓冲区的末尾。

pTo

类型： PCZZTSTR

注意 此字符串必须以双 null 结尾。

 

指向目标文件或目录名称的指针。 如果未使用此参数，则必须将其设置为 NULL 。 不允许使用通配符。 它们的使用将导致不可预知的结果。

与 pFrom 一样， pTo 成员也是双 null 终止字符串，其处理方式大致相同。 但是， pTo 必须满足以下规范：

• 不支持通配符。
• 复制和移动操作可以指定不存在的目标目录。 在这些情况下，系统会尝试创建它们，并且通常会显示一个对话框，询问用户是否要创建新目录。 若要禁止显示此对话框并让目录以无提示方式创建，请在 fFlags 中设置FOF_NOCONFIRMMKDIR标志。
• 对于“复制”和“移动”操作，如果 fFlags 成员指定 了FOF_MULTIDESTFILES，则缓冲区可以包含多个目标文件名。
• 以与 pFrom 相同的方式将多个名称打包到 pTo 字符串中。
• 使用完全限定的路径。 不禁止使用相对路径，但可能会产生不可预知的结果。

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。 以无提示方式执行操作，不向用户显示任何 UI。 这等效于 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。 用户可以通过 UI 手动中止操作，或者如果设置了FOF_NOERRORUI或FOF_NOCONFIRMATION标志，系统也可以以无提示方式中止操作。

hNameMappings

类型： LPVOID

函数返回时，此成员包含名称映射对象的句柄，该对象包含重命名文件的旧名称和新名称。 仅当 fFlags 成员包含 FOF_WANTMAPPINGHANDLE 标志时，才使用此成员。 有关更多详细信息，请参阅备注。

lpszProgressTitle

类型： PCTSTR

指向进度对话框标题的指针。 这是一个以 null 结尾的字符串。 仅当 fFlags 包含 FOF_SIMPLEPROGRESS 标志时，才使用此成员。

注解

重要 必须确保源路径和目标路径以双 null 结尾。 普通字符串仅以单个 null 字符结尾。 如果在源成员或目标成员中传递该值，则函数不会在到达字符串的末尾时实现，并且将继续在内存中读取，直到它出现随机的双 null 值。 这至少会导致缓冲区溢出，并可能意外删除不相关的数据。

 

// WRONG
LPTSTR pszSource = L"C:\\Windows\\*";

// RIGHT
LPTSTR pszSource = L"C:\\Windows\\*\0";

若要考虑两个终止 null 字符，请确保创建足够大的缓冲区来保存MAX_PATH (通常包括单个终止 null 字符) 加 1。

不能夸大路径应始终是完整路径。 如果 pFrom 或 pTo 成员是非限定名称，则当前目录取自由 GetCurrentDirectory 和 SetCurrentDirectory 函数管理的全局当前驱动器和目录设置。

如果未提供完整路径，则以下事实将变得相关：

• 文件名前缺少路径并不向 SHFileOperation 指示此文件驻留在当前目录的根目录中。
• SHFileOperation 不使用 PATH 环境变量来确定有效路径。
• 在开始执行时，不能依赖 SHFileOperation 来使用作为当前目录的目录。 被视为当前目录的目录在进程范围内，可以在执行操作时从另一个线程进行更改。 如果发生这种情况， SHFileOperation 的结果将是不可预知的。

如果将 pFrom 设置为没有完整路径的文件名，则删除具有 FO_DELETE 的文件不会将其移动到回收站，即使设置了 FOF_ALLOWUNDO 标志也是如此。 必须提供完整路径才能将文件删除到回收站。

SHFileOperation 在前缀为“\？”的任何路径上都失败。

此结构有两个版本，一个是 ANSI 版本 (SHFILEOPSTRUCTA) ，一个 Unicode 版本 (SHFILEOPSTRUCTW) 。 Unicode 版本与 ANSI 版本相同，只是使用 LPCWSTR) (宽字符串来代替 LPCSTR) (ANSI 字符串。 在 Windows 98 及更早版本上，仅支持 ANSI 版本。 在 Microsoft Windows NT 4.0 及更高版本中，支持此结构的 ANSI 和 Unicode 版本。 永远不应直接使用 SHFILEOPSTRUCTW 和 SHFILEOPTSTRUCTA;预编译程序将适当的结构重新定义为 SHFILEOPSTRUCT ，具体取决于是针对 ANSI 还是 Unicode 编译应用程序。

SHNAMEMAPPING 具有类似的 ANSI 和 Unicode 版本。 对于 ANSI 应用程序， hNameMappings 指向 int ，后跟 ANSI SHNAMEMAPPING 结构的数组。 对于 Unicode 应用程序， hNameMappings 指向一个 int ，后跟 Unicode SHNAMEMAPPING 结构数组。 但是，在 Microsoft Windows NT 4.0 及更高版本中， SHFileOperation始终 返回一组 SHNAMEMAPPING 结构的 Unicode 句柄。 如果希望应用程序在所有版本的 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 结构都包含其中一个重命名文件的新旧路径。

注意 必须使用 SHFreeNameMappings 释放句柄。

 

注意

shellapi.h 标头将 SHFILEOPSTRUCT 定义为别名，该别名根据 UNICODE 预处理器常量的定义自动选择此函数的 ANSI 或 Unicode 版本。 将非特定编码别名的使用与非非特定编码的代码混合使用可能会导致不匹配，从而导致编译或运行时错误。 有关详细信息，请参阅 函数原型的约定。

要求

最低受支持的客户端	Windows XP [仅限桌面应用]
最低受支持的服务器	Windows 2000 Server [仅限桌面应用]
标头	shellapi.h