Função MsiEnumProductsExW (msi.h)

Artigo
11/20/2024

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

Sintaxe

UINT MsiEnumProductsExW(
  [in, optional]      LPCWSTR           szProductCode,
  [in]                LPCWSTR           szUserSid,
  [in]                DWORD             dwContext,
  [in]                DWORD             dwIndex,
  [out, optional]     WCHAR [39]        szInstalledProductCode,
  [out, optional]     MSIINSTALLCONTEXT *pdwInstalledContext,
  [out, optional]     LPWSTR            szSid,
  [in, out, optional] LPDWORD           pcchSid
);

Parâmetros

[in, optional] szProductCode

ProductCode GUID do produto a ser enumerado. Somente as instâncias de produtos no 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 do s-1-1-0 é considerado um SID do 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
NULL	Especifica o usuário conectado no momento.
sid do usuário	Especifica a enumeração para 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 a enumeração entre todos os usuários no sistema.

Observação 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 apenas como 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 a todas as instalações gerenciadas por usuário para os usuários especificados pelo szUserSid. Um SID inválido não retorna itens.
MSIINSTALLCONTEXT_USERUNMANAGED	Enumeração estendida a todas as instalações não gerenciadas por usuário para os usuários especificados pelo szUserSid. Um SID inválido não retorna itens.
MSIINSTALLCONTEXT_MACHINE	Enumeração estendida a todas as instalações por computador. Quando dwInstallContext é definido apenas como MSIINSTALLCONTEXT_MACHINE, o parâmetro szUserSID do 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 incrementada 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 tem 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 ProductCode GUID da instância do produto que está sendo enumerada. Esse parâmetro pode ser NULL.

[out, optional] pdwInstalledContext

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

[out, optional] szSid

Um buffer de saída que recebe o SID de cadeia de caracteres da conta na qual essa instância do 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 para o número de TCHAR no SID, não incluindo o caractere NULL de terminação.

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

Se szSid e pcchSid estiverem definidas 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 de szSid do . Quando a função retorna, esse parâmetro é definido como o tamanho do valor solicitado se a função copia 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 pode ser definido como NULL somente se szSid também estiver NULL, caso contrário, a função retornará ERROR_INVALID_PARAMETER.

Valor de retorno

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.

Observações

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é retornar ERROR_NO_MORE_ITEMS e não houver 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 em uma conta de usuário diferente da conta de usuário atual. A enumeração ignora produtos que são anunciados somente (como produtos não instalados) no contexto não gerenciado por usuário ao enumerar em 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 do produto enumerada MsiEnumProductsEx.

Nota

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. 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 3.0 ou posterior 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

MsiEnumProducts

sem suporte no Windows Installer 2.0 e anteriores

ProductCode

removendo patches

Compartilhar via