Compartilhar via


Função MsiProcessMessage (msiquery.h)

A função MsiProcessMessage envia um registro de erro para o instalador para processamento.

Sintaxe

int MsiProcessMessage(
  [in] MSIHANDLE      hInstall,
  [in] INSTALLMESSAGE eMessageType,
  [in] MSIHANDLE      hRecord
);

Parâmetros

[in] hInstall

Manipule para a instalação fornecida a uma ação personalizada de DLL ou obtida por meio de MsiOpenPackage, MsiOpenPackageEx ou MsiOpenProduct.

[in] eMessageType

O parâmetro eMessage deve ser um valor que especifique um dos seguintes tipos de mensagem. Para exibir uma caixa de mensagem com botões ou ícones, use operadores OR para adicionar INSTALLMESSAGE_ERROR, INSTALLMESSAGE_WARNING ou INSTALLMESSAGE_USER aos estilos de caixa de mensagem padrão usados pelas funções MessageBox e MessageBoxEx . Para obter mais informações, consulte os Comentários abaixo.

Valor Significado
INSTALLMESSAGE_FATALEXIT
Término prematuro, possivelmente de memória insuficiente fatal.
INSTALLMESSAGE_ERROR
Mensagem de erro formatada,
 
[1] é o número da mensagem na tabela Erro.
INSTALLMESSAGE_WARNING
Mensagem de aviso formatada,
 
[1] é o número da mensagem na tabela Erro.
INSTALLMESSAGE_USER
Mensagem de solicitação do usuário,
 
[1] é o número da mensagem na tabela Erro.
INSTALLMESSAGE_INFO
Mensagem informativa para log,
 
não a ser exibido.
INSTALLMESSAGE_FILESINUSE
Lista de arquivos atualmente em uso que devem ser fechados antes de serem substituídos.
INSTALLMESSAGE_RESOLVESOURCE
Solicitação para determinar um local de origem válido.
INSTALLMESSAGE_RMFILESINUSE
Lista de arquivos atualmente em uso que devem ser fechados antes de serem substituídos. Disponível a partir do Windows Installer versão 4.0. Para obter mais informações sobre essa mensagem, consulte Usar o gerenciador de reinicialização com uma interface do usuário externa.
INSTALLMESSAGE_OUTOFDISKSPACE
Mensagem de espaço insuficiente em disco.
INSTALLMESSAGE_ACTIONSTART
Progresso: início da ação,
 
[1] nome da ação,
 
[2] descrição,
 
[3] modelo para mensagens ACTIONDATA.
INSTALLMESSAGE_ACTIONDATA
Dados de ação. Os campos de registro correspondem ao modelo da mensagem ACTIONSTART.
INSTALLMESSAGE_PROGRESS
Informações da barra de progresso. Confira a descrição dos campos de registro abaixo.
INSTALLMESSAGE_COMMONDATA
Para habilitar o botão Cancelar, defina [1] como 2 e [2] como 1.

Para desabilitar o botão Cancelar, defina [1] como 2 e [2] como 0

[in] hRecord

Manipule para um registro que contém o formato e os dados da mensagem.

Retornar valor

Essa função retorna int.

Comentários

A função MsiProcessMessage executa todas as operações de log habilitadas e adia a execução. Você pode habilitar seletivamente o registro em log para vários tipos de mensagens.

Para mensagens INSTALLMESSAGE_FATALEXIT, INSTALLMESSAGE_ERROR, INSTALLMESSAGE_WARNING e INSTALLMESSAGE_USER, se o campo 0 não estiver definido, o campo 1 deverá ser definido como o código de erro correspondente à mensagem de erro na tabela Erro. Em seguida, a mensagem é formatada usando o modelo da tabela Error antes de passá-la para o manipulador de interface do usuário para exibição.

Campos de registro para mensagens da barra de progresso

