Clase COleMessageFilter

Administra la simultaneidad requerida por la interacción de aplicaciones OLE.

Sintaxis

class COleMessageFilter : public CCmdTarget

Miembros

Constructores públicos

Métodos públicos

Comentarios

La clase COleMessageFilter es útil en las aplicaciones de contenedor y servidor de edición visual, así como en las aplicaciones de automatización OLE. En el caso de las aplicaciones de servidor a las que se llama, esta clase se puede usar para que la aplicación esté "ocupada", de manera que las llamadas entrantes de otras aplicaciones contenedoras se cancelen o se vuelvan a intentar más adelante. Esta clase también se puede usar para determinar la acción que debe realizar una aplicación que llama cuando la aplicación a la que se llama está ocupada.

El uso común es para que una aplicación de servidor llame a BeginBusyState y EndBusyState cuando sería peligroso destruir un documento u otro objeto OLE accesible. Estas llamadas se realizan en CWinApp::OnIdle durante las actualizaciones de la interfaz de usuario.

De manera predeterminada, se asigna un objeto COleMessageFilter cuando se inicializa la aplicación. Se puede recuperar con AfxOleGetMessageFilter.

Se trata de una clase avanzada; rara vez necesita trabajar directamente con ella.

Para más información, consulte el artículo Servidores: Implementación de un servidor.

Jerarquía de herencia

CObject

CCmdTarget

COleMessageFilter

Requisitos

Encabezado: afxole.h

COleMessageFilter::BeginBusyState

Llame a esta función para comenzar un estado "ocupado".

virtual void BeginBusyState();

Comentarios

Funciona junto con EndBusyState para controlar el estado ocupado de la aplicación. La función SetBusyReply determina la respuesta de la aplicación a las aplicaciones que la llaman cuando está ocupada.

Las llamadas a BeginBusyState y EndBusyState aumentan y disminuyen, respectivamente, un contador que determina si la aplicación está ocupada. Por ejemplo, dos llamadas a BeginBusyState y una llamada a EndBusyState siguen dando como resultado un estado ocupado. Para cancelar un estado ocupado, es necesario llamar EndBusyState al mismo número de veces que a BeginBusyState.

De manera predeterminada, el marco entra en el estado ocupado durante el procesamiento inactivo, que CWinApp::OnIdle lleva a cabo. Mientras la aplicación controla las notificaciones ON_COMMANDUPDATEUI, las llamadas entrantes se controlan más adelante, una vez que se completa el procesamiento inactivo.

COleMessageFilter::COleMessageFilter

Crea un objeto COleMessageFilter.

COleMessageFilter();

COleMessageFilter::EnableBusyDialog

Habilita y deshabilita el cuadro de diálogo "ocupado", el que se muestra cuando expira el retraso pendiente del mensaje (consulte SetRetryReply) durante una llamada OLE.

void EnableBusyDialog(BOOL bEnableBusy = TRUE);

Parámetros

bEnableBusy
Especifica si el cuadro de diálogo "ocupado" está habilitado o deshabilitado.

COleMessageFilter::EnableNotRespondingDialog

Habilita y deshabilita el cuadro de diálogo "no responde", el que se muestra si un mensaje de teclado o mouse está pendiente durante una llamada OLE y se agotó el tiempo de espera de la llamada.

void EnableNotRespondingDialog(BOOL bEnableNotResponding = TRUE);

Parámetros

bEnableNotResponding
Especifica si el cuadro de diálogo "no responde" está habilitado o deshabilitado.

COleMessageFilter::EndBusyState

Llame a esta función para finalizar un estado "ocupado".

virtual void EndBusyState();

Comentarios

Funciona junto con BeginBusyState para controlar el estado ocupado de la aplicación. La función SetBusyReply determina la respuesta de la aplicación a las aplicaciones que la llaman cuando está ocupada.

Las llamadas a BeginBusyState y EndBusyState aumentan y disminuyen, respectivamente, un contador que determina si la aplicación está ocupada. Por ejemplo, dos llamadas a BeginBusyState y una llamada a EndBusyState siguen dando como resultado un estado ocupado. Para cancelar un estado ocupado, es necesario llamar EndBusyState al mismo número de veces que a BeginBusyState.

De manera predeterminada, el marco entra en el estado ocupado durante el procesamiento inactivo, que CWinApp::OnIdle lleva a cabo. Mientras la aplicación controla las notificaciones ON_UPDATE_COMMAND_UI, las llamadas entrantes se controlan una vez que se completa el procesamiento inactivo.

COleMessageFilter::OnMessagePending

El marco llama a este método para procesar los mensajes mientras una llamada OLE está en curso.

virtual BOOL OnMessagePending(const MSG* pMsg);

Parámetros

PMSG
Puntero al mensaje pendiente.

Valor devuelto

Distinto de cero en caso de éxito; en caso contrario, es 0.

Comentarios

Cuando una aplicación que llamada espera a que se complete una llamada, el marco llama a OnMessagePending con un puntero al mensaje pendiente. De manera predeterminada, el marco envía mensajes WM_PAINT, de modo que puedan ocurrir actualizaciones de ventana durante una llamada que tarda mucho tiempo.

