Contrôle d'application

OLE nécessite un contrôle substantiel sur les applications et leurs objets. Les DLL système OLE doivent être en mesure de lancer et de libérer automatiquement des applications, de coordonner leur production et leur modification d’objets, et ainsi de suite. Les fonctions de cette rubrique répondent à ces exigences. En plus d’être appelées par les DLL système OLE, ces fonctions doivent parfois être appelées par des applications.

Contrôle d'application

AfxOleCanExitApp

Indique si l’application peut se terminer.

BOOL AFXAPI AfxOleCanExitApp();

Valeur de retour

Différent de zéro si l’application peut quitter ; sinon 0.

Notes

Une application ne doit pas se terminer s’il existe des références en attente à ses objets. Les fonctions AfxOleLockApp globales et AfxOleUnlockApp incrémentent et décrémentent, respectivement, un compteur de références aux objets de l’application. L’application ne doit pas se terminer lorsque ce compteur n’est pas zéro. Si le compteur n’est pas différent de zéro, la fenêtre principale de l’application est masquée (non détruite) lorsque l’utilisateur choisit Fermer dans le menu système ou quittez le menu Fichier. L’infrastructure appelle cette fonction dans CFrameWnd::OnClose.

Exemple

// Helper exit function for automation server
BOOL CMainFrame::CanExit()
{
   if (AfxOleCanExitApp())
   {
      // No outstanding object counts - go ahead and exit
      return TRUE;
   }
   else
   {
      // There are outstanding OLE object counts...
      // hide app to give user impression that application has exited.
      ShowWindow(SW_HIDE);
      // take user out of control of the app
      AfxOleSetUserCtrl(FALSE);
      return FALSE;
   }
}

Spécifications

En-tête : afxdisp.h

AfxOleGetMessageFilter

Récupère le filtre de message actuel de l’application.

COleMessageFilter* AFXAPI AfxOleGetMessageFilter();

Valeur de retour

Pointeur vers le filtre de message actuel.

Notes

Appelez cette fonction pour accéder à l’objet dérivé actuel COleMessageFilter, tout comme vous l’appeliez AfxGetApp pour accéder à l’objet d’application actuel.

Exemple

COleMessageFilter *pFilter = AfxOleGetMessageFilter();
ASSERT_VALID(pFilter);
pFilter->BeginBusyState();
// do things requiring a busy state
pFilter->EndBusyState();

// Another example
//CWinApp-derived class
BOOL CCMFCAutomationApp::InitInstance()
{
   CWinApp::InitInstance();

   // Initialize OLE libraries
   if (!AfxOleInit())
   {
      AfxMessageBox(IDP_OLE_INIT_FAILED);
      return FALSE;
   }

   CWinThread *pThread = AfxGetThread();
   if (pThread != NULL)
   {
      // Destroy message filter, thereby unregistering it.
      delete pThread->m_pMessageFilter;
      pThread->m_pMessageFilter = NULL;

      // Create the new message filter object.
      //CMyMessageFilter is derived from COleMessageFilter
      pThread->m_pMessageFilter = new CMyMessageFilter;
      ASSERT(AfxOleGetMessageFilter() != NULL);

      // Register the new message filter object.
      AfxOleGetMessageFilter()->Register();
   }
   //...
   //...
   //...
}

Spécifications

En-tête : afxwin.h

AfxOleGetUserCtrl

Récupère l’indicateur de contrôle utilisateur actuel.

BOOL AFXAPI AfxOleGetUserCtrl();

Valeur de retour

Différent de zéro si l’utilisateur est dans le contrôle de l’application ; sinon 0.

Notes

L’utilisateur contrôle l’application lorsque l’utilisateur a ouvert ou créé explicitement un document. L’utilisateur est également en contrôle si l’application n’a pas été lancée par les DLL système OLE , en d’autres termes, si l’utilisateur a lancé l’application avec l’interpréteur de commandes système.

Spécifications

En-tête : afxdisp.h

AfxOleSetUserCtrl

Définit ou efface l’indicateur de contrôle utilisateur, qui est expliqué dans la référence pour AfxOleGetUserCtrl.

void AFXAPI AfxOleSetUserCtrl(BOOL bUserCtrl);

Paramètres

bUserCtrl
Spécifie si l’indicateur de contrôle utilisateur doit être défini ou effacé.

Notes

L’infrastructure appelle cette fonction lorsque l’utilisateur crée ou charge un document, mais pas lorsqu’un document est chargé ou créé par le biais d’une action indirecte telle que le chargement d’un objet incorporé à partir d’une application conteneur.

