SetupCopyOEMInfW 函数 (setupapi.h)

  • 项目

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

SetupCopyOEMInf 函数将指定的 .inf 文件复制到 %windir%/Inf 目录。

此函数的调用方必须具有管理权限，否则该函数将失败。

语法

WINSETUPAPI BOOL SetupCopyOEMInfW(
  [in]            PCWSTR SourceInfFileName,
  [in]            PCWSTR OEMSourceMediaLocation,
  [in]            DWORD  OEMSourceMediaType,
  [in]            DWORD  CopyStyle,
  [out, optional] PWSTR  DestinationInfFileName,
  [in]            DWORD  DestinationInfFileNameSize,
  [out, optional] PDWORD RequiredSize,
  [out, optional] PWSTR  *DestinationInfFileNameComponent
);

参数

[in] SourceInfFileName

源 .inf 文件的完整路径。 应使用以 null 结尾的字符串。 此路径的大小不应超过 MAX_PATH ，包括终止 NULL。

[in] OEMSourceMediaLocation

要存储在预编译的 .inf (.pnf) 中的源位置信息。 此位置信息特定于指定的源媒体类型。 应使用以 null 结尾的字符串。 此路径的大小不应超过 MAX_PATH ，包括终止 NULL。

[in] OEMSourceMediaType

位置信息引用的源媒体类型。 此参数可能是以下值之一。

值 含义
SPOST_NONE
 .pnf 文件中不存储源媒体信息。 在这种情况下， 将忽略 OEMSourceMediaLocation 的值。
SPOST_PATH
 OEMSourceMediaLocation 包含源媒体的路径。 例如，如果媒体位于软盘上，则此路径可能是“A：\”。 如果 OEMSourceMediaLocation 为 NULL，则假定路径为 .inf 所在的路径。 如果 .inf 在该位置具有相应的 .pnf，则 .pnf 文件的源媒体信息将传输到目标 .pnf 文件。
SPOST_URL
 OEMSourceMediaLocation 包含通用资源定位符 (URL) ，用于指定从中检索 .inf/driver 文件的 Internet 位置。 如果 OEMSourceMediaLocation 为 NULL，则假定使用了默认的代码下载管理器位置。

[in] CopyStyle

指定如何将 .inf 文件复制到 .inf 目录。 可以组合以下标志。

值 含义
SP_COPY_DELETESOURCE
 成功复制时删除源文件。
SP_COPY_REPLACEONLY
 仅当此文件已存在于 Inf 目录中时才进行复制。 此标志可用于更新现有 .inf 的源位置信息。
SP_COPY_NOOVERWRITE
 仅当指定的文件当前不存在于 Inf 目录中时才进行复制。 如果 .inf 当前确实存在，则此 API 会失败， GetLastError 将返回ERROR_FILE_EXISTS。 在这种情况下，现有 .inf 文件的文件名将放置在目标 .inf 文件的信息输出缓冲区的相应字段中。
SP_COPY_OEMINF_CATALOG_ONLY
 指定的 .inf 文件的相应目录文件将复制到 %windir%\Inf。 如果指定了此标志，如果指定的 .inf 文件已存在于 Inf 目录中，则会在成功返回时输入目标文件名信息。

[out, optional] DestinationInfFileName

指向缓冲区的指针，用于接收在复制到 Inf 目录时分配给它的 .inf 文件名。 缓冲区（如果指定）通常应 MAX_PATH 长度。 如果指定了 SP_COPY_NOOVERWRITE 标志，并且 SetupCopyOEMInf 函数失败，返回代码为 ERROR_FILE_EXISTS，则此缓冲区包含现有 .inf 文件的名称。 如果指定了 SP_COPY_OEMINF_CATALOG_ONLY 标志，则如果 .inf 文件已存在于 Inf 目录中，则此缓冲区将包含目标 .inf 文件名。 否则，此缓冲区设置为空字符串。 此参数可以为 NULL。

