Compartilhar via


Classe COleMessageFilter

Gerencia a simultaneidade exigida pela interação de aplicativos OLE.

Sintaxe

class COleMessageFilter : public CCmdTarget

Membros

Construtores públicos

Nome Descrição
COleMessageFilter::COleMessageFilter Constrói um objeto COleMessageFilter.

Métodos públicos

Nome Descrição
COleMessageFilter::BeginBusyState Coloca o aplicativo no estado ocupado.
COleMessageFilter::EnableBusyDialog Habilita e desabilita a caixa de diálogo exibida quando um aplicativo chamado está ocupado.
COleMessageFilter::EnableNotRespondingDialog Habilita e desabilita a caixa de diálogo exibida quando um aplicativo chamado não está respondendo.
COleMessageFilter::EndBusyState Encerra o estado ocupado do aplicativo.
COleMessageFilter::OnMessagePending Chamado pela estrutura para processar mensagens enquanto uma chamada OLE está em andamento.
COleMessageFilter::Register Registra o filtro de mensagem com as DLLs do sistema OLE.
COleMessageFilter::Revoke Revoga o registro do filtro de mensagem com as DLLs do sistema OLE.
COleMessageFilter::SetBusyReply Determina a resposta do aplicativo ocupado a uma chamada OLE.
COleMessageFilter::SetMessagePendingDelay Determina por quanto tempo o aplicativo aguarda uma resposta a uma chamada OLE.
COleMessageFilter::SetRetryReply Determina a resposta do aplicativo autor da chamada a um aplicativo ocupado.

Comentários

A classe COleMessageFilter é útil em aplicativos de contêiner e servidor de edição visual, bem como em aplicativos de automação OLE. Para aplicativos de servidor que estão sendo chamados, essa classe pode ser usada para tornar o aplicativo "ocupado", de modo que chamadas recebidas de outros aplicativos de contêiner sejam canceladas ou repetidas posteriormente. Essa classe também pode ser usada para determinar a ação a ser adotada por um aplicativo autor da chamada quando o aplicativo chamado está ocupado.

O uso comum é um aplicativo de servidor chamar BeginBusyState e EndBusyState quando seria perigoso que um documento ou outro objeto acessível de OLE fosse destruído. Essas chamadas são feitas em CWinApp::OnIdle durante atualizações da interface do usuário.

Por padrão, um objeto COleMessageFilter é alocado quando o aplicativo é inicializado. Ele pode ser recuperado com AfxOleGetMessageFilter.

Esta é uma classe avançada, com a qual você raramente precisa trabalhar diretamente.

Para obter mais informações, confira o artigo Servidores: implementando um servidor.

Hierarquia de herança

CObject

CCmdTarget

COleMessageFilter

Requisitos

Cabeçalho: afxole.h

COleMessageFilter::BeginBusyState

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

virtual void BeginBusyState();

Comentários

Ele funciona em conjunto com EndBusyState para controlar o estado ocupado do aplicativo. A função SetBusyReply determina a resposta do aplicativo aos aplicativos autores das chamadas quando ele está ocupado.

As chamadas BeginBusyState e EndBusyState incrementam e decrementam, respectivamente, um contador que determina se o aplicativo está ocupado. Por exemplo, duas chamadas para BeginBusyState e uma chamada para EndBusyState ainda resultam em um estado ocupado. Para cancelar um estado ocupado, é necessário chamar EndBusyState o mesmo número de vezes que BeginBusyState foi chamado.

Por padrão, a estrutura entra no estado ocupado durante o processamento ocioso, que é executado por CWinApp::OnIdle. Enquanto o aplicativo está tratando notificações de ON_COMMANDUPDATEUI, as chamadas de entrada são tratadas posteriormente, após o processamento ocioso ser concluído.

COleMessageFilter::COleMessageFilter

Cria um objeto COleMessageFilter.

COleMessageFilter();

COleMessageFilter::EnableBusyDialog

Habilita e desabilita a caixa de diálogo ocupada, que é exibida quando o atraso de mensagem pendente expira (consulte SetRetryReply) durante uma chamada de OLE.

void EnableBusyDialog(BOOL bEnableBusy = TRUE);

Parâmetros

bEnableBusy
Especifica se a caixa de diálogo "ocupado" é habilitada ou desabilitada.

COleMessageFilter::EnableNotRespondingDialog

Habilita e desabilita a caixa de diálogo "não respondendo", que é exibida quando uma mensagem de teclado ou mouse está pendente durante uma chamada de OLE e a chamada atinge o tempo limite.

void EnableNotRespondingDialog(BOOL bEnableNotResponding = TRUE);

Parâmetros

bEnableNotResponding
Especifica se a caixa de diálogo "não respondendo" é habilitada ou desabilitada.

COleMessageFilter::EndBusyState

Chame essa função para encerrar um estado ocupado.

virtual void EndBusyState();

Comentários

Ele funciona em conjunto com BeginBusyState para controlar o estado ocupado do aplicativo. A função SetBusyReply determina a resposta do aplicativo aos aplicativos autores das chamadas quando ele está ocupado.

As chamadas BeginBusyState e EndBusyState incrementam e decrementam, respectivamente, um contador que determina se o aplicativo está ocupado. Por exemplo, duas chamadas para BeginBusyState e uma chamada para EndBusyState ainda resultam em um estado ocupado. Para cancelar um estado ocupado, é necessário chamar EndBusyState o mesmo número de vezes que BeginBusyState foi chamado.

