Como enviar mensagens para o Windows Installer usando MsiProcessMessage

  • Artigo

As mensagens enviadas usando MsiProcessMessage são as mesmas mensagens recebidas pela função de retorno de chamada INSTALLUI\_HANDLER quando MsiSetExternalUI é chamado. Caso contrário, o Windows Installer manipula as mensagens. Para obter detalhes, confira Análise de mensagens do Windows Installer.

Por exemplo, para enviar uma mensagem INSTALLMESSAGE_ERROR com o ícone de MB_ICONWARNING e os botões MB_ABORTRETRYCANCEL:

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

Onde hInstall é o identificador para a instalação fornecido a uma ação personalizada ou o identificador hProduct de MsiOpenProduct ou MsiOpenPackage, e hRec é o registro que contém as informações de erro a serem formatadas. Para obter informações sobre como a formatação é executada, confira MsiFormatRecord.

Por padrão, se uma mensagem INSTALLMESSAGE_ERROR ou INSTALLMESSAGE_FATALEXIT for enviada sem especificar tipos de ícone ou tipo de botão, MB_OK, nenhum ícone e MB_DEFBUTTON1 serão usados.

O Windows Installer não rotula o botão ABORT com a cadeia de caracteres "Abortar" ao exibir uma MessageBox com a especificação do botão MB_ABORTRETRYIGNORE; em vez disso, ele rotula o botão com a cadeia de caracteres "Cancelar". Todas as mensagens de erro se abstêm de usar a palavra "Anular" e, em vez disso, usam a palavra "Cancelar".

O parâmetro hRecord da função MsiProcessMessage depende do tipo de mensagem enviado ao MsiProcessMessage. A lista abaixo detalha os requisitos do registro em relação ao tipo de mensagem:

INSTALLMESSAGE_FATALEXIT

 

INSTALLMESSAGE_INFO

 

INSTALLMESSAGE_OUTOFDISKSPACE

Campo Descrição
0 Modelo para a formatação da cadeia de caracteres resultante. Confira MsiFormatRecord para obter mais informações. Os campos do registro são referenciados usando [1] para o campo 1, [2] para o campo 2, etc.
1 a n Todos os campos subsequentes estão diretamente relacionados aos campos referenciados pelo modelo no campo 0.

 

Se o campo 0 for nulo, a cadeia de caracteres recebida pelo manipulador de interface do usuário será formatada como: 1: [dados do campo 1] 2: [dados do campo 2] o que significa que, para cada campo do registro, a cadeia de caracteres contém o número do campo seguido pelos dados armazenados no campo.

As mensagens de informações de MsiProcessMessage são registradas quando MsiEnableLog, a opção de linha de comando '/l' ou a política de log especificam 'I' ou INSTALLLOGMODE_INFO.

INSTALLMESSAGE_ERROR

 

INSTALLMESSAGE_WARNING

 

INSTALLMESSAGE_USER

Para usar uma mensagem da tabela Error.

Campo Descrição
0 Precisa ser NULL.
1 Número da mensagem na tabela Error.
2 a n Relacionado à mensagem especificada na tabela Error.

 

Por exemplo.

Campo Type Dados
0 string nulo
1 INT 1304
2 string Myfile.txt

 

A mensagem resultante recebida do manipulador de interface do usuário é:

Error 1304. Erro ao gravar no arquivo: Myfile.txt. Verifique se você tem acesso a esse diretório.

Se o campo 0 não for nulo, a mensagem da tabela de erros será substituída. Em vez disso, o modelo de campo 0 determina o formato da mensagem.

A mensagem também pode especificar os botões, incluindo o botão padrão, e o ícone para uso com a mensagem, conforme mencionado acima. Os tipos de botão e ícone são listados em INSTALLUI_HANDLER.

INSTALLMESSAGE_COMMONDATA

Esta mensagem é enviada para habilitar ou desabilitar o botão Cancelar em uma caixa de diálogo em andamento.

Campo Descrição
0 Não utilizado.
1 2 refere-se ao botão Cancelar.
2 Um valor de 1 indica que o botão Cancelar deve estar visível. Um valor de 0 indica que o botão Cancelar deve estar invisível.

 

Por exemplo, para desabilitar ou ocultar o botão Cancelar, o registro seria exibido desta maneira.

Campo Type Dados
0 string nulo
1 INT 2
2 INT 0

 

INSTALLMESSAGE_ACTIONSTART

 