[in] DestinationInfFileNameSize

DestinationInfFileName 缓冲区的大小（以字符为单位），如果未指定缓冲区，则为零。 如果指定 了 DestinationInfFileName ，并且此缓冲区大小小于返回目标 .inf 文件名 (包括完整路径) 所需的大小，则此函数将失败。 在这种情况下 ，GetLastError 返回ERROR_INSUFFICIENT_BUFFER。

[out, optional] RequiredSize

指向一个变量的指针，该变量接收大小 (字符) 存储目标 .inf 文件名（包括终止 NULL）所需的字符。 如果指定了 SP_COPY_OEMINF_CATALOG_ONLY 标志，则仅当 Inf 目录中已存在 .inf 文件时，此变量才会接收字符串长度。 否则，此变量设置为零。 此参数可以为 NULL。

[out, optional] DestinationInfFileNameComponent

指向成功时设置的字符串的指针返回 (或ERROR_FILE_EXISTS) 指向 DestinationInfFileName 参数中存储的路径的文件名组件的开头。 如果指定了SP_COPY_OEMINF_CATALOG_ONLY标志， 则 DestinationInfFileName 参数可能是空字符串。 在这种情况下，成功返回后，字符指针设置为 NULL 。 此参数可以为 NULL。

返回值

此函数返回 WINSETUPAPI BOOL。

注解

SetupCopyOEMInf 函数将指定的 .inf 文件复制到 %windir%\Inf 目录中。 如果 SetupCopyOEMInf 发现指定 .inf 文件的二进制映像已存在于具有相同名称或 OEM*.inf 格式的名称的 Inf 目录中，则不会重新复制该文件。 当 SetupCopyOEMInf 复制文件时，它会将复制的文件重命名为 OEM*.inf。 提供的名称是唯一的，无法预测。

SetupCopyOEMInf 使用以下过程来确定 Inf 目录中是否已存在 .inf 文件：

将枚举名称为 OEM*.inf 的所有 .inf 文件，并且与指定 .inf 文件具有相同文件大小的任何文件进行二进制比较。

在 Inf 目录中搜索 .inf 文件的源文件名。 如果存在同名的 .inf 文件，并且与指定的 .inf 文件的大小相同，则这两个文件是二进制文件，以确定它们是否相同。

如果指定的 .inf 文件已存在，则执行进一步检查以确定指定的 .inf 文件在其 [Version] 节中是否包含 CatalogFile= 条目。 如果存在，则使用扩展名为“.cat”的 .inf 文件的 %windir%\Inf 主文件名来确定是否已安装目录。 如果已安装目录，但与源 .inf 关联的目录不同，则不被视为匹配项，枚举会继续。 可以有多个相同的 .inf 文件，其中包含 %windir%\Inf 目录中的唯一目录。 如果未找到现有匹配项，则 .inf 和 .cat 文件会以新的唯一名称安装。

未指定 CatalogFile= 条目的 OEM .inf 文件在数字签名验证方面被视为无效。

如果必须将 .inf 文件复制到 %windir%\Inf 目录，则会报告任何数字签名验证失败。

如果 .inf 和 .cat 文件已存在，则使用这些现有文件名，并且文件替换行为基于指定的 CopyStyle 标志。 替换行为仅引用存储在 .pnf 中的源媒体信息。 不会修改现有的 .inf、.pnf 和 .cat 文件。

注意

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

要求

要求 值
最低受支持的客户端 Windows XP [仅限桌面应用]
最低受支持的服务器 Windows Server 2003 [仅限桌面应用]
目标平台 Windows
标头 setupapi.h
Library Setupapi.lib
DLL Setupapi.dll
API 集 Windows 10版本 10.0.1439 (3 中引入的 ext-ms-win-setupapi-classinstallers-l1-1-2)

请参阅

函数

概述

SetupUninstallOEMInf