SetupScanFileQueueA 函数 (setupapi.h)

  • 项目

[此函数可用于“要求”部分所示的操作系统。 它可能在后续版本中变更或不可用。 安装程序API 不应再用于安装应用程序。 请改用 Windows 安装程序来开发应用程序安装程序。 SetupAPI 继续用于安装设备驱动程序。]

SetupScanFileQueue 函数扫描安装文件队列，并对其副本列表中的每个节点执行操作。 操作由一组标志指定。 可以在提交队列之前或之后调用此函数。

语法

WINSETUPAPI BOOL SetupScanFileQueueA(
  [in]  HSPFILEQ            FileQueue,
  [in]  DWORD               Flags,
  [in]  HWND                Window,
  [in]  PSP_FILE_CALLBACK_A CallbackRoutine,
  [in]  PVOID               CallbackContext,
  [out] PDWORD              Result
);

参数

[in] FileQueue

要扫描或循环访问其复制列表的安装程序文件队列的句柄。

[in] Flags

要合并以控制文件队列扫描操作的标志。 请注意，必须指定SPQ_SCAN_FILE_PRESENCE、SPQ_SCAN_USE_CALLBACK、SPQ_SCAN_USE_CALLBACKEX或SPQ_SCAN_FILE_VALIDITY。

标志 含义
SPQ_SCAN_FILE_PRESENCE
 复制队列中的目标文件已存在于目标上。
SPQ_SCAN_FILE_VALIDITY
 复制队列中的目标文件已存在于具有有效签名的目标上。 适用于 Windows 2000 及更高版本。
SPQ_SCAN_USE_CALLBACK
 队列中每个节点的回调例程。 如果回调例程返回非零值，队列处理将停止， SetupScanFileQueue 返回零。 发出 SPFILENOTIFY_QUEUESCAN 通知代码，并将指向目标路径的指针作为 Param1 传递。
SPQ_SCAN_USE_CALLBACKEX
 队列中每个节点的回调例程。 如果回调例程返回非零值，队列处理将停止， SetupScanFileQueue 返回零。 发出SPFILENOTIFY_QUEUESCAN_EX通知，并将指向 FILEPATHS 结构的指针作为 Param1 传递。 SPQ_SCAN_USE_CALLBACKEX还会检查文件是否具有有效的签名。 从 Windows 2000 开始可用。 仅在 Windows XP 上，可以通过将此标志与SPQ_SCAN_FILE_PRESENCE组合来关闭签名检查。
SPQ_SCAN_INFORM_USER
 当队列中的所有文件都为有效签名传递检查时指定的标志。 SetupScanFileQueue 通知用户，该操作需要目标上已存在的文件。 如果未指定SPQ_SCAN_FILE_PRESENCE或SPQ_SCAN_FILE_VALIDITY，则忽略此标志。 此标志不能与SPQ_SCAN_PRUNE_COPY_QUEUE或SPQ_SCAN_PRUNE_DELREN一起使用。
SPQ_SCAN_PRUNE_COPY_QUEUE
 与 SPQ_SCAN_FILE_PRESENCE 结合使用，从复制队列中删除现有条目。 与 SPQ_SCAN_FILE_VALIDITY 结合使用时，会从复制队列中删除已签名的条目。 从 Windows 2000 开始可用。 仅在 Windows XP 上，除非指定了SPQ_SCAN_PRUNE_DELREN，否则不会修剪在删除队列或重命名队列中指定的文件。
SPQ_SCAN_USE_CALLBACK_SIGNERINFO
 从 Windows XP 开始可用。 问题SPFILENOTIFY_QUEUESCAN_SIGNERINFO通知，并将指针作为 Param1 传递给FILEPATHS_SIGNERINFO结构。 检查每个文件是否存在有效的签名，并通过回调函数报告签名信息。
SPQ_SCAN_PRUNE_DELREN
 结合SPQ_SCAN_FILE_PRESENCE或SPQ_SCAN_FILE_VALIDITY，删除或重命名队列中也位于复制队列中的条目。 与 SPQ_SCAN_PRUNE_COPY_QUEUE 结合使用时，将从复制队列中删除的文件限制为不在删除或重命名队列中的文件。 从 Windows XP 开始可用。

[in] Window

窗口的可选句柄，用于拥有显示的对话框。 如果 Flags 参数不包含SPQ_SCAN_FILE_PRESENCE或 Flags 不包含SPQ_SCAN_INFORM_USER，则不使用此参数。

[in] CallbackRoutine

指向在复制队列的每个节点上调用 的 FileCallback 回调函数的可选指针。 传递给回调函数的通知代码 SPFILENOTIFY_QUEUESCAN。 如果 Flags 包含SPQ_SCAN_USE_CALLBACK，则此参数是必需的。

注意 必须提供由 CallbackRoutine 指定的回调例程。 默认队列回调例程不支持 SetupScanFileQueue。
 

[in] CallbackContext

指向上下文的可选指针，该上下文包含传递给 CallbackRoutine 指向的回调例程的调用方定义数据。

[out] Result

指向接收扫描操作结果的变量的指针。

返回值

如果已处理队列中的所有节点，则函数将返回非零值。

如果设置了SPQ_SCAN_USE_CALLBACK标志， 则 Result 中的值为 0。 CallbackRoutine 指定的回调例程SPFILENOTIFY_QUEUESCAN发送通知。 CallbackRoutine.Param1 指定指向包含目标路径信息的数组的指针。 指针已强制转换为无符号整数，并且必须重新转换为MAX_PATH元素的 TCHAR 数组，回调例程才能访问信息。 如果当前队列节点正在使用，则 CallbackRoutine.Param2 设置为 SPQ_DELAYED_COPY，在重启系统之前无法复制。 否则， CallbackRoutine.Param2 采用值 0。

如果未设置SPQ_SCAN_USE_CALLBACK，则 Result 指示队列是通过状态或有效性检查，如下表所示。

返回代码 说明
0
 队列检查失败或传递了检查，但指定了SPQ_SCAN_INFORM_USER，用户需要文件的新副本。
1
 队列传递了检查，如果指定了SPQ_SCAN_INFORM_USER，则用户指示不需要复制。 复制队列为空，删除或重命名队列上没有元素，因此调用方可以跳过队列提交。
2
 队列传递了检查，如果指定了SPQ_SCAN_INFORM_USER，则用户指示不需要复制。 复制队列为空，但删除或重命名队列上有元素，因此调用方无法跳过队列提交。
 

如果发生错误或回调函数返回非零值，则函数返回零。 如果 Result 为非零值，则它是回调函数返回的停止队列处理的值。 如果 Result 为零，则可以通过调用 GetLastError 来检索扩展错误信息。

注解

注意

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

要求

要求 值
最低受支持的客户端 Windows XP [仅限桌面应用]
最低受支持的服务器 Windows Server 2003 [仅限桌面应用]
目标平台 Windows
标头 setupapi.h
Library Setupapi.lib
DLL Setupapi.dll

另请参阅

FileCallback

函数

概述

SetupCommitFileQueue

SetupDefaultQueueCallback