Função MsiEnumComponentsExA (msi.h)
A função MsiEnumComponentsEx enumera componentes instalados. A função recupera o código do componente para um componente cada vez 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 anteriores: 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 se estende 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 (System) não pode ser usada para enumerar aplicativos instalados no contexto de instalação por computador. Definir o valor de 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 por szUserSid.
[in] dwIndex
Especifica o índice do componente a ser recuperado. Esse parâmetro deve ser zero (0) para a primeira chamada para função msiEnumComponentsEx. Para cada chamada subsequente, o índice deve ser incrementado em 1. O índice só deverá ser incrementado se a chamada anterior à 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 de componente para o componente instalado. O comprimento do buffer deve ser grande o suficiente para manter 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 neste local deve ser grande o suficiente para manter um valor de cadeia de caracteres encerrado 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, não incluindo 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 encerramento. Em seguida, a função pode ser chamada novamente para recuperar o valor, com o szSid buffer 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, não incluindo o caractere nulo de encerramento. 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 por 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 pode ser definido como NULL somente se szSid também estiver NULL, caso contrário, a função retornará ERROR_INVALID_PARAMETER. Se szSid e pcchSid estiverem definidas como NULL, a função retornará ERROR_SUCCESS se o SID existir, sem recuperar o valor de SID.
Valor de retorno
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 o valor inteiro. |
|
Falha na função. |
Observações
Nota
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 do 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. 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 |