Appelez cette fonction si d’autres actions de votre application doivent placer l’utilisateur dans le contrôle de l’application.

Spécifications

En-tête : afxdisp.h

AfxOleLockApp

Incrémente le nombre global d’objets actifs de l’infrastructure dans l’application.

void AFXAPI AfxOleLockApp();

Notes

L’infrastructure conserve le nombre d’objets actifs dans une application. Les AfxOleLockApp fonctions et AfxOleUnlockApp les fonctions, respectivement, incrémentent et décrémentent ce nombre.

Lorsque l’utilisateur tente de fermer une application qui a des objets actifs ( une application pour laquelle le nombre d’objets actifs n’est pas zéro), l’infrastructure masque l’application de la vue de l’utilisateur au lieu de l’arrêter complètement. La AfxOleCanExitApp fonction indique si l’application peut se terminer.

Appel AfxOleLockApp à partir d’un objet qui expose des interfaces OLE, s’il serait indésirable que cet objet soit détruit tout en étant toujours utilisé par une application cliente. Appelez AfxOleUnlockApp également le destructeur de n’importe quel objet qui appelle AfxOleLockApp le constructeur. Par défaut, COleDocument (et les classes dérivées) verrouillent et déverrouillent automatiquement l’application.

Exemple

// Below is a code sample from an  Application Wizard-generated SDI
// Application with Automation support. The Application Wizard adds a
// dispatch interface to the document class. AfxOleLockApp() and
// AfxOleUnlockApp() respectively increment and decrement the
// application's object count. When the object count is equal to
// zero and if the user has not taken control of the application,
// the server is terminated.

CCMFCAutomationDoc::CCMFCAutomationDoc()
{
   EnableAutomation();
   AfxOleLockApp();
}

CCMFCAutomationDoc::~CCMFCAutomationDoc()
{
   AfxOleUnlockApp();
}

Spécifications

En-tête : afxdisp.h

AfxOleUnlockApp

Décrémente le nombre d’objets actifs de l’infrastructure dans l’application.

void AFXAPI AfxOleUnlockApp();

Notes

Consultez AfxOleLockApp pour plus d’informations.

Lorsque le nombre d’objets actifs atteint zéro, AfxOleOnReleaseAllObjects est appelé.

Exemple

Consultez l’exemple d’AfxOleLockApp.

Spécifications

En-tête : afxdisp.h

AfxOleLockControl

Verrouille la fabrique de classe du contrôle spécifié afin que les données créées dynamiquement associées au contrôle restent en mémoire.

Syntaxe

BOOL AFXAPI AfxOleLockControl(  REFCLSID clsid  );
BOOL AFXAPI AfxOleLockControl( LPCTSTR lpszProgID );

Paramètres

clsid
ID de classe unique du contrôle.

lpszProgID
ID de programme unique du contrôle.

Valeur de retour

Différent de zéro si la fabrique de classe du contrôle a été correctement verrouillée ; sinon 0.

Notes

Cela peut accélérer considérablement l’affichage des contrôles. Par exemple, une fois que vous avez créé un contrôle dans une boîte de dialogue et que vous verrouillez le contrôle avec AfxOleLockControl, vous n’avez pas besoin de le créer et de le tuer à chaque fois que le dialogue est affiché ou détruit. Si l’utilisateur ouvre et ferme une boîte de dialogue à plusieurs reprises, le verrouillage de vos contrôles peut améliorer considérablement les performances. Lorsque vous êtes prêt à détruire le contrôle, appelez AfxOleUnlockControl.

Exemple

// Starts and locks control's (Microsoft Calendar) class factory.
// Control will remain in memory for lifetime of
// application or until AfxOleUnlockControl() is called.

AfxOleLockControl(_T("MSCAL.Calendar"));

Spécifications

En-tête : afxwin.h

AfxOleRegisterServerClass

Cette fonction vous permet d’inscrire votre serveur dans le registre du système OLE.

BOOL AFXAPI AfxOleRegisterServerClass(
    REFCLSID clsid,
    LPCTSTR lpszClassName,
    LPCTSTR lpszShortTypeName,
    LPCTSTR lpszLongTypeName,
    OLE_APPTYPE nAppType = OAT_SERVER,
    LPCTSTR* rglpszRegister = NULL,
    LPCTSTR* rglpszOverwrite = NULL);

Paramètres

clsid
Référence à l’ID de classe OLE du serveur.

lpszClassName
Pointeur vers une chaîne contenant le nom de classe des objets du serveur.

lpszShortTypeName
Pointeur vers une chaîne contenant le nom court du type d’objet du serveur, tel que « Chart ».

