Função MsiDeterminePatchSequenceA (msi.h)

Artigo
11/20/2024

A função MsiDeterminePatchSequence usa um conjunto de arquivos de patch, arquivos XML e blobs XML e determina a melhor sequência de aplicativos para os patches para um produto instalado especificado. Essa função contabiliza patches que já foram aplicados ao produto e contas para patches obsoletos e substituídos.

Sintaxe

UINT MsiDeterminePatchSequenceA(
  [in]           LPCSTR                 szProductCode,
  [in, optional] LPCSTR                 szUserSid,
  [in]           MSIINSTALLCONTEXT      dwContext,
  [in]           DWORD                  cPatchInfo,
  [in]           PMSIPATCHSEQUENCEINFOA pPatchInfo
);

Parâmetros

[in] szProductCode

O produto que é o destino para o conjunto de patches. O valor deve ser o ProductCode GUID do produto.

[in, optional] szUserSid

Cadeia de caracteres terminada em nulo que especifica um SID (identificador de segurança) de um usuário. Esse parâmetro restringe o contexto de enumeração para essa conta de usuário. Esse parâmetro não pode ser as cadeias de caracteres sid especiais "S-1-1-0" (todos) ou "S-1-5-18" (sistema local). Para o contexto do computador dwContext está definido como MSIINSTALLCONTEXT_MACHINE e szUserSid deve ser NULL. Para o contexto de usuário atual szUserSid pode ser nulo e dwContext pode ser definido como MSIINSTALLCONTEXT_USERMANAGED ou MSIINSTALLCONTEXT_USERUNMANAGED.

[in] dwContext

Restringe a enumeração a um contexto por usuário não gerenciado, por usuário ou por computador. Esse parâmetro pode ser qualquer um dos valores a seguir.

Tipo de contexto	Significado
MSIINSTALLCONTEXT_USERMANAGED	Os patches são considerados para todas as instalações gerenciadas por usuário do produto para o usuário especificado por szUserSid. Um szUserSid nulo com esse contexto significa o usuário atual.
MSIINSTALLCONTEXT_USERUNMANAGED	Os patches são considerados para todas as instalações não gerenciadas por usuário para o usuário especificado pelo szUserSid. Um szUserSid nulo com esse contexto significa o usuário atual.
MSIINSTALLCONTEXT_MACHINE	Os patches são considerados para a instalação por computador. Quando dwContext é definido como MSIINSTALLCONTEXT_MACHINE o parâmetro szUserSid deve ser nulo.

[in] cPatchInfo

O número de patches na matriz.

[in] pPatchInfo

Ponteiro para uma matriz de estruturas de MSIPATCHSEQUENCEINFO .

Valor de retorno

A função MsiDeterminePatchSequence retorna os valores a seguir.

Valor	Significado
ERROR_FUNCTION_FAILED	A função falhou de uma maneira não abordada nos outros códigos de erro.
ERROR_INVALID_PARAMETER	Um argumento é inválido.
ERROR_PATCH_NO_SEQUENCE	Nenhuma sequência válida foi encontrada para o conjunto de patches.
ERROR_INSTALL_PACKAGE_OPEN_FAILED	Não é possível abrir um pacote de instalação referenciado por caminho.
ERROR_SUCCESS	Os patches foram classificados com êxito.
ERROR_FILE_NOT_FOUND	O arquivo .msi não foi encontrado.
ERROR_PATH_NOT_FOUND	O caminho para o arquivo .msi não foi encontrado.
ERROR_INVALID_PATCH_XML	Os dados do patch XML são inválidos.
ERROR_INSTALL_PACKAGE_INVALID	O pacote de instalação era inválido.
ERROR_ACCESS_DENIED	Um usuário que não é um administrador tentou chamar a função com um contexto de um usuário diferente.
ERROR_BAD_CONFIGURATION	Os dados de configuração de um patch ou produto registrados são inválidos.
ERROR_UNKNOWN_PRODUCT	O ProductCode GUID especificado não está registrado.
ERROR_FUNCTION_NOT_CALLED	O Windows Installer versão 3.0 é necessário para determinar a melhor sequência de patch. A função foi chamada com szProductCode ainda não instalado com o Windows Installer versão 3.0.
ERROR_CALL_NOT_IMPLEMENTED	Esse erro poderá ser retornado se a função tiver sido chamada de uma ação personalizada ou se o MSXML 3.0 não estiver instalado.
ERROR_UNKNOWN_PATCH	O patch especificado é desconhecido.

Observações

Os usuários que não têm privilégios de administrador podem chamar essa função apenas em seu próprio contexto ou no computador. Os usuários que são administradores podem chamá-lo para outros usuários.

Se essa função for chamada de uma ação personalizada, ela falhará e retornará ERROR_CALL_NOT_IMPLEMENTED. A função requer MSXML versão 3.0 para processar XML e retorna ERROR_CALL_NOT_IMPLEMENTED se o MSXML 3.0 não estiver instalado.

A função MsiDeterminePatchSequence define a estrutura de uStatus e dwOrder de cada estrutura MSIPATCHSEQUENCEINFO apontada por pPatchInfo. Cada estrutura contém informações sobre um patch específico.

Se a função for bem-sucedida, a estrutura MSIPATCHSEQUENCEINFO de cada patch que pode ser aplicado ao produto retorna com um uStatus de ERROR_SUCCESS e um dwOrder maior ou igual a zero. Os valores de dwOrder maior ou igual a zero indicam a melhor sequência de aplicativos para os patches começando com zero.

Se a função for bem-sucedida, os patches excluídos da melhor sequência de aplicação de patch retornarão uma estrutura MSIPATCHSEQUENCEINFO com um dwOrder igual a -1. Nesses casos, um campo uStatus de ERROR_SUCCESS indica um patch obsoleto ou substituído para o produto. Um campo uStatus de ERROR_PATCH_TARGET_NOT_FOUND indica um patch inaplicaível ao produto.

Se a função falhar, a estrutura MSIPATCHSEQUENCEINFO para cada patch retornará um dwOrder igual a -1. Nesse caso, os campos uStatus podem conter erros com mais informações sobre patches individuais. Por exemplo, ERROR_PATCH_NO_SEQUENCE é retornado para patches que têm informações de sequenciamento circular.

Nota

O cabeçalho msi.h define MsiDeterminePatchSequence 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. Windows Installer 4.0 ou Windows Installer 4.5 no Windows Server 2008 ou Windows Vista. 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

Consulte também

MSIPATCHSEQUENCEINFO

MsiDetermineApplicablePatches

sem suporte no Windows Installer 2.0 e anteriores

ProductCode

Compartilhar via