Função MsiProvideQualifiedComponentExA (msi.h)

Artigo
08/24/2023

A função MsiProvideQualifiedComponentEx retorna o caminho completo do componente para um componente qualificado que é publicado por um produto e executa 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 MsiProvideQualifiedComponentExA(
  [in]      LPCSTR  szCategory,
  [in]      LPCSTR  szQualifier,
  [in]      DWORD   dwInstallMode,
  [in]      LPCSTR  szProduct,
  [in]      DWORD   dwUnused1,
  [in]      DWORD   dwUnused2,
  [out]     LPSTR   lpPathBuf,
  [in, out] LPDWORD pcchPathBuf
);

Parâmetros

[in] szCategory

Especifica a ID do componente que para o componente solicitado. Esse pode não ser o GUID para o componente em si, mas sim um servidor que fornece a funcionalidade correta, como na coluna ComponentId da Tabela PublishComponent.

[in] szQualifier

Especifica um qualificador em uma lista de componentes de publicidade (de PublishComponent Table).

[in] dwInstallMode

Define o modo de instalação. Esse parâmetro pode usar 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.
INSTALLMODE_EXISTING	Forneça o componente somente se o recurso existir; caso contrário, retorne ERROR_FILE_NOT_FOUND.
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.

[in] szProduct

Especifica o produto a ser correspondido que publicou o componente qualificado. Se for nulo, essa API funcionará da mesma forma que MsiProvideQualifiedComponent.

[in] dwUnused1

Reservado. Deve ser zero.

[in] dwUnused2

Reservado. Deve ser zero.

[out] lpPathBuf

Ponteiro para uma variável que recebe o caminho para o componente. Este 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 terminação.

Se lpPathBuf for nulo, pcchBuf poderá ser nulo.

Valor retornado

Valor	Significado
ERROR_INDEX_ABSENT	Qualificador de componente inválido ou não presente.
ERROR_SUCCESS	A função foi concluída com êxito.
ERROR_FILE_NOT_FOUND	O recurso está ausente ou desfeito. esse erro é retornado para dwInstallMode = INSTALLMODE_EXISTING.
ERROR_UNKNOWN_COMPONENT	O componente especificado é desconhecido.
Um erro relacionado a uma ação	Consulte Códigos de erro.
Erro de inicialização	Ocorreu um erro relacionado à inicialização.

Comentários

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

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 o aplicativo chame MsiReinstallFeature.

Observação

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

Requisito	Valor
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. Windows Installer no Windows Server 2003 ou no Windows XP. Confira os Requisitos de tempo de execução do Windows Installer para obter informações sobre o service pack mínimo do Windows exigido por uma versão do Windows Installer.
Plataforma de Destino	Windows
Cabeçalho	msi.h
Biblioteca	Msi.lib
DLL	Msi.dll