Função MsiEnumComponentsExA (msi.h)
A função MsiEnumComponentsEx enumera componentes instalados. A função recupera o código do componente para um componente sempre que é chamado. O código do componente é o GUID da cadeia de caracteres exclusivo para o componente, a versão e o idioma.
Windows Installer 4.5 ou anterior: Sem suporte. Essa função está disponível a partir do Windows Installer 5.0.
Sintaxe
UINT MsiEnumComponentsExA(
[in, optional] LPCSTR szUserSid,
[in] DWORD dwContext,
[in] DWORD dwIndex,
[out, optional] CHAR [39] szInstalledComponentCode,
[out, optional] MSIINSTALLCONTEXT *pdwInstalledContext,
[out, optional] LPSTR szSid,
[in, out] LPDWORD pcchSid
);
Parâmetros
[in, optional] szUserSid
Uma cadeia de caracteres terminada em nulo que contém um SID (identificador de segurança). A enumeração de componentes instalados estende-se aos usuários identificados por esse SID. A cadeia de caracteres sid especial s-1-1-0 (Todos) especifica uma enumeração de todos os componentes instalados em todos os produtos de todos os usuários no sistema. Um valor sid diferente do s-1-1-0 especifica um SID de usuário para um usuário específico e restringe a enumeração a instâncias de aplicativos instalados pelo usuário especificado.
A cadeia de caracteres sid especial s-1-5-18 (Sistema) não pode ser usada para enumerar 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 apenas como MSIINSTALLCONTEXT_MACHINE, szUserSid deve ser NULL.
[in] dwContext
Um sinalizador que restringe a enumeração do componente instalado a instâncias de produtos instalados no contexto de instalação especificado. A enumeração inclui apenas instâncias de produto instaladas pelos usuários especificados pelo szUserSid.
[in] dwIndex
Especifica o índice do componente a ser recuperado. Esse parâmetro deve ser zero (0) para a primeira chamada para a função MsiEnumComponentsEx . Para cada chamada subsequente, o índice deve ser incrementado em 1. O índice só deverá ser incrementado se a chamada anterior para a função retornar ERROR_SUCCESS. Os componentes não são ordenados e podem ser retornados pela função em qualquer ordem.
[out, optional] szInstalledComponentCode
Um buffer de saída que recebe o GUID de código do componente para o componente instalado. O comprimento do buffer deve ser grande o suficiente para conter um valor de cadeia de caracteres terminada em nulo que contém o código do componente. Os primeiros 38 caracteres TCHAR recebem o GUID do componente e o 39º caractere recebe um caractere NULL de terminação.
[out, optional] pdwInstalledContext
Um sinalizador que fornece ao contexto de instalação o aplicativo que instalou o componente.
[out, optional] szSid
Recebe o SID (identificador de segurança) que identifica o usuário que instalou o aplicativo que possui o componente. O local receberá uma cadeia de caracteres vazia se essa instância do aplicativo estiver instalada em um contexto de instalação por computador.
O comprimento do buffer nesse local deve ser grande o suficiente para conter um valor de cadeia de caracteres terminada em nulo que contém o SID. Se o buffer for muito pequeno, a função retornará ERROR_MORE_DATA e o local apontado por pcchSid receberá o número de TCHAR no SID, sem incluir o caractere NULL de terminação.
Se szSid estiver definido como NULL e pcchSid for um ponteiro válido para um local na memória, a função retornará ERROR_SUCCESS e o local receberá o número de TCHAR no SID, não incluindo o caractere nulo de terminação. Em seguida, a função pode ser chamada novamente para recuperar o valor, com o buffer szSid redimensionado grande o suficiente para conter *pcchSid + 1 caracteres.
| Tipo de SID | Significado |
|---|---|
|
O aplicativo é instalado em um contexto de instalação por computador. |
|
O SID para o usuário no sistema que instalou o aplicativo. |
[in, out] pcchSid
Recebe o número de TCHAR no SID, sem incluir o caractere nulo de terminação. Quando a função retorna, essa variável é definida como o tamanho do SID solicitado se a função pode ou não copiar com êxito o SID e encerrar o caractere nulo no local do buffer apontado pelo szSid. 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. Se szSid e pcchSid estiverem definidos como NULL, a função retornará ERROR_SUCCESS se o SID existir, sem recuperar o valor sid.
Retornar valor
A função MsiEnumProductsEx retorna um dos valores a seguir.
| Código de retorno | Descrição |
|---|---|
|
Privilégios de administrador são necessários para enumerar componentes de aplicativos instalados por usuários diferentes do usuário atual. |
|
Os dados de configuração estão corrompidos. |
|
Um parâmetro inválido é passado para a função . |
|
Não há mais componentes para enumerar. |
|
A função foi bem-sucedida. |
|
O buffer fornecido era muito pequeno para manter todo o valor. |
|
Falha na função. |
Comentários
Observação
O cabeçalho msi.h define MsiEnumComponentsEx 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 |
Comentários
Em breve: Ao longo de 2024, eliminaremos os problemas do GitHub como o mecanismo de comentários para conteúdo e o substituiremos por um novo sistema de comentários. Para obter mais informações, consulte https://aka.ms/ContentUserFeedback.
Enviar e exibir comentários de