Debe registrar el filtro de mensajes mediante una llamada a Register para poder activarlo.

COleMessageFilter::Register

Registra el filtro de mensajes con los archivos DLL del sistema OLE.

BOOL Register();

Valor devuelto

Distinto de cero en caso de éxito; en caso contrario, es 0.

Comentarios

Un filtro de mensajes no tiene ningún efecto a menos que se registre con los archivos DLL del sistema. Por lo general, el código de inicialización de la aplicación registra el filtro de mensajes de la aplicación. Cualquier otro filtro de mensajes que la aplicación registre se debe revocar antes de que el programa finalice mediante una llamada a Revoke.

El filtro de mensajes predeterminado del marco se registra automáticamente durante la inicialización y se revoca al finalizar.

COleMessageFilter::Revoke

Revoca un registro anterior realizado mediante una llamada a Register.

void Revoke();

Comentarios

Se debe revocar un filtro de mensajes antes de que finalice el programa.

El filtro de mensajes predeterminado, que el marco crea y registra automáticamente, también se revoca de manera automática.

COleMessageFilter::SetBusyReply

Esta función establece la "respuesta ocupada" de la aplicación.

void SetBusyReply(SERVERCALL nBusyReply);

Parámetros

nBusyReply
Valor de la enumeración SERVERCALL, que se define en COMPOBJ.H. Puede tener uno de los valores siguientes:

• SERVERCALL_ISHANDLED La aplicación puede aceptar llamadas, pero se puede producir un error al procesar una llamada determinada.

• SERVERCALL_REJECTED La aplicación probablemente nunca podrá procesar una llamada.

• SERVERCALL_RETRYLATER La aplicación está temporalmente en un estado en el que no puede procesar una llamada.

Comentarios

Las funciones BeginBusyState y EndBusyState controlan el estado ocupado de la aplicación.

Cuando una aplicación ha entrado en un estado ocupado con una llamada a BeginBusyState, responde a las llamadas de los archivos DLL del sistema OLE con un valor determinado por la configuración más reciente de SetBusyReply. La aplicación que llama usa esta respuesta ocupada para determinar qué acción realizar.

De manera predeterminada, la respuesta ocupada es SERVERCALL_RETRYLATER. Esta respuesta hace que la aplicación que llama vuelva a intentar la llamada tan pronto como sea posible.

COleMessageFilter::SetMessagePendingDelay

Determina durante cuánto tiempo la aplicación que llama espera a que responda la aplicación a la que se llama antes de realizar más acciones.

void SetMessagePendingDelay(DWORD nTimeout = 5000);

Parámetros

nTimeout
Número de milisegundos para el retraso pendiente del mensaje.

Comentarios

Esta función funciona en conjunto con SetRetryReply.

COleMessageFilter::SetRetryReply

Determina la acción de la aplicación que llama cuando recibe una respuesta ocupada de una aplicación a la que se llama.

void SetRetryReply(DWORD nRetryReply = 0);

Parámetros

nRetryReply
Número de milisegundos entre reintentos.

Comentarios

Cuando una aplicación a la que se llama indica que está ocupada, la aplicación que llama puede decidir esperar hasta que el servidor ya no esté ocupado, volver a intentarlo de inmediato o volver a intentarlo después de un intervalo especificado. También puede decidir cancelar totalmente la llamada.

La respuesta del autor de llamada se controla mediante las funciones SetRetryReply y SetMessagePendingDelay. SetRetryReply determina durante cuánto tiempo la aplicación que llama debe esperar entre reintentos de una llamada determinada. SetMessagePendingDelay determina durante cuánto tiempo la aplicación que llama espera una respuesta del servidor antes de realizar más acciones.

Por lo general, los valores predeterminados son aceptables y no es necesario cambiarlos. El marco reintenta la llamada a cada nRetryReply milisegundos hasta que la llamada entra o expira el retraso pendiente del mensaje. Un valor de 0 para nRetryReply especifica un reintento inmediato y - 1 especifica la cancelación de la llamada.

Cuando el retraso pendiente del mensaje expira, se muestra el "cuadro de diálogo ocupado" OLE (consulte COleBusyDialog) para que el usuario pueda optar por cancelar o reintentar la llamada. Llame a EnableBusyDialog para habilitar o deshabilitar este cuadro de diálogo.

Cuando un mensaje de teclado o mouse está pendiente durante una llamada y se agota el tiempo de espera de la llamada (superó el retraso pendiente del mensaje), se muestra el cuadro de diálogo "no responde". Llame a EnableNotRespondingDialog para habilitar o deshabilitar este cuadro de diálogo. Por lo general, esta situación indica que hubo un problema y el usuario está impaciente.

Con los diálogos deshabilitados, siempre se usa la "respuesta de reintento" actual para las llamadas a aplicaciones ocupadas.

Consulte también

CCmdTarget (clase)
Gráfico de jerarquías
CCmdTarget (clase)