lpszLongTypeName
Pointeur vers une chaîne contenant le nom long du type d’objet du serveur, tel que « Graphique Microsoft Excel 5.0 ».

nAppType
Valeur, extraite de l’énumération OLE_APPTYPE, spécifiant le type d’application OLE. Les valeurs possibles sont les suivantes :

• OAT_INPLACE_SERVER Server dispose d’une interface utilisateur de serveur complète.

• OAT_SERVER Server prend uniquement en charge l’incorporation.

• OAT_CONTAINER Container prend en charge les liens vers des incorporations.

• IDispatchOAT_DISPATCH_OBJECT objet compatible.

rglpszRegister
Tableau de pointeurs vers des chaînes représentant les clés et les valeurs à ajouter au registre du système OLE si aucune valeur existante pour les clés n’est trouvée.

rglpszOverwrite
Tableau de pointeurs vers des chaînes représentant les clés et les valeurs à ajouter au registre système OLE si le Registre contient des valeurs existantes pour les clés données.

Valeur de retour

Différent de zéro si la classe de serveur est correctement inscrite ; sinon 0.

Notes

La plupart des applications peuvent utiliser COleTemplateServer::Register pour inscrire les types de documents de l’application. Si le format de registre système de votre application ne correspond pas au modèle classique, vous pouvez l’utiliser AfxOleRegisterServerClass pour plus de contrôle.

Le Registre se compose d’un ensemble de clés et de valeurs. Les arguments rglpszRegister et rglpszOverwrite sont des tableaux de pointeurs vers des chaînes, chacun composé d’une clé et d’une valeur séparée par un caractère NULL ( '\0'). Chacune de ces chaînes peut avoir des paramètres remplaçables dont les emplacements sont marqués par les séquences de caractères %1 à %5.

Les symboles sont renseignés comme suit :

Spécifications

En-tête : afxdisp.h

AfxOleSetEditMenu

Implémente l’interface utilisateur de la commande Typename Object.

void AFXAPI AfxOleSetEditMenu(
    COleClientItem* pClient,
    CMenu* pMenu,
    UINT iMenuItem,
    UINT nIDVerbMin,
    UINT nIDVerbMax = 0,
    UINT nIDConvert = 0);

Paramètres

pClient
Pointeur vers l’élément OLE client.

pMenu
Pointeur vers l’objet de menu à mettre à jour.

iMenuItem
Index de l’élément de menu à mettre à jour.

nIDVerbMin
ID de commande qui correspond au verbe principal.

nIDVerbMax
ID de commande qui correspond au dernier verbe.

nIDConvert
ID de l’élément de menu Convertir.

Notes

Si le serveur reconnaît uniquement un verbe principal, l’élément de menu devient « verb typename Object » et la commande nIDVerbMin est envoyée lorsque l’utilisateur choisit la commande. Si le serveur reconnaît plusieurs verbes, l’élément de menu devient « typename Object » et un sous-menu listant tous les verbes s’affiche lorsque l’utilisateur choisit la commande. Lorsque l’utilisateur choisit un verbe dans le sous-menu, nIDVerbMin est envoyé si le premier verbe est choisi, nIDVerbMin + 1 est envoyé si le deuxième verbe est choisi, et ainsi de suite. L’implémentation par défaut COleDocument gère automatiquement cette fonctionnalité.

Vous devez disposer de l’instruction suivante dans le script de ressource d’application de votre client (. Fichier RC) :

<#include afxolecl.rc>

Spécifications

En-tête : afxole.h

AfxOleUnlockControl

Déverrouille la fabrique de classe du contrôle spécifié.

Syntaxe

BOOL AFXAPI AfxOleUnlockControl( REFCLSID clsid );
BOOL AFXAPI AfxOleUnlockControl( LPCTSTR lpszProgID );

Paramètres

clsid
ID de classe unique du contrôle.

lpszProgID
ID de programme unique du contrôle.

Valeur de retour

Différent de zéro si la fabrique de classe du contrôle a été déverrouillée avec succès ; sinon 0.

Notes

Un contrôle est verrouillé avec AfxOleLockControl, de sorte que les données créées dynamiquement associées au contrôle restent en mémoire. Cela peut accélérer considérablement l’affichage du contrôle, car le contrôle n’a pas besoin d’être créé et détruit chaque fois qu’il est affiché. Lorsque vous êtes prêt à détruire le contrôle, appelez AfxOleUnlockControl.

Exemple

// Unlock control's (Microsoft Calendar Control) class factory.

AfxOleUnlockControl(_T("MSCAL.Calendar"));

Spécifications

En-tête : afxwin.h

Voir aussi

Macros et globals