A seguir, descreve os campos de registro quando eMessageType é definido como INSTALLMESSAGE_PROGRESS. O campo 1 especifica o tipo da mensagem de progresso. O significado dos outros campos depende do valor neste campo. Os valores possíveis que podem ser definidos no Campo 1 são os seguintes.
Valor do campo 1 Descrição do campo 1
0 Redefine a barra de progresso e define o número total esperado de tiques na barra.
1 Fornece informações relacionadas às mensagens de progresso a serem enviadas pela ação atual.
2 Incrementa a barra de progresso.
3 Permite que uma ação (como CustomAction) adicione tiques ao número total esperado de progresso da barra de progresso.
 

O significado do Campo 2 depende do valor no Campo 1 da seguinte maneira.

Valor do campo 1 Descrição do campo 2
0 Número total esperado de tiques na barra de progresso.
1 Número de tiques que a barra de progresso move para cada mensagem ActionData enviada pela ação atual. Esse campo será ignorado se o Campo 3 for 0.
2 Número de tiques que a barra de progresso moveu.
3 Número de tiques a serem adicionados ao progresso total esperado.
 

O significado do Campo 3 depende do valor no Campo 1 da seguinte maneira.

Valor do campo 1 Valor do campo 3 Descrição do campo 3
0 0 Barra de progresso Avançar (da esquerda para a direita)
  1 Barra de progresso Voltar (da direita para a esquerda)
1 0 A ação atual enviará mensagens ProgressReport explícitas.
  1 Incremente a barra de progresso pelo número de tiques especificados no Campo 2 sempre que uma mensagem ActionData for enviada pela ação atual.
2 Não usado  
3 Não usado  
 

O significado do Campo 4 depende do valor no Campo 1 da seguinte maneira.

Valor do campo 1 Valor do campo 4 Descrição do campo 4
0 0 A execução está em andamento. Nesse caso, a interface do usuário pode calcular e exibir o tempo restante.
  1 Criando o script de execução. Nesse caso, a interface do usuário pode exibir uma mensagem para aguardar enquanto o instalador termina de preparar a instalação.
1 Não usado  
2 Não usado  
3 Não usado  
 

Para obter mais informações e um exemplo de código, consulte Adicionando ações personalizadas ao ProgressBar.

Exibição de caixas de mensagem

Para exibir uma caixa de mensagem com botões ou ícones, use operadores OR para adicionar INSTALLMESSAGE_ERROR, INSTALLMESSAGE_WARNING ou INSTALLMESSAGE_USER com as opções de caixa de mensagem usadas por MessageBox e MessageBoxEx. As opções de botão de ação disponíveis são MB_OK, MB_OKCANCEL, MB_ABORTRETRYIGNORE, MB_YESNOCANCEL, MB_YESNO e MB_RETRYCANCEL. As opções de botão padrão disponíveis são MB_DEFBUTTON1, MB_DEFBUTTON2 e MB_DEFBUTTON3. As opções de ícone disponíveis são MB_ICONERROR, MB_ICONQUESTION, MB_ICONWARNING e MB_ICONINFORMATION. Se nenhuma opção de ícone for especificada, o Windows Installer escolherá um estilo de ícone padrão com base no tipo de mensagem.

Por exemplo, a chamada a seguir para MsiProcessMessage envia uma mensagem INSTALLMESSAGE_ERROR com o ícone MB_ICONWARNING e os botões MB_ABORTRETRYCANCEL.

PMSIHANDLE hInstall;
PMSIHANDLE hRec;
MsiProcessMessage(hInstall, 
                  INSTALLMESSAGE(INSTALLMESSAGE_ERROR|MB_ABORTRETRYIGNORE|MB_ICONWARNING),
                  hRec);

Se uma ação personalizada chamar MsiProcessMessage, a ação personalizada deverá ser capaz de lidar com um cancelamento pelo usuário e deve retornar ERROR_INSTALL_USEREXIT.

Para obter mais informações sobre como enviar mensagens com MsiProcessMessage, consulte o Envio de mensagens para o Windows Installer usando MsiProcessMessage.

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. Windows Installer no Windows Server 2003 ou no Windows XP
Plataforma de Destino Windows
Cabeçalho msiquery.h
Biblioteca Msi.lib
DLL Msi.dll

Confira também

Funções de ação do instalador

Como enviar mensagens para o Windows Installer usando MsiProcessMessage