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 somente 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 nula. Não tente determinar o tamanho do buffer passando um valor 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 TCHAR, não incluindo o caractere nulo de terminação. No retorno de ERROR_SUCCESS, pcchResultBuf contém o número de TCHARgravados no buffer, não incluindo o caractere nulo de terminação.
[in, out] pcchResultBuf
Ponteiro para a variável que especifica o tamanho, em TCHAR, 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, não incluindo 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, não incluindo o caractere nulo de encerramento, na variável apontada por pcchResultBuf.
Valor de retorno
A função MsiFormatRecord retorna um dos seguintes valores:
Observações
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 ficará 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, todos os textos nas chaves e nas chaves serão removidos.
Observe que, no caso de ações personalizadas de execução adiada, msiFormatRecord dá suporte apenas a propriedades CustomActionData e ProductCode. Para obter mais informações, consulte Obtendo 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
- 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.
-
A cadeia de caracteres resultante é processada substituindo os parâmetros não registrados pelos valores correspondentes, descritos em seguida.
- Se uma subcadeia de caracteres do formulário "[propertyname]" for encontrada, ela será substituída pelo valor da propriedade.
- Se uma subcadeia de caracteres do formulário "[%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, pelo valor filekey usado como uma chave na tabela arquivo . O valor de "[#filekey]" permanece em branco e não será substituído por um caminho até que o instalador execute a ação CostInitialize, de ação FileCost e de ação CostFinalize. O valor de "[#filekey]" depende do estado de instalação do componente ao qual o arquivo pertence. Se o componente estiver sendo executado da origem, o valor será o caminho para o local de origem do arquivo. Se o componente estiver sendo 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, consulte Verificando a instalação de recursos, componentes, arquivos.
- Se uma subcadeia de caracteres do formulário "[$componentkey]" for encontrada, ela será substituída pelo diretório de instalação do componente, com o valor componentkey usado como uma chave na tabela componente . O valor de "[$componentkey]" permanece em branco e não será substituído por um diretório até que o instalador execute a ação CostInitialize, de ação FileCost e ação CostFinalize. O valor de "[$componentkey]" depende do estado de instalação do componente. Se o componente estiver sendo executado da origem, o valor será o diretório de origem do arquivo. Se o componente estiver sendo 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, consulte Verificando a instalação de recursos, componentes, 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 subcadeia de caracteres do formulário "[\c]" for encontrada, ela será substituída pelo caractere sem nenhum processamento adicional. Somente o primeiro caractere após a barra invertida ser mantida; todo o resto é removido.
Nota
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 do pré-processador UNICODE. A combinação do uso do alias neutro de codificação com código que não é neutro em codificação pode levar a incompatibilidades que resultam em erros de compilação ou de runtime. Para obter mais informações, consulte Conventions for Function Prototypes.
Requisitos
| Requisito | Valor |
|---|---|
| de cliente com suporte mínimo | Windows Installer 5.0 no Windows Server 2012, Windows 8, Windows Server 2008 R2 ou Windows 7. Windows Installer 4.0 ou Windows Installer 4.5 no Windows Server 2008 ou Windows Vista. |
| da Plataforma de Destino |
Windows |
| cabeçalho | msiquery.h |
| biblioteca | Msi.lib |
| de DLL |
Msi.dll |
Consulte também
passando nulo como o argumento do Windows Installer Functions