Função MsiLocateComponentA (msi.h)

Artigo
11/20/2024

A função MsiLocateComponent retorna o caminho completo para um componente instalado sem um código do produto. Essa função tenta determinar o produto usando msiGetProductCode, mas não é garantido que encontre o produto correto para o chamador. MsiGetComponentPath sempre deve ser chamado quando possível.

Sintaxe

INSTALLSTATE MsiLocateComponentA(
  [in]      LPCSTR  szComponent,
  [out]     LPSTR   lpPathBuf,
  [in, out] LPDWORD pcchBuf
);

Parâmetros

[in] szComponent

Especifica a ID do componente a ser localizado.

[out] lpPathBuf

Ponteiro para uma variável que recebe o caminho para o componente. A variável inclui o caractere nulo de encerramento.

[in, out] pcchBuf

Ponteiro para uma variável que especifica o tamanho, em caracteres, do buffer apontado pelo parâmetro lpPathBuf. Na entrada, esse é o tamanho total do buffer, incluindo um espaço para um caractere nulo de terminação. Após o sucesso da função MsiLocateComponent, a variável apontada por pcchBuf contém a contagem de caracteres que não incluem o caractere nulo de terminação. Se o tamanho do buffer passado for muito pequeno, a função retornará INSTALLSTATE_MOREDATA.

Se lpPathBuf for nulo, pcchBuf poderá ser nulo.

Valor de retorno

Valor	Significado
INSTALLSTATE_NOTUSED	O componente que está sendo solicitado está desabilitado no computador.
INSTALLSTATE_ABSENT	O componente não está instalado. Consulte Comentários.
INSTALLSTATE_INVALIDARG	Um dos parâmetros de função é inválido.
INSTALLSTATE_LOCAL	O componente é instalado localmente.
INSTALLSTATE_MOREDATA	O buffer fornecido era muito pequeno.
INSTALLSTATE_SOURCE	O componente é instalado para ser executado da origem.
INSTALLSTATE_SOURCEABSENT	A origem do componente está inacessível.
INSTALLSTATE_UNKNOWN	O código do produto ou a ID do componente é desconhecido. Consulte Comentários.

Observações

A função MsiLocateComponent pode retornar INSTALLSTATE_ABSENT ou INSTALL_STATE_UNKNOWN, pelos seguintes motivos:

INSTALLSTATE_ABSENT
O aplicativo não garantiu corretamente que o recurso foi instalado chamando MsiUseFeature e, se necessário, MsiConfigureFeature.
INSTALLSTATE_UNKNOWN
O recurso não foi publicado. O aplicativo deve ter determinado isso anteriormente chamando MsiQueryFeatureState ou MsiEnumFeatures. O aplicativo faz essas chamadas enquanto inicializa. Um aplicativo só deve usar recursos que são conhecidos por serem publicados. Como INSTALLSTATE_UNKNOWN deveria ter sido retornado por msiUseFeature também, msiUseFeature não foi chamado ou seu valor retornado não foi verificado corretamente.

Nota

O cabeçalho msi.h define MsiLocateComponent 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. Windows Installer no Windows Server 2003 ou Windows XP. Consulte os Requisitos de Run-Time do Windows Installer para obter informações sobre o service pack mínimo do Windows exigido por uma versão do Windows Installer.
da Plataforma de Destino	Windows
cabeçalho	msi.h
biblioteca	Msi.lib
de DLL	Msi.dll

Consulte também

Funções Component-Specific

Compartilhar via