msiquery.h) (MsiFormatRecordA 函数

  • 项目

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

语法

UINT MsiFormatRecordA(
  [in]      MSIHANDLE hInstall,
  [in]      MSIHANDLE hRecord,
  [out]     LPSTR     szResultBuf,
  [in, out] LPDWORD   pcchResultBuf
);

parameters

[in] hInstall

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

[in] hRecord

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

[out] szResultBuf

指向接收 null 终止格式字符串的缓冲区的指针。 请勿尝试通过为 szResultBuf 传入 null (value=0) 来确定缓冲区的大小。 可以通过传入空字符串 (（例如“”) ）来获取缓冲区的大小。 然后，该函数返回 ERROR_MORE_DATA 并且 pcchResultBuf 在 TCHAR中包含所需的缓冲区大小，不包括终止 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 函数的参数传递