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.
[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.
[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 |
|---|---|
|
Se o escopo incluir usuários diferentes do usuário atual, você precisará de privilégios de administrador. |
|
Os dados de configuração estão corrompidos. |
|
Um parâmetro inválido foi passado para a função. |
|
Não há mais produtos para enumerar. |
|
Um produto é enumerado. |
|
O parâmetro szSid é muito pequeno para obter o SID do usuário. |
|
O produto não está instalado no computador no contexto especificado. |
|
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
Sem suporte no Windows Installer 2.0 e nas versões anteriores