Compartilhar via


Função MsiEnumPatchesExA (msi.h)

A função MsiEnumPatchesEx enumera todos os patches em um contexto específico ou em todos os contextos. Os patches já aplicados aos produtos são enumerados. Os patches que foram registrados, mas ainda não aplicados aos produtos, também são enumerados.

Sintaxe

UINT MsiEnumPatchesExA(
  [in, optional]      LPCSTR            szProductCode,
  [in, optional]      LPCSTR            szUserSid,
  [in]                DWORD             dwContext,
  [in]                DWORD             dwFilter,
  [in]                DWORD             dwIndex,
  [out, optional]     CHAR [39]         szPatchCode,
  [out, optional]     CHAR [39]         szTargetProductCode,
  [out, optional]     MSIINSTALLCONTEXT *pdwTargetProductContext,
  [out, optional]     LPSTR             szTargetUserSid,
  [in, out, optional] LPDWORD           pcchTargetUserSid
);

Parâmetros

[in, optional] szProductCode

Uma cadeia de caracteres terminada em nulo que especifica o GUID productCode do produto cujos patches são enumerados. Se não for NULL, a enumeração de patch será restrita a instâncias deste produto no usuário e no contexto especificado por szUserSid e dwContext. Se FOR NULL, os patches de todos os produtos no contexto especificado serão enumerados.

[in, optional] szUserSid

Uma 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 a esse usuário. Ao enumerar para um usuário diferente do usuário atual, todos os patches aplicados em um contexto por usuário não gerenciado usando uma versão menor que o Windows Installer versão 3.0 não são enumerados. Esse parâmetro pode ser definido como NULL para especificar o usuário atual.

Tipo de SID Significado
NULO
Especifica o usuário conectado no momento.
SID de usuário
Uma enumeração para um usuário específico no sistema. Um exemplo de SID do usuário é "S-1-3-64-2415071341-1358098788-3127455600-2561".
s-1-1-0
Uma enumeração entre todos os usuários no sistema.
 
Nota A cadeia de caracteres sid especial "S-1-5-18" (Sistema) não pode ser usada para enumerar produtos ou patches instalados como por computador. Definir o valor sid como "S-1-5-18" retorna ERROR_INVALID_PARAMETER. Quando dwContext é definido como somente MSIINSTALLCONTEXT_MACHINE , szUserSid deve ser NULL.
 

[in] dwContext

Restringe a enumeração a um ou a uma combinação de contextos. Esse parâmetro pode ser qualquer um ou uma combinação dos valores a seguir.

Contexto Significado
MSIINSTALLCONTEXT_USERMANAGED
A enumeração estendida para 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
Nesse contexto, somente os patches instalados com o Windows Installer versão 3.0 são enumerados para usuários que não são o usuário atual. Para o usuário atual, a função enumera todos os patches instalados e novos. Um SID inválido para szUserSid não retorna itens.
MSIINSTALLCONTEXT_MACHINE
Uma enumeração estendida para todas as instalações por computador. Quando dwContext é definido como somente MSIINSTALLCONTEXT_MACHINE , o parâmetro szUserSid deve ser NULL.

[in] dwFilter

O filtro para enumeração. Esse parâmetro pode ser uma ou uma combinação dos parâmetros a seguir.

Filtrar Significado
MSIPATCHSTATE_APPLIED
1
A enumeração inclui patches que foram aplicados. A enumeração não inclui patches substituídos ou obsoletos.
MSIPATCHSTATE_SUPERSEDED
2
A enumeração inclui patches marcados como substituídos.
MSIPATCHSTATE_OBSOLETED
4
A enumeração inclui patches marcados como obsoletos.
MSIPATCHSTATE_REGISTERED
8
A enumeração inclui patches registrados, mas ainda não aplicados. A função MsiSourceListAddSourceEx pode registrar novos patches.
Nota Os patches registrados para usuários diferentes do usuário atual e aplicados no contexto por usuário não gerenciado não são enumerados.
 
MSIPATCHSTATE_ALL
15
A enumeração inclui todos os patches aplicados, obsoletos, substituídos e registrados.

[in] dwIndex

O índice do patch a ser recuperado. Esse parâmetro deve ser zero para a primeira chamada para a função MsiEnumPatchesEx e, em seguida, incrementado para chamadas subsequentes. O parâmetro dwIndex só deverá ser incrementado se a chamada anterior retornar ERROR_SUCCESS.

[out, optional] szPatchCode

Um buffer de saída para conter o GUID do patch que está sendo enumerado. O buffer deve ser grande o suficiente para manter o GUID. Este parâmetro pode ser NULL.

[out, optional] szTargetProductCode

Um buffer de saída para conter o GUID productCode do produto que recebe esse patch. O buffer deve ser grande o suficiente para manter o GUID. Este parâmetro pode ser NULL.

[out, optional] pdwTargetProductContext

Retorna o contexto do patch que está sendo enumerado. O valor de saída pode ser MSIINSTALLCONTEXT_USERMANAGED, MSIINSTALLCONTEXT_USERUNMANAGED ou MSIINSTALLCONTEXT_MACHINE. Este parâmetro pode ser NULL.

[out, optional] szTargetUserSid

Um buffer de saída que recebe o SID da cadeia de caracteres da conta na qual essa instância de patch existe. Esse buffer retorna uma cadeia de caracteres vazia para 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á *pcchTargetUserSid como o número de TCHAR no valor, sem incluir o caractere NULL de terminação.

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

Se szTargetUserSid e pcchTargetUserSid estiverem definidos como NULL, a função retornará ERROR_SUCCESS se o valor existir, sem recuperar o valor.

[in, out, optional] pcchTargetUserSid

Um ponteiro para uma variável que especifica o número de TCHAR no buffer szTargetUserSid . 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 szTargetUserSid também for NULL; caso contrário, a função retornará ERROR_INVALID_PARAMETER.

Retornar valor

A função MsiEnumPatchesEx retorna um dos valores a seguir.

Código de retorno Descrição
ERROR_ACCESS_DENIED
A função falha ao tentar acessar um recurso com privilégios insuficientes.
ERROR_BAD_CONFIGURATION
Os dados de configuração estão corrompidos.
ERROR_INVALID_PARAMETER
Um parâmetro inválido é passado para a função .
ERROR_NO_MORE_ITEMS
Não há mais patches para enumerar.
ERROR_SUCCESS
O patch é enumerado com êxito.
ERROR_UNKNOWN_PRODUCT
O produto que szProduct especifica não está instalado no computador nos contextos especificados.
ERROR_MORE_DATA
Isso é retornado quando pcchTargetUserSid aponta para um tamanho de buffer menor do que o necessário para copiar o SID. Nesse caso, o usuário pode corrigir o buffer e chamar MsiEnumPatchesEx novamente para o mesmo valor de índice.

Comentários

Os não administradores podem enumerar patches somente em sua visibilidade. Os administradores podem enumerar patches para outros contextos de usuário.

Observação

O cabeçalho msi.h define MsiEnumPatchesEx 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. Confira os Requisitos de tempo de execução do Windows Installer para obter informações sobre o Windows service pack mínimo 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

Contexto de instalação

MsiSourceListAddSourceEx

Sem suporte no Windows Installer 2.0 e nas versões anteriores

ProductCode