Clase COleMessageFilter
Administra la simultaneidad requerida por la interacción de aplicaciones OLE.
Sintaxis
class COleMessageFilter : public CCmdTarget
Miembros
Constructores públicos
| Nombre | Descripción |
|---|---|
| COleMessageFilter::COleMessageFilter | Construye un objeto COleMessageFilter. |
Métodos públicos
| Nombre | Descripción |
|---|---|
| COleMessageFilter::BeginBusyState | Coloca la aplicación en estado ocupado. |
| COleMessageFilter::EnableBusyDialog | Habilita y deshabilita el cuadro de diálogo que aparece cuando una aplicación a la que se llama está ocupada. |
| COleMessageFilter::EnableNotRespondingDialog | Habilita y deshabilita el cuadro de diálogo que aparece cuando una aplicación a la que se llama no responde. |
| COleMessageFilter::EndBusyState | Finaliza el estado ocupado de la aplicación. |
| COleMessageFilter::OnMessagePending | El marco llama a este método para procesar los mensajes mientras una llamada OLE está en curso. |
| COleMessageFilter::Register | Registra el filtro de mensajes con los archivos DLL del sistema OLE. |
| COleMessageFilter::Revoke | Revoca el registro del filtro de mensajes con los archivos DLL del sistema OLE. |
| COleMessageFilter::SetBusyReply | Determina la respuesta de la aplicación ocupada a una llamada OLE. |
| COleMessageFilter::SetMessagePendingDelay | Determina durante cuánto tiempo espera la aplicación una respuesta a una llamada OLE. |
| COleMessageFilter::SetRetryReply | Determina la respuesta de la aplicación que llama a una aplicación ocupada. |
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
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.