通过

MsiFormatRecordW 函数 (msiquery.h)

  • 项目

MsiFormatRecord 函数使用格式字符串设置记录字段数据和属性的格式。

语法

UINT MsiFormatRecordW(
  [in]      MSIHANDLE hInstall,
  [in]      MSIHANDLE hRecord,
  [out]     LPWSTR    szResultBuf,
  [in, out] LPDWORD   pcchResultBuf
);

parameters

[in] hInstall

安装句柄。 这可以省略，在这种情况下，仅处理记录字段参数，而属性不能用于替换。

[in] hRecord

要格式化的记录的句柄。 模板字符串必须存储在记录字段 0 中，后跟引用的数据参数。

[out] szResultBuf

指向接收 null 终止格式化字符串的缓冲区的指针。 请勿尝试通过为 szResultBuf 传入 null (value=0) 来确定缓冲区的大小。 可以通过传入空字符串 (（例如“”) ）来获取缓冲区的大小。 然后，该函数返回 ERROR_MORE_DATApcchResultBuf 包含 TCHARs 中所需的缓冲区大小，不包括终止 null 字符。 返回 ERROR_SUCCESS时， pcchResultBuf 包含写入缓冲区的 TCHAR数，不包括终止 null 字符。

[in, out] pcchResultBuf

指向变量的指针，该变量指定变量 szResultBuf 指向的缓冲区的大小（以 TCHAR为单位）。 当函数返回 ERROR_SUCCESS时，此变量包含复制到 szResultBuf 的数据的大小，不包括终止 null 字符。 如果 szResultBuf 不够大，则该函数将返回 ERROR_MORE_DATA 并将所需的大小（不包括终止 null 字符）存储在 pcchResultBuf 指向的变量中。

返回值

MsiFormatRecord 函数返回以下值之一：

注解

MsiFormatRecord 函数使用以下格式过程。

要格式化的参数括在方括号 [...] 中。可以循环访问方括号，因为会从内到外解析替换项。

如果字符串的一部分括在大括号 { } 中，而且不包含方括号，则字符串（包括大括号）保持不变。

如果字符串的一部分括在大括号 { } 中，并且包含一个或多个属性名称，并且如果找到所有属性，则显示) 包含已解析替换 (的文本，而不显示大括号。 如果未找到任何属性，则删除大括号和大括号本身中的所有文本。

请注意，在延迟执行自定义操作的情况下， MsiFormatRecord 仅支持 CustomActionData 和 ProductCode 属性。 有关详细信息，请参阅获取延迟执行自定义操作的上下文信息。

以下步骤介绍如何使用 MsiFormatRecord 函数设置字符串的格式：

使用 MsiFormatRecord 函数设置字符串格式

  1. 通过将标记替换为相应记录字段的值来替换数值参数，并用缺失或 null 值不生成文本。
  2. 通过将非记录参数替换为相应的值来处理生成的字符串，如下所述。
    • 如果遇到形式为“[propertyname]”的子字符串，则将其替换为属性的值。
    • 如果发现“[%environmentvariable]”形式的子字符串，则环境变量的值将被替换。
    • 如果找到格式 “[#filekey]” 的子字符串，则会将其替换为文件的完整路径，并将值 filekey 用作 File 表中的键。 “[#filekey]”的值将保留为空，在安装程序运行 CostInitialize 操作、 FileCost 操作和 CostFinalize 操作之前，不会替换为路径。 “[#filekey]”的值取决于文件所属组件的安装状态。 如果组件是从源运行的，则值是文件源位置的路径。 如果组件是在本地运行，则值是安装后文件目标位置的路径。 如果组件不存在，则路径为空。 有关检查组件安装状态的详细信息，请参阅检查功能、组件、文件的安装。
    • 如果找到格式为“[$componentkey]”的子字符串，则会将其替换为组件的安装目录，并将值 componentkey 用作 组件表中的键。 “[$componentkey]”的值保持空白，在安装程序运行 CostInitialize 操作、 FileCost 操作和 CostFinalize 操作之前，不会替换为目录。 “[$componentkey]”的值取决于组件的安装状态。 如果组件是从源运行的，则值是文件的源目录。 如果组件是在本地运行，则值是安装后的目标目录。 如果组件不存在，则值为空。 有关检查组件安装状态的详细信息，请参阅检查功能、组件、文件的安装。
    • 请注意，如果组件已安装，并且未在当前安装期间重新安装、删除或移动，则组件的操作状态为 null，因此字符串“[$componentkey]”的计算结果为 Null。
    • 如果发现形式为“[\c]”的子字符串，则将其替换为该字符，不进行任何进一步处理。 仅保留反斜杠后的第一个字符；其他部分全部删除。
如果返回 ERROR_MORE_DATA ，则指针参数会提供保存字符串所需的缓冲区大小。 如果返回 ERROR_SUCCESS ，则会提供写入字符串缓冲区的字符数。 因此，可以通过传入空字符串 (例如指定缓冲区的参数的“”) 来获取缓冲区的大小。 请勿尝试通过传入 Null (value=0) 来确定缓冲区的大小。

注意

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

要求

   
最低受支持的客户端 Windows Server 2012、Windows 8、Windows Server 2008 R2 或 Windows 7 上的 Windows Installer 5.0。 Windows Server 2008 或 Windows Vista 上的 Windows Installer 4.0 或 Windows Installer 4.5。
目标平台 Windows
标头 msiquery.h
Library Msi.lib
DLL Msi.dll

请参阅

将 Null 作为 Windows Installer 函数的参数传递