INSTALLMESSAGE_ACTIONDATA

O registro INSTALLMESSAGE_ACTIONSTART determina o formato do registro ActionData.

Campo Descrição
0 nulo
1 Nome da ação. O nome nesse campo precisa ser não nulo.
2 Descrição da ação.
3 Modelo de ação. Isso é usado no ActionData cuja mensagem está sendo formatada de acordo com esse modelo.

 

Não faça referência ao campo 0 na mensagem Modelo de ação.

O registro INSTALLMESSAGE_ACTIONDATA é formatado desta maneira.

Campo Descrição
0 nulo
1 a n Dependente do campo 3 da mensagem INSTALLMESSAGE_ACTIONSTART correspondente ou do modelo especificado na tabela ActionText.

 

Por exemplo, o registro INSTALLMESSAGE_ACTIONSTART.

Campo Type Dados
0 string nulo
1 string MyAction
2 string Esta é a descrição de "MyAction"
3 string Modelo myAction: dados field1 são [1]. Os dados do campo 2 são [2].

 

O modelo para INSTALLMESSAGE_ACTIONSTART (campo 3) faz referência aos campos 1 e 2, o registro INSTALLMESSAGE_ACTIONDATA deve ter dois campos contendo os dados garantidos. Os campos podem ser cadeia de caracteres ou campos inteiros.

Registro INSTALLMESSAGE_ACTIONDATA.

Campo Type Dados
0 string nulo
1 INT 2
2 string ActionData para MyAction

 

INSTALLMESSAGE_FILESINUSE

O registro FILESINUSE é um registro de tamanho variável.

Campo Descrição
0 Este campo pode ser nulo. Para uma instalação que usa uma interface do usuário básica, esse campo pode especificar texto estático para exibição no controle ListBox do diálogo FilesInUse. Para uma instalação que usa uma interface do usuário completa, esse campo não tem efeito porque o texto é especificado pela criação da caixa de diálogo FilesInUse personalizada.
1 Nome do arquivo em uso.
2 Esse campo identifica o processo que mantém o arquivo em uso. Windows Installer versão 4.0: a ID do processo (PID) do processo ou o título da janela para o processo.
Windows Installer versão 3.1 e anterior: esse campo deve ser a ID do processo (PID).

 

Por exemplo, para enviar uma mensagem FilesInUse mostrando dois arquivos em uso, red.exe e blue.exe, o registro tem quatro campos mais o campo 0. O formato do registro seria conforme mostrado na tabela a seguir. Este exemplo requer o Windows Installer versão 4.0.

Windows Installer versão 3.1 e anterior: os campos 2 e 4 no exemplo a seguir precisam conter as PIDs dos processos que mantêm red.exe e blue.exe em uso.

Campo Descrição
0 nulo
1 Red.exe
2 Título da Janela Vermelha
3 Blue.exe
4 Título da Janela Azul

 

Observação

No Windows Installer versão 4.0, se a PID transmitida do serviço não tiver um título de janela, como um aplicativo de bandeja do sistema, o arquivo não será exibido e o log detalhado conterá as mensagens a seguir.

 

File In Use: -<FileName>- Window could not be found. Process ID: <PID>
No window with title could be found for FilesInUse

INSTALLMESSAGE_RESOLVESOURCE

O registro INSTALLMESSAGE_RESOLVESOURCE tem sete campos. Para INSTALLMESSAGE_RESOLVESOURCE funcionar corretamente, um manipulador de interface do usuário externo poderá não lidar com a mensagem INSTALLMESSAGE_RESOLVESOURCE. O Windows Installer precisa lidar com a mensagem de INSTALLMESSAGE_RESOLVESOURCE. Ou seja, o manipulador de interface do usuário externo retorna 0 para indicar "nenhuma ação tomada" ao filtrar a mensagem INSTALLMESSAGE_RESOLVESOURCE. A melhor prática é evitar o envio de uma mensagem RESOLVESOURCE.

Campo Descrição
0 nulo
1 null
2 Nome do pacote.
3 Código do Produto.
4 O caminho relativo, se conhecido, pode ser nulo.
5 0
6 Se deseja validar ou não o código do pacote. Um valor de '1' indica que o código do pacote deve ser validado. Um valor de '0' indica que o pacote não deve ser validado.
7 Disco necessário da tabela de mídia. Um valor de '0' indica que qualquer disco é aceitável.