Função MsiProvideComponentA (msi.h)

Artigo
11/20/2024

A função MsiProvideComponent retorna o caminho completo do componente, executando qualquer instalação necessária. Essa função solicita a origem, se necessário, e incrementa a contagem de uso para o recurso.

Sintaxe

UINT MsiProvideComponentA(
  [in]      LPCSTR  szProduct,
  [in]      LPCSTR  szFeature,
  [in]      LPCSTR  szComponent,
  [in]      DWORD   dwInstallMode,
  [out]     LPSTR   lpPathBuf,
  [in, out] LPDWORD pcchPathBuf
);

Parâmetros

[in] szProduct

Especifica o código do produto para o produto que contém o recurso com o componente necessário.

[in] szFeature

Especifica a ID do recurso com o componente necessário.

[in] szComponent

Especifica o código do componente necessário.

[in] dwInstallMode

Define o modo de instalação. Esse parâmetro pode ser um dos valores a seguir.

Valor	Significado
INSTALLMODE_DEFAULT	Forneça o componente e execute qualquer instalação necessária para fornecer o componente. Se o arquivo de chave de um componente no recurso solicitado ou um pai de recurso estiver ausente, reinstale o recurso usando MsiReinstallFeature com os seguintes bits de sinalizador definidos: REINSTALLMODE_FILEMISSING, REINSTALLMODE_FILEOLDERVERSION, REINSTALLMODE_FILEVERIFY, REINSTALLMODE_MACHINEDATA, REINSTALLMODE_USERDATA e REINSTALLMODE_SHORTCUT.
INSTALLMODE_EXISTING	Forneça o componente somente se o recurso existir. Caso contrário, retorne ERROR_FILE_NOT_FOUND. Esse modo verifica se o arquivo de chave do componente existe.
INSTALLMODE_NODETECTION	Forneça o componente somente se o recurso existir. Caso contrário, retorne ERROR_FILE_NOT_FOUND. Esse modo verifica apenas se o componente está registrado e não verifica se o arquivo de chave do componente existe.
combinação dos sinalizadores REINSTALLMODE	Chame MsiReinstallFeature para reinstalar o recurso usando esse parâmetro para o parâmetro dwReinstallMode e forneça o componente.
INSTALLMODE_NOSOURCERESOLUTION	Forneça o componente somente se o estado de instalação do recurso for INSTALLSTATE_LOCAL. Se o estado de instalação do recurso for INSTALLSTATE_SOURCE, retorne ERROR_INSTALL_SOURCE_ABSENT. Caso contrário, retorne ERROR_FILE_NOT_FOUND. Esse modo verifica apenas se o componente está registrado e não verifica se o arquivo de chave existe.

[out] lpPathBuf

Ponteiro para uma variável que recebe o caminho para o componente. Esse parâmetro pode ser nulo.

[in, out] pcchPathBuf

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. Se o buffer passado for muito pequeno, a contagem retornada não incluirá o caractere nulo de encerramento.

Se lpPathBuf for nulo, pcchBuf poderá ser nulo.

Valor de retorno

Valor	Significado
ERROR_BAD_CONFIGURATION	Os dados de configuração estão corrompidos.
ERROR_FILE_NOT_FOUND	O recurso está ausente ou desfeito. esse erro é retornado para dwInstallMode = INSTALLMODE_EXISTING.
ERROR_INSTALL_FAILURE	Falha na instalação.
ERROR_INSTALL_NOTUSED	O componente que está sendo solicitado está desabilitado no computador.
ERROR_INVALID_PARAMETER	Um parâmetro inválido foi passado para a função.
ERROR_SUCCESS	A função foi concluída com êxito.
ERROR_UNKNOWN_FEATURE	A ID do recurso não identifica um recurso conhecido.
ERROR_UNKNOWN_PRODUCT	O código do produto não identifica um produto conhecido.
INSTALLSTATE_UNKNOWN	Um produto não reconhecido ou um nome de recurso foi passado para a função.
ERROR_MORE_DATA	O estouro do buffer é retornado.
ERROR_INSTALL_SOURCE_ABSENT	Não é possível detectar uma origem.

Para obter mais informações, consulte mensagens de erro exibidas.

Observações

Após o sucesso da função de MsiProvideComponent , o parâmetro pcchPathBuf contém o comprimento da cadeia de caracteres em lpPathBuf.

A função MsiProvideComponent combina a funcionalidade de MsiUseFeature, MsiConfigureFeaturee MsiGetComponentPath. Você pode usar a função MsiProvideComponent para simplificar a sequência de chamadas. No entanto, como essa função incrementa a contagem de uso, use-a com cuidado para evitar contagens de uso imprecisas. A função MsiProvideComponent também oferece menos flexibilidade do que a série de chamadas individuais.

Se o aplicativo estiver se recuperando de uma situação inesperada, o aplicativo provavelmente já chamou MsiUseFeature e incrementou a contagem de uso. Nesse caso, o aplicativo deve chamar MsiConfigureFeature em vez de MsiProvideComponent para evitar incrementar a contagem novamente.

A opção INSTALLMODE_EXISTING não pode ser usada em combinação com o sinalizador REINSTALLMODE.

Os recursos com componentes que contêm um arquivo corrompido ou a versão errada de um arquivo devem ser explicitamente reinstalados pelo usuário ou fazendo com que a chamada do aplicativo MsiReinstallFeature.

Nota

O cabeçalho msi.h define MsiProvideComponent 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. 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

instalações Multiple-Package

Compartilhar via