Compartilhar via


Função MsiGetComponentPathExA (msi.h)

A função MsiGetComponentPathEx retorna o caminho completo para um componente instalado. Se o caminho da chave do componente for uma chave do Registro, a função retornará a chave do Registro.

Essa função estende a função MsiGetComponentPath existente para habilitar pesquisas de componentes entre contas de usuário e contextos de instalação.

Sintaxe

INSTALLSTATE MsiGetComponentPathExA(
  [in]                LPCSTR            szProductCode,
  [in]                LPCSTR            szComponentCode,
  [in, optional]      LPCSTR            szUserSid,
  [in, optional]      MSIINSTALLCONTEXT dwContext,
  [out, optional]     LPSTR             lpOutPathBuffer,
  [in, out, optional] LPDWORD           pcchOutPathBuffer
);

Parâmetros

[in] szProductCode

Um valor de cadeia de caracteres terminada em nulo que especifica o GUID do código do produto de um aplicativo. A função obtém o caminho dos componentes instalados usados por este aplicativo.

[in] szComponentCode

Um valor de cadeia de caracteres terminada em nulo que especifica um GUID de código de componente. A função obtém o caminho de um componente instalado com esse código de componente.

[in, optional] szUserSid

Um valor de cadeia de caracteres terminada em nulo que especifica o SID (identificador de segurança) de um usuário no sistema. A função obtém os caminhos dos componentes instalados dos aplicativos instalados nas contas de usuário identificadas por esse SID. A cadeia de caracteres sid especial s-1-1-0 (Todos) especifica todos os usuários no sistema. Se esse parâmetro for NULL, a função obterá o caminho de um componente instalado somente para o usuário conectado no momento.

Tipo de SID Significado
NULO
Especifica o usuário conectado no momento.
SID de usuário
Especifica um usuário específico no sistema. Um exemplo de SID de usuário é "S-1-3-64-2415071341-1358098788-3127455600-2561".
s-1-1-0
Especifica todos os usuários no sistema.
 
Nota A cadeia de caracteres sid especial s-1-5-18 (Sistema) não pode ser usada para pesquisar aplicativos instalados no contexto de instalação por computador. Definir o valor sid como s-1-5-18 retorna ERROR_INVALID_PARAMETER. Quando dwContext é definido como somente MSIINSTALLCONTEXT_MACHINE, szUserSid deve ser NULL.
 

[in, optional] dwContext

Um sinalizador que especifica o contexto de instalação. A função obtém os caminhos dos componentes instalados dos aplicativos instalados no contexto de instalação especificado. Esse parâmetro pode ser uma combinação dos seguintes valores.

Contexto Significado
MSIINSTALLCONTEXT_USERMANAGED
1
Inclua aplicativos instalados no contexto de instalação gerenciada por usuário.
MSIINSTALLCONTEXT_USERUNMANAGED
2
Inclua aplicativos instalados no contexto de instalação por usuário– não gerenciado.
MSIINSTALLCONTEXT_MACHINE
4
Inclua aplicativos instalados no contexto de instalação por computador. Quando dwInstallContext é definido como somente MSIINSTALLCONTEXT_MACHINE , o parâmetro szUserSID deve ser NULL.

[out, optional] lpOutPathBuffer

Um valor de cadeia de caracteres que recebe o caminho para o componente. Este parâmetro pode ser NULL. Se o componente for uma chave do Registro, as raízes do Registro serão representadas numericamente. Se esse for um caminho de subchave do Registro, haverá uma barra invertida no final do Caminho da Chave. Se esse for um caminho de chave de valor do Registro, não haverá barra invertida no final. Por exemplo, um caminho do Registro em um sistema operacional de 32 bits do software HKEY_CURRENT_USER\\Microsoft é retornado como "01:\SOFTWARE\Microsoft". As raízes do registro retornadas em sistemas operacionais de 32 bits são definidas conforme mostrado na tabela a seguir.

Nota Em sistemas operacionais de 64 bits, um valor de 20 é adicionado às raízes numéricas do registro nesta tabela para distingui-las dos caminhos de chave do Registro em sistemas operacionais de 32 bits. Por exemplo, um caminho de chave do Registro de HKEY_CURRENT_USER\SOFTWARE\Microsoft será retornado como "21:\SOFTWARE\Microsoft\", se o caminho do componente for uma chave do Registro em um sistema operacional de 64 bits.
 
Root Significado
HKEY_CLASSES_ROOT
00
HKEY_CURRENT_USER
01
HKEY_LOCAL_MACHINE
02
HKEY_USERS
03

[in, out, optional] pcchOutPathBuffer

Ponteiro para um local que recebe o tamanho do buffer, em TCHAR, apontado pelo parâmetro szPathBuf . O valor nesse local deve ser definido como a contagem de TCHAR na cadeia de caracteres, incluindo o caractere nulo de terminação. Se o tamanho do buffer for muito pequeno, esse parâmetro receberá o comprimento do valor da cadeia de caracteres sem incluir o caractere nulo de terminação na contagem.

Retornar valor

A função MsiGetComponentPathEx retorna os valores a seguir.

Valor Significado
INSTALLSTATE_NOTUSED
O componente que está sendo solicitado está desabilitado no computador.
INSTALLSTATE_BADCONFIG
Os dados de configuração estão corrompidos.
INSTALLSTATE_ABSENT
O componente não está instalado.
INSTALLSTATE_INVALIDARG
Um dos parâmetros de função é inválido.
INSTALLSTATE_LOCAL
O componente é instalado localmente.
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.
INSTALLSTATE_BROKEN
O componente está corrompido ou parcialmente ausente de alguma forma e requer reparo.

Comentários

A função MsiGetComponentPathEx 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.

Observação

O cabeçalho msi.h define MsiGetComponentPathEx 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. Confira os Requisitos 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

Confira também

Funções específicas do componente