Função MsiEnumClientsExA (msi.h)
A função MsiEnumClientsEx enumera os aplicativos instalados que usam um componente especificado. A função recupera um código de produto para um aplicativo sempre que ele é chamado.
Windows Installer 4.5 ou anterior: Sem suporte. Essa função está disponível a partir do Windows Installer 5.0.
Sintaxe
UINT MsiEnumClientsExA(
[in] LPCSTR szComponent,
[in, optional] LPCSTR szUserSid,
[in] DWORD dwContext,
[in] DWORD dwProductIndex,
[out, optional] CHAR [39] szProductBuf,
[out, optional] MSIINSTALLCONTEXT *pdwInstalledContext,
[out, optional] LPSTR szSid,
[in, out, optional] LPDWORD pcchSid
);
Parâmetros
[in] szComponent
O GUID do código do componente que identifica o componente. A função enumera os aplicativos que usam esse componente.
[in, optional] szUserSid
Um valor de cadeia de caracteres terminada em nulo que contém um SID (identificador de segurança). A enumeração de aplicativos se estende aos usuários identificados por esse SID. A cadeia de caracteres sid especial s-1-1-0 (Todos) enumera todos os aplicativos para todos os usuários no sistema. Um valor sid diferente de s-1-1-0 especifica um SID de usuário para um usuário específico e enumera as instâncias de aplicativos instalados pelo usuário especificado.
[in] dwContext
Um sinalizador que estende a enumeração para instâncias de aplicativos instalados no contexto de instalação especificado. A enumeração inclui apenas instâncias de aplicativos instalados pelos usuários identificados por szUserSid.
Isso pode ser uma combinação dos valores a seguir.
[in] dwProductIndex
Especifica o índice do aplicativo a ser recuperado. O valor desse parâmetro deve ser zero (0) na primeira chamada para a função. 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.
[out, optional] szProductBuf
Um valor de cadeia de caracteres que recebe o código do produto para o aplicativo. 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 código do produto. 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 o contexto de instalação do aplicativo.
Isso pode ser uma combinação dos valores a seguir.
[out, optional] szSid
Recebe o SID (identificador de segurança) que identifica o usuário que instalou o aplicativo. O local receberá um valor de cadeia de caracteres vazio se essa instância do aplicativo existir em um contexto de instalação por computador.
O comprimento do buffer 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 for 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, sem incluir 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 do usuário que instalou o produto. |
[in, out, optional] pcchSid
Ponteiro para um local na memória que contém uma variável que especifica o número de TCHAR no SID, não incluindo 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 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 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 de SID.
Valor retornado
A função MsiEnumClientsEx retorna um dos valores a seguir.
| Código de retorno | Descrição |
|---|---|
|
Os privilégios do 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 aplicativos para enumerar. |
|
A função foi bem-sucedida. |
|
O buffer fornecido era muito pequeno para conter todo o valor. |
|
A função falhou. |
Comentários
Observação
O cabeçalho msi.h define MsiEnumClientsEx 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
| 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 |