COleMessageFilter, classe

Gère l'accès concurrentiel requis par l'interaction des applications OLE.

Syntaxe

class COleMessageFilter : public CCmdTarget

Membres

Constructeurs publics

Méthodes publiques

Notes

La COleMessageFilter classe est utile dans les applications de serveur et de conteneur d’édition visuelle, ainsi que dans les applications OLE Automation. Pour les applications serveur appelées, cette classe peut être utilisée pour rendre l’application « occupée » afin que les appels entrants d’autres applications conteneur soient annulés ou retentés ultérieurement. Cette classe peut également être utilisée pour déterminer l’action à entreprendre par une application appelante lorsque l’application appelée est occupée.

L’utilisation courante est destinée à une application serveur pour appeler BeginBusyState et EndBusyState lorsqu’il serait dangereux pour un document ou un autre objet OLE accessible à être détruit. Ces appels sont effectués dans CWinApp ::OnIdle pendant les mises à jour de l’interface utilisateur.

Par défaut, un COleMessageFilter objet est alloué lorsque l’application est initialisée. Il peut être récupéré avec AfxOleGetMessageFilter.

Il s’agit d’une classe avancée ; vous avez rarement besoin de travailler directement avec elle.

Pour plus d’informations, consultez l’article Serveurs : Implémentation d’un serveur.

Hiérarchie d'héritage

CObject

CCmdTarget

COleMessageFilter

Spécifications

En-tête : afxole.h

COleMessageFilter ::BeginBusyState

Appelez cette fonction pour commencer un état occupé.

virtual void BeginBusyState();

Notes

Il fonctionne conjointement avec EndBusyState pour contrôler l’état occupé de l’application. La fonction SetBusyReply détermine la réponse de l’application aux applications appelantes lorsqu’elle est occupée.

Les BeginBusyState incréments et EndBusyState les appels sont incrémentés et décrémentés, respectivement, un compteur qui détermine si l’application est occupée. Par exemple, deux appels à BeginBusyState et un appel pour EndBusyState toujours entraîner un état occupé. Pour annuler un état occupé, il est nécessaire d’appeler EndBusyState le même nombre de fois BeginBusyState qu’il a été appelé.

Par défaut, l’infrastructure entre dans l’état occupé pendant le traitement inactif, qui est effectué par CWinApp ::OnIdle. Bien que l’application gère ON_COMMANDUPDATEUI notifications, les appels entrants sont gérés ultérieurement, une fois le traitement inactif terminé.

COleMessageFilter ::COleMessageFilter

Crée un objet COleMessageFilter.

COleMessageFilter();

COleMessageFilter ::EnableBusyDialog

Active et désactive la boîte de dialogue occupée, qui s’affiche lorsque le délai en attente de message expire (voir SetRetryReply) pendant un appel OLE.

void EnableBusyDialog(BOOL bEnableBusy = TRUE);

Paramètres

bEnableBusy
Spécifie si la boîte de dialogue « occupé » est activée ou désactivée.

COleMessageFilter ::EnableNotRespondingDialog

Active et désactive la boîte de dialogue « Non réponse », qui s’affiche si un clavier ou un message de souris est en attente pendant un appel OLE et que l’appel a expiré.

void EnableNotRespondingDialog(BOOL bEnableNotResponding = TRUE);

Paramètres

bEnableNotResponding
Spécifie si la boîte de dialogue « ne répond pas » est activée ou désactivée.

COleMessageFilter ::EndBusyState

Appelez cette fonction pour terminer un état occupé.

virtual void EndBusyState();

Notes

Elle fonctionne conjointement avec BeginBusyState pour contrôler l’état occupé de l’application. La fonction SetBusyReply détermine la réponse de l’application aux applications appelantes lorsqu’elle est occupée.

Les BeginBusyState incréments et EndBusyState les appels sont incrémentés et décrémentés, respectivement, un compteur qui détermine si l’application est occupée. Par exemple, deux appels à BeginBusyState et un appel pour EndBusyState toujours entraîner un état occupé. Pour annuler un état occupé, il est nécessaire d’appeler EndBusyState le même nombre de fois BeginBusyState qu’il a été appelé.

Par défaut, l’infrastructure entre dans l’état occupé pendant le traitement inactif, qui est effectué par CWinApp ::OnIdle. Pendant que l’application gère ON_UPDATE_COMMAND_UI notifications, les appels entrants sont gérés une fois le traitement inactif terminé.

COleMessageFilter ::OnMessagePending

Appelé par l’infrastructure pour traiter les messages pendant qu’un appel OLE est en cours.

virtual BOOL OnMessagePending(const MSG* pMsg);

Paramètres

pMsg
Pointeur vers le message en attente.

Valeur de retour

Différent de zéro en cas de réussite ; sinon, 0.

Notes

Lorsqu’une application appelante attend la fin d’un appel, l’infrastructure appelle OnMessagePending avec un pointeur vers le message en attente. Par défaut, l’infrastructure distribue WM_PAINT messages, afin que les mises à jour de fenêtre puissent se produire pendant un appel qui prend beaucoup de temps.

