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
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.