Por padrão, a estrutura entra no estado ocupado durante o processamento ocioso, que é executado por CWinApp::OnIdle. Enquanto o aplicativo está tratando notificações de ON_UPDATE_COMMAND_UI, as chamadas de entrada são tratadas após o processamento ocioso ser concluído.

COleMessageFilter::OnMessagePending

Chamado pela estrutura para processar mensagens enquanto uma chamada OLE está em andamento.

virtual BOOL OnMessagePending(const MSG* pMsg);

Parâmetros

pMsg
Ponteiro para a mensagem pendente.

Valor de retorno

Diferente de zero em caso de êxito. Caso contrário, 0.

Comentários

Quando um aplicativo autor da chamada está aguardando a conclusão de uma chamada, a estrutura chama OnMessagePending com um ponteiro para a mensagem pendente. Por padrão, a estrutura expede mensagens WM_PAINT, de modo que atualizações de janela possam ocorrer durante uma chamada que está demorando muito.

Você precisa registrar seu filtro de mensagem por meio de uma chamada para Register antes que ele possa ficar ativo.

COleMessageFilter::Register

Registra o filtro de mensagem com as DLLs do sistema OLE.

BOOL Register();

Valor de retorno

Diferente de zero em caso de êxito. Caso contrário, 0.

Comentários

Um filtro de mensagem não tem efeito a menos que seja registrado nas DLLs do sistema. Normalmente, o código de inicialização do aplicativo registra o filtro de mensagem do aplicativo. Qualquer outro filtro de mensagem registrado pelo aplicativo deve ser revogado antes que o programa seja encerrado com uma chamada para Revoke.

O filtro de mensagem padrão da estrutura é registrado automaticamente durante a inicialização e revogado no encerramento.

COleMessageFilter::Revoke

Revoga um registro anterior executado por uma chamada para Register.

void Revoke();

Comentários

Um filtro de mensagem deve ser revogado antes que o programa seja encerrado.

O filtro de mensagem padrão, que é criado e registrado automaticamente pela estrutura, também é revogado automaticamente.

COleMessageFilter::SetBusyReply

Essa função define a "resposta ocupada" do aplicativo.

void SetBusyReply(SERVERCALL nBusyReply);

Parâmetros

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

  • SERVERCALL_ISHANDLED O aplicativo pode aceitar chamadas, mas pode falhar ao processar uma chamada específica.

  • SERVERCALL_REJECTED O aplicativo provavelmente nunca será capaz de processar uma chamada.

  • SERVERCALL_RETRYLATER O aplicativo está temporariamente em um estado no qual não pode processar uma chamada.

Comentários

As funções BeginBusyState e EndBusyState controlam o estado ocupado do aplicativo.

Quando um aplicativo é ocupado por uma chamada para BeginBusyState, ele responde a chamadas das DLLs do sistema OLE com um valor determinado pela última configuração de SetBusyReply. O aplicativo autor da chamada usa essa resposta ocupada para determinar qual ação deve ser tomada.

Por padrão, a resposta ocupada é SERVERCALL_RETRYLATER. Essa resposta faz com que o aplicativo autor da chamada repita a chamada assim que possível.

COleMessageFilter::SetMessagePendingDelay

Determina por quanto tempo o aplicativo autor da chamada aguarda uma resposta do aplicativo chamado antes de tomar medidas adicionais.

void SetMessagePendingDelay(DWORD nTimeout = 5000);

Parâmetros

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

Comentários

Essa função funciona em conjunto com SetRetryReply.

COleMessageFilter::SetRetryReply

Determina a ação do aplicativo autor da chamada quando ele recebe uma resposta ocupada de um aplicativo chamado.

void SetRetryReply(DWORD nRetryReply = 0);

Parâmetros

nRetryReply
Número de milissegundos entre repetições.

Comentários

Quando um aplicativo chamado indica que está ocupado, o aplicativo autor da chamada pode decidir aguardar até que o servidor não esteja mais ocupado, tentar novamente imediatamente ou tentar novamente após um intervalo especificado. Ele também pode decidir cancelar a chamada.

A resposta do autor da chamada é controlada pelas funções SetRetryReply e setMessagePendingDelay. SetRetryReply determina por quanto tempo o aplicativo autor da chamada deve aguardar entre repetições de uma determinada chamada. SetMessagePendingDelay determina por quanto tempo o aplicativo autor da chamada aguarda uma resposta do servidor antes de tomar medidas adicionais.

Normalmente, os padrões são aceitáveis e não precisam ser alterados. A estrutura repete a chamada a cada nRetryReply milissegundos até que a chamada seja transmitida ou o atraso de mensagem pendente tenha expirado. Um valor de 0 para nRetryReply especifica uma repetição imediata e -1 especifica o cancelamento da chamada.

Quando o atraso de mensagem pendente expira, a "caixa de diálogo ocupado" do OLE (consulte COleBusyDialog) é exibida para que o usuário possa optar por cancelar ou repetir a chamada. Chame EnableBusyDialog para habilitar ou desabilitar essa caixa de diálogo.

Quando uma mensagem de teclado ou mouse está pendente durante uma chamada e a chamada atinge o tempo limite (excede o atraso de mensagem pendente), a caixa de diálogo "não respondendo" é exibida. Chame EnableNotRespondingDialog para habilitar ou desabilitar essa caixa de diálogo. Normalmente, esse estado indica que algo deu errado e o usuário está ficando impaciente.

Quando as caixas de diálogo são desabilitadas, a "resposta de repetição" atual sempre é usada para chamadas a aplicativos ocupados.

Confira também

Classe CCmdTarget
Gráfico da hierarquia
Classe CCmdTarget