Vous devez inscrire votre filtre de messages au moyen d’un appel à Inscrire avant de pouvoir être actif.

COleMessageFilter ::Register

Inscrit le filtre de messages avec les DLL système OLE.

BOOL Register();

Valeur de retour

Différent de zéro en cas de réussite ; sinon, 0.

Notes

Un filtre de message n’a aucun effet, sauf s’il est inscrit auprès des DLL système. En règle générale, le code d’initialisation de votre application inscrit le filtre de message de l’application. Tout autre filtre de message inscrit par votre application doit être révoqué avant que le programme ne se termine par un appel à Revoke.

Le filtre de messages par défaut de l’infrastructure est automatiquement inscrit lors de l’initialisation et révoqué à l’arrêt.

COleMessageFilter ::Revoke

Révoque une inscription précédente effectuée par un appel à Inscrire.

void Revoke();

Notes

Un filtre de message doit être révoqué avant la fin du programme.

Le filtre de message par défaut, créé et enregistré automatiquement par l’infrastructure, est également révoqué automatiquement.

COleMessageFilter ::SetBusyReply

Cette fonction définit la « réponse occupée » de l’application.

void SetBusyReply(SERVERCALL nBusyReply);

Paramètres

nBusyReply
Valeur de l’énumération SERVERCALL , qui est définie dans COMPOBJ.H. Il peut avoir l’une des valeurs suivantes :

• SERVERCALL_ISHANDLED L’application peut accepter des appels, mais peut échouer dans le traitement d’un appel particulier.

• SERVERCALL_REJECTED L’application ne pourra probablement jamais traiter un appel.

• SERVERCALL_RETRYLATER L’application est temporairement dans un état dans lequel elle ne peut pas traiter un appel.

Notes

Les fonctions BeginBusyState et EndBusyState contrôlent l’état occupé de l’application.

Lorsqu’une application a été occupée avec un appel, BeginBusyStateelle répond aux appels des DLL système OLE avec une valeur déterminée par le dernier paramètre de SetBusyReply. L’application appelante utilise cette réponse occupée pour déterminer quelle action effectuer.

Par défaut, la réponse occupée est SERVERCALL_RETRYLATER. Cette réponse entraîne la nouvelle tentative d’appel de l’application appelante dès que possible.

COleMessageFilter ::SetMessagePendingDelay

Détermine la durée pendant laquelle l’application appelante attend une réponse de l’application appelée avant d’entreprendre d’autres actions.

void SetMessagePendingDelay(DWORD nTimeout = 5000);

Paramètres

nTimeout
Nombre de millisecondes pour le délai en attente de message.

Notes

Cette fonction fonctionne en concert avec SetRetryReply.

COleMessageFilter ::SetRetryReply

Détermine l’action de l’application appelante lorsqu’elle reçoit une réponse occupée d’une application appelée.

void SetRetryReply(DWORD nRetryReply = 0);

Paramètres

nRetryReply
Nombre de millisecondes entre les nouvelles tentatives.

Notes

Lorsqu’une application appelée indique qu’elle est occupée, l’application appelante peut décider d’attendre que le serveur ne soit plus occupé, de réessayer immédiatement ou de réessayer après un intervalle spécifié. Il peut également décider d’annuler complètement l’appel.

La réponse de l’appelant est contrôlée par les fonctions SetRetryReply et SetMessagePendingDelay. SetRetryReply détermine la durée pendant laquelle l’application appelante doit attendre entre les nouvelles tentatives pour un appel donné. SetMessagePendingDelay détermine la durée pendant laquelle l’application appelante attend une réponse du serveur avant d’entreprendre d’autres actions.

En règle générale, les valeurs par défaut sont acceptables et n’ont pas besoin d’être modifiées. Le framework retente l’appel toutes les millisecondes nRetryReply jusqu’à ce que l’appel passe ou que le délai en attente de message ait expiré. La valeur 0 pour nRetryReply spécifie une nouvelle tentative immédiate et - 1 spécifie l’annulation de l’appel.

Lorsque le délai en attente de message a expiré, la « boîte de dialogue occupée » OLE (voir COleBusyDialog) s’affiche afin que l’utilisateur puisse choisir d’annuler ou de réessayer l’appel. Appelez EnableBusyDialog pour activer ou désactiver cette boîte de dialogue.

Lorsqu’un clavier ou un message de souris est en attente pendant un appel et que l’appel a expiré (dépassement du délai d’attente du message), la boîte de dialogue « ne répond pas » s’affiche. Appelez EnableNotRespondingDialog pour activer ou désactiver cette boîte de dialogue. En règle générale, cet état des affaires indique que quelque chose a été incorrect et que l’utilisateur est impatient.

Lorsque les boîtes de dialogue sont désactivées, la « réponse à nouvelle tentative » actuelle est toujours utilisée pour les appels aux applications occupées.

Voir aussi

CCmdTarget, classe
Graphique hiérarchique
CCmdTarget, classe