Função MsiFormatRecordA (msiquery.h)

A função MsiFormatRecord formata dados de campo de registro e propriedades usando uma cadeia de caracteres de formato.

Sintaxe

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

Parâmetros

[in] hInstall

Manipule para a instalação. Isso pode ser omitido, caso em que apenas os parâmetros de campo de registro são processados e as propriedades não estão disponíveis para substituição.

[in] hRecord

Manipule para o registro a ser formatado. A cadeia de caracteres de modelo deve ser armazenada no campo de registro 0 seguido por parâmetros de dados referenciados.

[out] szResultBuf

Ponteiro para o buffer que recebe a cadeia de caracteres formatada terminada em nulo. Não tente determinar o tamanho do buffer passando um nulo (valor=0) para szResultBuf. Você pode obter o tamanho do buffer passando uma cadeia de caracteres vazia (por exemplo, ""). Em seguida, a função retorna ERROR_MORE_DATA e pcchResultBuf contém o tamanho do buffer necessário em TCHARs, sem incluir o caractere nulo de terminação. No retorno de ERROR_SUCCESS, pcchResultBuf contém o número de TCHARgravados no buffer, sem incluir o caractere nulo de terminação.

[in, out] pcchResultBuf

Ponteiro para a variável que especifica o tamanho, em TCHARs, do buffer apontado pela variável szResultBuf. Quando a função retorna ERROR_SUCCESS, essa variável contém o tamanho dos dados copiados para szResultBuf, sem incluir o caractere nulo de terminação. Se szResultBuf não for grande o suficiente, a função retornará ERROR_MORE_DATA e armazenará o tamanho necessário, sem incluir o caractere nulo de terminação, na variável apontada por pcchResultBuf.

Valor retornado

A função MsiFormatRecord retorna um dos seguintes valores:

Comentários

A função MsiFormatRecord usa o processo de formato a seguir.

Os parâmetros que devem ser formatados são colocados entre colchetes […]. Os colchetes podem ser iterados porque as substituições são resolvidas de dentro para fora.

Se uma parte da cadeia de caracteres estiver entre chaves { } e não contiver colchetes, ela será deixada inalterada, incluindo as chaves.

Se uma parte da cadeia de caracteres estiver entre chaves { } e contiver um ou mais nomes de propriedade, e se todas as propriedades forem encontradas, o texto (com as substituições resolvidas) será exibido sem as chaves. Se alguma das propriedades não for encontrada, todo o texto nas chaves e as chaves serão removidos.

Observação no caso de ações personalizadas de execução adiada, MsiFormatRecord dá suporte apenas às propriedades CustomActionData e ProductCode . Para obter mais informações, confira Como obter informações de contexto para ações personalizadas de execução adiada.

As etapas a seguir descrevem como formatar cadeias de caracteres usando a função MsiFormatRecord :

Para formatar cadeias de caracteres usando a função MsiFormatRecord

1. Os parâmetros numéricos são substituídos pela substituição do marcador pelo valor do campo de registro correspondente, por valores ausentes ou nulos que não produzem texto.
2. A cadeia de caracteres resultante é processada substituindo os parâmetros não registrados pelos valores correspondentes, descritos em seguida.
   • Se uma substring do formato [propertyname] for encontrada, ela será substituída pelo valor da propriedade.
   • Se uma substring do formato [%environmentvariable] for encontrada, o valor da variável de ambiente será substituído.
   • Se uma subcadeia de caracteres do formulário" [#filekey]" for encontrada, ela será substituída pelo caminho completo do arquivo, pela chave de arquivo de valor usada como uma chave na tabela Arquivo. O valor de "[#filekey]" permanece em branco e não é substituído por um caminho até que o instalador execute a ação CostInitialize, a ação FileCost e a ação CostFinalize. O valor de "[#filekey]" depende do estado de instalação do componente ao qual o arquivo pertence. Se o componente for executado por meio da origem, o valor será o caminho para o local de origem do arquivo. Se o componente for executado localmente, o valor será o caminho para o local de destino do arquivo após a instalação. Se o componente estiver ausente, o caminho estará em branco. Para obter mais informações sobre como verificar o estado de instalação dos componentes, confira Como verificar a instalação de recursos, componentes e arquivos.
   • Se uma subcadeia de caracteres do formulário "[$componentkey]" for encontrada, ela será substituída pelo diretório de instalação do componente, pela chave de componente de valor usada como uma chave na tabela Componente. O valor de "[$componentkey]" permanece em branco e não é substituído por um diretório até que o instalador execute a ação CostInitialize, a ação FileCost e a ação CostFinalize. O valor de "[$componentkey]" depende do estado de instalação do componente. Se o componente for executado por meio da origem, o valor será o diretório de origem do arquivo. Se o componente for executado localmente, o valor será o diretório de destino após a instalação. Se o componente estiver ausente, o valor será deixado em branco. Para obter mais informações sobre como verificar o estado de instalação dos componentes, confira Como verificar a instalação de recursos, componentes e arquivos.
   • Observe que, se um componente já estiver instalado e não estiver sendo reinstalado, removido ou movido durante a instalação atual, o estado de ação do componente será nulo e, portanto, a cadeia de caracteres "[$componentkey]" será avaliada como Null.
   • Se uma substring do formato "[\c]" for encontrada, ela será substituída pelo caractere, sem nenhum processamento adicional. Somente o primeiro caractere depois da barra invertida é mantido. O restante é removido.

Se ERROR_MORE_DATA for retornado, o parâmetro que é um ponteiro fornecerá o tamanho do buffer necessário para manter a cadeia de caracteres. Se ERROR_SUCCESS for retornado, ele fornecerá o número de caracteres gravados no buffer de cadeia de caracteres. Portanto, você pode obter o tamanho do buffer passando uma cadeia de caracteres vazia (por exemplo, "") para o parâmetro que especifica o buffer. Não tente determinar o tamanho do buffer passando um Null (value=0).

Observação

O cabeçalho msiquery.h define MsiFormatRecord como um alias que seleciona automaticamente a versão ANSI ou Unicode dessa função com base na definição da constante de pré-processador UNICODE. Misturar o uso do alias neutro de codificação com código que não seja neutro em codificação pode levar a incompatibilidades que resultam em erros de compilação ou de runtime. Para obter mais informações, consulte Convenções para protótipos de função.

Requisitos

Cliente mínimo com suporte	Windows Installer 5.0 no Windows Server 2012, no Windows 8, no Windows Server 2008 R2 ou no Windows 7. Windows Installer 4.0 ou Windows Installer 4.5 no Windows Server 2008 ou no Windows Vista.
Plataforma de Destino	Windows
Cabeçalho	msiquery.h
Biblioteca	Msi.lib
DLL	Msi.dll

Confira também

Passando Null como o argumento das funções do Windows Installer