Classe COleMessageFilter

Gerir a concorrência exigida pela interação das aplicações OLE.

Sintaxe

class COleMessageFilter : public CCmdTarget

Membros

Construtores Públicos

Métodos Públicos

Observações

A COleMessageFilter classe é útil em edição visual de servidores e aplicações de contentores, bem como em aplicações de automação OLE. Para aplicações servidor que estão a ser chamadas, esta classe pode ser usada para tornar a aplicação "ocupada", de modo a que as chamadas recebidas de outras aplicações contentores sejam canceladas ou retentadas mais tarde. Esta classe também pode ser usada para determinar a ação a realizar por uma aplicação chamada quando a aplicação chamada está ocupada.

O uso comum é que uma aplicação servidor chame BeginBusyState e EndBusyState quando seria perigoso que um documento ou outro objeto acessível OLE fosse destruído. Estas chamadas são feitas em CWinApp::OnIdle durante as atualizações da interface de utilizador.

Por defeito, um COleMessageFilter objeto é alocado quando a aplicação é inicializada. Pode ser recuperado com AfxOleGetMessageFilter.

Esta é uma disciplina avançada; raramente é preciso trabalhar diretamente com ela.

Para mais informações, consulte o artigo Servidores: Implementar um Servidor.

Hierarquia de herança

CObject

CCmdTarget

COleMessageFilter

Requerimentos

Cabeçalho: afxole.h

COleMessageFilter::BeginBusyState

Chame esta função para iniciar um estado ocupado.

virtual void BeginBusyState();

Observações

Funciona em conjunto com o EndBusyState para controlar o estado ocupado da aplicação. A função SetBusyReply determina a resposta da aplicação às aplicações a chamar quando está ocupada.

As BeginBusyState chamadas e EndBusyState incrementam e decrementam, respetivamente, um contador que determina se a aplicação está ocupada. Por exemplo, duas chamadas para BeginBusyState e uma chamada para EndBusyState continuar a resultar num estado ocupado. Para cancelar um estado ocupado, é necessário ligar EndBusyState o mesmo número de vezes BeginBusyState que foi chamado.

Por defeito, o framework entra no estado ocupado durante o processamento inativo, que é realizado pelo CWinApp::OnIdle. Enquanto a aplicação está a tratar de notificações ON_COMMANDUPDATEUI, as chamadas recebidas são tratadas mais tarde, após o processamento inativo estar concluído.

COleMessageFilter::COleMessageFilter

Cria um COleMessageFilter objeto.

COleMessageFilter();

COleMessageFilter::EnableBusyDialog

Ativa e desativa a caixa de diálogo ocupada, que é exibida quando o atraso da mensagem pendente expira (ver SetRetryReply) durante uma chamada OLE.

void EnableBusyDialog(BOOL bEnableBusy = TRUE);

Parâmetros

bEnableBusy
Especifica se a caixa de diálogo "ocupado" está ativada ou desativada.

COleMessageFilter::EnableNotRespondingDialog

Ativa e desativa a caixa de diálogo "não responde", que é exibida se uma mensagem de teclado ou rato estiver pendente durante uma chamada OLE e a chamada tiver expirado.

void EnableNotRespondingDialog(BOOL bEnableNotResponding = TRUE);

Parâmetros

bEncapacitNãoA Responder
Especifica se a caixa de diálogo "não responde" está ativada ou desativada.

COleMessageFilter::EndBusyState

Chama esta função para terminar um estado ocupado.

virtual void EndBusyState();

Observações

Funciona em conjunto com o BeginBusyState para controlar o estado ocupado da aplicação. A função SetBusyReply determina a resposta da aplicação às aplicações a chamar quando está ocupada.

As BeginBusyState chamadas e EndBusyState incrementam e decrementam, respetivamente, um contador que determina se a aplicação está ocupada. Por exemplo, duas chamadas para BeginBusyState e uma chamada para EndBusyState continuar a resultar num estado ocupado. Para cancelar um estado ocupado, é necessário ligar EndBusyState o mesmo número de vezes BeginBusyState que foi chamado.

Por defeito, o framework entra no estado ocupado durante o processamento inativo, que é realizado pelo CWinApp::OnIdle. Enquanto a aplicação está a tratar ON_UPDATE_COMMAND_UI notificações, as chamadas recebidas são tratadas após o processamento inativo estar concluído.

COleMessageFilter::OnMessagePending

Chamado pelo framework para processar mensagens enquanto uma chamada OLE está em curso.

virtual BOOL OnMessagePending(const MSG* pMsg);

Parâmetros

pMsg
Apontar para a mensagem pendente.

Valor de retorno

Não-zero em termos de sucesso; caso contrário, 0.

Observações

Quando uma aplicação que chama está à espera de uma chamada a ser concluída, o framework chama OnMessagePending com um ponteiro para a mensagem pendente. Por defeito, o framework despacha WM_PAINT mensagens, permitindo que atualizações de janelas ocorram durante uma chamada que demora muito tempo.

