Compartilhar via


Função MsiEnumProductsExA (msi.h)

A função MsiEnumProductsEx enumera por meio de uma ou todas as instâncias de produtos anunciados ou instalados atualmente nos contextos especificados. Essa função substitui MsiEnumProducts.

Sintaxe

UINT MsiEnumProductsExA(
  [in, optional]      LPCSTR            szProductCode,
  [in]                LPCSTR            szUserSid,
  [in]                DWORD             dwContext,
  [in]                DWORD             dwIndex,
  [out, optional]     CHAR [39]         szInstalledProductCode,
  [out, optional]     MSIINSTALLCONTEXT *pdwInstalledContext,
  [out, optional]     LPSTR             szSid,
  [in, out, optional] LPDWORD           pcchSid
);

Parâmetros

[in, optional] szProductCode

Productcode GUID do produto a ser enumerado. Somente instâncias de produtos dentro do escopo do contexto especificado pelos parâmetros szUserSid e dwContext são enumeradas. Esse parâmetro pode ser definido como NULL para enumerar todos os produtos no contexto especificado.

[in] szUserSid

Cadeia de caracteres terminada em nulo que especifica um SID (identificador de segurança) que restringe o contexto de enumeração. A cadeia de caracteres sid especial s-1-1-0 (Todos) especifica a enumeração entre todos os usuários no sistema. Um valor sid diferente de s-1-1-0 é considerado um SID de usuário e restringe a enumeração ao usuário atual ou a qualquer usuário no sistema. Esse parâmetro pode ser definido como NULL para restringir o escopo de enumeração ao usuário atual.

Tipo de SID Significado
NULO
Especifica o usuário conectado no momento.
SID de usuário
Especifica a enumeração para um usuário específico no sistema. Um exemplo de SID do usuário é "S-1-3-64-2415071341-1358098788-3127455600-2561".
s-1-1-0
Especifica a enumeração entre todos os usuários no sistema.
 
Nota A cadeia de caracteres sid especial s-1-5-18 (System) não pode ser usada para enumerar produtos ou patches instalados como por computador. Quando dwContext é definido como somente MSIINSTALLCONTEXT_MACHINE, szUserSid deve ser NULL.
 

[in] dwContext

Restringe a enumeração a um contexto. Esse parâmetro pode ser qualquer um ou uma combinação dos valores mostrados na tabela a seguir.

Contexto Significado
MSIINSTALLCONTEXT_USERMANAGED
Enumeração estendida para todas as instalações gerenciadas por usuário para os usuários especificados por szUserSid. Um SID inválido não retorna itens.
MSIINSTALLCONTEXT_USERUNMANAGED
Enumeração estendida para todas as instalações não gerenciadas por usuário para os usuários especificados por szUserSid. Um SID inválido não retorna itens.
MSIINSTALLCONTEXT_MACHINE
Enumeração estendida para todas as instalações por computador. Quando dwInstallContext é definido como somente MSIINSTALLCONTEXT_MACHINE, o parâmetro szUserSID deve ser NULL.

[in] dwIndex

Especifica o índice do produto a ser recuperado. Esse parâmetro deve ser zero para a primeira chamada para a função MsiEnumProductsEx e, em seguida, incrementado para chamadas subsequentes. O índice deve ser incrementado, somente se a chamada anterior tiver retornado ERROR_SUCCESS. Como os produtos não são ordenados, qualquer novo produto terá um índice arbitrário. Isso significa que a função pode retornar produtos em qualquer ordem.

[out, optional] szInstalledProductCode

Cadeia de caracteres terminada em nulo de TCHAR que fornece o GUID productCode da instância do produto que está sendo enumerada. Este parâmetro pode ser NULL.

[out, optional] pdwInstalledContext

Retorna o contexto da instância do produto que está sendo enumerada. O valor de saída pode ser MSIINSTALLCONTEXT_USERMANAGED, MSIINSTALLCONTEXT_USERUNMANAGED ou MSIINSTALLCONTEXT_MACHINE. Este parâmetro pode ser NULL.

[out, optional] szSid

Um buffer de saída que recebe o SID da cadeia de caracteres da conta sob a qual essa instância de produto existe. Esse buffer retorna uma cadeia de caracteres vazia para uma instância instalada em um contexto por computador.

Esse buffer deve ser grande o suficiente para conter o SID. Se o buffer for muito pequeno, a função retornará ERROR_MORE_DATA e definirá *pcchSid como o número de TCHAR no SID, não incluindo o caractere NULL de terminação.

Se szSid for definido como NULL e pcchSid for definido como um ponteiro válido, a função retornará ERROR_SUCCESS e definirá *pcchSid como o número de TCHAR no valor, sem incluir o NULL de terminação. Em seguida, a função pode ser chamada novamente para recuperar o valor, com o buffer szSid grande o suficiente para conter *pcchSid + 1 caracteres.

Se szSid e pcchSid estiverem definidos como NULL, a função retornará ERROR_SUCCESS se o valor existir, sem recuperar o valor.

[in, out, optional] pcchSid

Ao chamar a função , esse parâmetro deve ser um ponteiro para uma variável que especifica o número de TCHAR no buffer szSid . Quando a função retorna, esse parâmetro é definido como o tamanho do valor solicitado, quer a função copie ou não o valor para o buffer especificado. O tamanho é retornado como o número de TCHAR no valor solicitado, não incluindo o caractere nulo de terminação.

Esse parâmetro só poderá ser definido como NULL se szSid também for NULL; caso contrário, a função retornará ERROR_INVALID_PARAMETER.

Retornar valor

A função MsiEnumProductsEx retorna um dos valores a seguir.

Código de retorno Descrição
ERROR_ACCESS_DENIED
Se o escopo incluir usuários diferentes do usuário atual, você precisará de privilégios de administrador.
ERROR_BAD_CONFIGURATION
Os dados de configuração estão corrompidos.
ERROR_INVALID_PARAMETER
Um parâmetro inválido foi passado para a função.
ERROR_NO_MORE_ITEMS
Não há mais produtos para enumerar.
ERROR_SUCCESS
Um produto é enumerado.
ERROR_MORE_DATA
O parâmetro szSid é muito pequeno para obter o SID do usuário.
ERROR_UNKNOWN_PRODUCT
O produto não está instalado no computador no contexto especificado.
ERROR_FUNCTION_FAILED
Uma falha interna inesperada.

Comentários

Para enumerar produtos, um aplicativo deve inicialmente chamar a função MsiEnumProductsEx com o parâmetro iIndex definido como zero. Em seguida, o aplicativo deve incrementar o parâmetro iProductIndex e chamar MsiEnumProductsEx até que retorne ERROR_NO_MORE_ITEMS e não haja mais produtos para enumerar.

Ao fazer várias chamadas para MsiEnumProductsEx para enumerar todos os produtos, cada chamada deve ser feita do mesmo thread.

Um usuário deve ter privilégios de administrador para enumerar produtos em todas as contas de usuário ou uma conta de usuário diferente da conta de usuário atual. A enumeração ignora os produtos que são anunciados somente (como produtos não instalados) no contexto por usuário não gerenciado ao enumerar entre todos os usuários ou um usuário diferente do usuário atual.

Use MsiGetProductInfoEx para obter o estado ou outras informações sobre cada instância de produto enumerada por MsiEnumProductsEx.

Observação

O cabeçalho msi.h define MsiEnumProductsEx 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 3.0 ou versões posteriores 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

Confira também

MsiEnumProducts

Sem suporte no Windows Installer 2.0 e nas versões anteriores

ProductCode

Como remover patches