Deve registar o seu filtro de mensagens através de uma chamada para Registar antes de se tornar ativo.

COleMessageFilter::Registar

Regista o filtro de mensagens com as DLLs do sistema OLE.

BOOL Register();

Valor de retorno

Não-zero em termos de sucesso; caso contrário, 0.

Observações

Um filtro de mensagens não tem efeito a menos que esteja registado nas DLLs do sistema. Normalmente, o código de inicialização da sua aplicação regista o filtro de mensagens da aplicação. Qualquer outro filtro de mensagens registado pela sua candidatura deve ser revogado antes de o programa terminar, através de uma chamada para o Revoke.

O filtro de mensagens predefinido do framework é automaticamente registado durante a inicialização e revogado na terminação.

COleMessageFilter::Revoke

Revoga um registo anterior realizado através de uma chamada para Registo.

void Revoke();

Observações

Um filtro de mensagem deve ser revogado antes do programa terminar.

O filtro de mensagens predefinido, que é criado e registado automaticamente pelo framework, também é automaticamente revogado.

COleMessageFilter::SetBusyReply

Esta função define a "resposta ocupada" da aplicação.

void SetBusyReply(SERVERCALL nBusyReply);

Parâmetros

nBusyReply
Um valor da SERVERCALL enumeração, que está definido em COMPOBJ.H. Pode ter qualquer um dos seguintes valores:

• SERVERCALL_ISHANDLED A aplicação pode aceitar chamadas, mas pode falhar no processamento de uma chamada específica.

• SERVERCALL_REJECTED A candidatura provavelmente nunca conseguirá processar uma chamada.

• SERVERCALL_RETRYLATER A aplicação encontra-se temporariamente num estado em que não pode processar uma chamada.

Observações

As funções BeginBusyState e EndBusyState controlam o estado ocupado da aplicação.

Quando uma aplicação está ocupada com uma chamada para BeginBusyState, responde a chamadas das DLLs do sistema OLE com um valor determinado pela última definição de SetBusyReply. A aplicação que chama usa esta resposta ocupada para determinar que ação tomar.

Por defeito, a resposta ocupada é SERVERCALL_RETRYLATER. Esta resposta faz com que a aplicação que chama tente novamente a chamada o mais rapidamente possível.

FiltroMensagem::DefinirMensagemAtrasoPendenteAtraso

Determina quanto tempo a aplicação chamadora espera por uma resposta da aplicação chamada antes de tomar mais ação.

void SetMessagePendingDelay(DWORD nTimeout = 5000);

Parâmetros

nTimeout
Número de milissegundos para o atraso da mensagem pendente.

Observações

Esta função funciona em conjunto com o SetRetryReply.

COleMessageFilter::SetRetryReply

Determina a ação da aplicação chamadora quando recebe uma resposta ocupada de uma aplicação chamada.

void SetRetryReply(DWORD nRetryReply = 0);

Parâmetros

nRetryReply
Número de milissegundos entre tentativas.

Observações

Quando uma aplicação chamada indica que está ocupada, a aplicação chamada pode decidir esperar até que o servidor deixe de estar ocupado, tentar novamente imediatamente ou tentar novamente após um intervalo especificado. Também pode decidir cancelar a chamada por completo.

A resposta do chamador é controlada pelas funções SetRetryReply e pelo SetMessagePendingDelay. SetRetryReply determina quanto tempo a aplicação de chamada deve esperar entre tentativas para uma dada chamada. SetMessagePendingDelay determina quanto tempo a aplicação chamadora espera por uma resposta do servidor antes de tomar mais medidas.

Normalmente, os padrões são aceitáveis e não precisam de ser alterados. O framework tenta novamente a chamada a cada nRetryReply milissegundos até que a chamada seja concluída ou até o atraso da mensagem pendente expirar. Um valor de 0 para nRetryReply especifica uma retentativa imediata, e - 1 indica o cancelamento da chamada.

Quando o atraso de mensagem pendente expira, a OLE "caixa de diálogo ocupada" (ver COleBusyDialog) é exibida para que o utilizador possa escolher cancelar ou tentar novamente a chamada. Ligue para o EnableBusyDialog para ativar ou desativar esta caixa de diálogo.

Quando uma mensagem de teclado ou rato está pendente durante uma chamada e esta terminou o tempo de espera (excedeu o atraso de mensagem pendente), é exibida a caixa de diálogo "não responde". Ligue para o EnableNotRespondingDialog para ativar ou desativar esta caixa de diálogo. Normalmente, esta situação indica que algo correu mal e que o utilizador está a ficar impaciente.

Quando os diálogos estão desativados, a atual "resposta de tentativa" é sempre usada para chamadas a aplicações ocupadas.

Consulte também

Classe CCmdTarget
Gráfico de Hierarquia
Classe CCmdTarget