Control de la aplicación

Artículo
06/16/2023

OLE requiere un control sustancial sobre las aplicaciones y sus objetos. Los archivos DLL del sistema OLE deben poder iniciar y lanzar aplicaciones automáticamente, coordinar su producción y modificación de objetos, etc. Las funciones de este tema cumplen con esos requisitos. Estas funciones no solo deben ser llamadas por los archivos DLL del sistema OLE, sino también, en algunas ocasiones, por las aplicaciones.

Control de la aplicación

Nombre	Descripción
AfxOleCanExitApp	Indica si la aplicación puede finalizar.
AfxOleGetMessageFilter	Recupera el filtro de mensajes actual de la aplicación.
AfxOleGetUserCtrl	Recupera la marca de control de usuario actual.
AfxOleSetUserCtrl	Establece o borra la marca de control de usuario.
AfxOleLockApp	Incrementa el contador global del marco del número de objetos activos en una aplicación.
AfxOleLockControl	Bloquea el generador de clases del control especificado.
AfxOleUnlockApp	Disminuye el contador del marco del número de objetos activos en una aplicación.
AfxOleUnlockControl	Desbloquea el generador de clases del control especificado.
AfxOleRegisterServerClass	Registra un servidor en el registro del sistema OLE.
AfxOleSetEditMenu	Implementa la interfaz de usuario para el comando de objeto typename.

AfxOleCanExitApp

Indica si la aplicación puede finalizar.

BOOL AFXAPI AfxOleCanExitApp();

Valor devuelto

Distinto de cero si la aplicación puede finalizar; de lo contrario, 0.

Comentarios

Una aplicación no debe finalizar si hay referencias pendientes a sus objetos. Las funciones globales AfxOleLockApp y AfxOleUnlockApp aumentan y disminuyen, respectivamente, un contador de referencias a los objetos de la aplicación. La aplicación no debe finalizar cuando este contador sea distinto de cero. Si el contador es distinto de cero, la ventana principal de la aplicación se oculta (no se destruye) cuando el usuario elige Cerrar en el menú del sistema o Salir en el menú Archivo. El marco llama a esta función en CFrameWnd::OnClose.

Ejemplo

// 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;
   }
}

Requisitos

Encabezado: afxdisp.h

AfxOleGetMessageFilter

Recupera el filtro de mensajes actual de la aplicación.

COleMessageFilter* AFXAPI AfxOleGetMessageFilter();

Valor devuelto

Puntero al filtro de mensajes actual.

Comentarios

Llame a esta función para acceder al objeto derivado de COleMessageFilter actual, tal como llamaría a AfxGetApp para acceder al objeto de aplicación actual.

Ejemplo

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();
   }
   //...
   //...
   //...
}

Requisitos

Encabezado: afxwin.h

AfxOleGetUserCtrl

Recupera la marca de control de usuario actual.

BOOL AFXAPI AfxOleGetUserCtrl();

Valor devuelto

Distinto de cero si el usuario controla la aplicación; de lo contrario, 0.

Comentarios

El usuario controla la aplicación cuando el usuario ha abierto o creado explícitamente un documento nuevo. El usuario también tiene el control si los archivos DLL del sistema OLE no iniciaron la aplicación; en otras palabras, si el usuario inició la aplicación con el shell del sistema.

Requisitos

Encabezado: afxdisp.h

AfxOleSetUserCtrl

Establece o borra la marca de control de usuario, que se explica en la referencia para AfxOleGetUserCtrl.

void AFXAPI AfxOleSetUserCtrl(BOOL bUserCtrl);

Parámetros

bUserCtrl
Especifica si la marca de control de usuario se va a establecer o borrar.

Comentarios

El marco llama a esta función cuando el usuario crea o carga un documento, pero no cuando se carga o crea un documento a través de una acción indirecta, como cargar un objeto insertado desde una aplicación contenedora.

Llame a esta función si otras acciones de la aplicación deben poner al usuario en control de la aplicación.

Requisitos

Encabezado: afxdisp.h

AfxOleLockApp

Incrementa el contador global del marco del número de objetos activos en la aplicación.

void AFXAPI AfxOleLockApp();

Comentarios

El marco mantiene un contador del número de objetos activos en una aplicación. Las funciones AfxOleLockApp y AfxOleUnlockApp aumentan y disminuyen este contador, respectivamente.

Cuando el usuario intenta cerrar una aplicación que tiene objetos activos (una aplicación para la que el contador de objetos activos es distinto de cero), el marco oculta la aplicación de la vista del usuario en lugar de cerrarla por completo. La función AfxOleCanExitApp indica si la aplicación puede finalizar.

Llame a AfxOleLockApp desde cualquier objeto que exponga interfaces OLE si no desea que se destruya a ese objeto mientras lo sigue utilizando una aplicación cliente. Llame también a AfxOleUnlockApp en el destructor de cualquier objeto que llama a AfxOleLockApp en el constructor. De manera predeterminada, COleDocument, y las clases derivadas, bloquean y desbloquean automáticamente la aplicación.

Ejemplo

// 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();
}

Requisitos

Encabezado: afxdisp.h

AfxOleUnlockApp

Disminuye el contador del marco de objetos activos en la aplicación.

void AFXAPI AfxOleUnlockApp();

Comentarios

Para más información, consulte AfxOleLockApp.

Cuando el número de objetos activos llega a cero, se llama a AfxOleOnReleaseAllObjects.

Ejemplo

Consulte el ejemplo para AfxOleLockApp.

Requisitos

Encabezado: afxdisp.h

AfxOleLockControl

Bloquea el generador de clases del control especificado para que los datos creados dinámicamente que están asociados al control permanezcan en memoria.

Sintaxis

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

Parámetros

clsid
El Id. de clase único del control.

lpszProgID
Identificador de programa único del control.

Valor devuelto

Distinto de cero si el generador de clases del control se bloqueó correctamente; de lo contrario, 0.

Comentarios

Esto puede acelerar considerablemente la visualización de los controles. Por ejemplo, una vez que crea un control en un cuadro de diálogo y bloquea el control con AfxOleLockControl, no es necesario crearlo y volver a terminarlo cada vez que se muestra o se destruye el diálogo. Si el usuario abre y cierra un cuadro de diálogo repetidamente, bloquear los controles puede mejorar considerablemente el rendimiento. Cuando esté listo para destruir el control, llame a AfxOleUnlockControl.

Ejemplo

// 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"));

Requisitos

Encabezado: afxwin.h

AfxOleRegisterServerClass

Esta función permite registrar el servidor en el registro del sistema OLE.

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

Parámetros

clsid
Referencia al identificador de clase OLE del servidor.

lpszClassName
Puntero a una cadena que contiene el nombre de clase de los objetos del servidor.

lpszShortTypeName
Puntero a una cadena que contiene el nombre corto del tipo de objeto del servidor, como "Gráfico".

lpszLongTypeName
Puntero a una cadena que contiene el nombre largo del tipo de objeto del servidor, como "Gráfico de Microsoft Excel 5.0".

nAppType
Valor, tomado de la enumeración OLE_APPTYPE, que especifica el tipo de aplicación OLE. Los valores posibles son los siguientes:

OAT_INPLACE_SERVER El servidor tiene una interfaz de usuario de servidor completa.
OAT_SERVER El servidor solo admite la inserción.
OAT_CONTAINER El contenedor admite vínculos a inserciones.
OAT_DISPATCH_OBJECT Objeto compatible con IDispatch.

rglpszRegister
Matriz de punteros a cadenas que representan las claves y los valores que se van a agregar al registro del sistema OLE si no se encuentran valores existentes para las claves.

rglpszOverwrite
Matriz de punteros a cadenas que representan las claves y los valores que se van a agregar al registro del sistema OLE si el registro contiene valores existentes para las claves dadas.

Valor devuelto

Distinto de cero si la clase de servidor se registra correctamente; de lo contrario, 0.

Comentarios

La mayoría de las aplicaciones pueden usar COleTemplateServer::Register para registrar los tipos de documento de la aplicación. Si el formato del registro del sistema de la aplicación no se ajusta al patrón típico, puede usar AfxOleRegisterServerClass para un mayor control.

El registro consta de un conjunto de claves y valores. Los argumentos rglpszRegister y rglpszOverwrite son matrices de punteros a cadenas, cada una de ellas formada por una clave y un valor separados por un carácter NULL ('\0'). Cada una de estas cadenas puede tener parámetros reemplazables cuyos lugares están marcados mediante las secuencias de caracteres %1 a %5.

Los símbolos se llenan de la manera siguiente:

Símbolo	Valor
%1	Identificador de clase con formato de cadena
2 %	Nombre de la clase
3 %	Ruta de acceso al archivo ejecutable
%4	Nombre de tipo corto
5 %	Nombre de tipo largo

Requisitos

Encabezado: afxdisp.h

AfxOleSetEditMenu

Implementa la interfaz de usuario para el comando de objeto typename.

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

Parámetros

pClient
Puntero al elemento OLE de cliente.

pMenu
Puntero al objeto de menú que se va a actualizar.

iMenuItem
Índice del elemento de menú que se va a actualizar.

nIDVerbMin
Identificador de comando que corresponde al verbo principal.

nIDVerbMax
Identificador de comando que corresponde al último verbo.

nIDConvert
Identificador del elemento de menú Convertir.

Comentarios

Si el servidor reconoce solo un verbo principal, el elemento de menú se convierte en "objeto typename del verbo" y el comando nIDVerbMin se envía cuando el usuario elige el comando. Si el servidor reconoce varios verbos, el elemento de menú se convierte en "objeto typename" y aparece un submenú que enumera todos los verbos cuando el usuario elige el comando. Cuando el usuario elige un verbo del submenú, nIDVerbMin se envía si se elige el primer verbo, nIDVerbMin + 1 se envía si se elige el segundo verbo, y así sucesivamente. La implementación COleDocument predeterminada controla automáticamente esta característica.

Debe tener la instrucción siguiente en el archivo de script de recursos (.RC) de la aplicación del cliente:

#include <afxolecl.rc>

Requisitos

Encabezado: afxole.h

AfxOleUnlockControl

Desbloquea el generador de clases del control especificado.

Sintaxis

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

Parámetros

clsid
El Id. de clase único del control.

lpszProgID
Identificador de programa único del control.

Valor devuelto

Distinto de cero si el generador de clases del control se desbloqueó correctamente; de lo contrario, 0.

Comentarios

Un control se bloquea con AfxOleLockControl, de modo que los datos creados dinámicamente que están asociados al control permanecen en memoria. Esto puede acelerar considerablemente la visualización del control, porque no es necesario crear y destruir el control cada vez que se muestra. Cuando esté listo para destruir el control, llame a AfxOleUnlockControl.

Ejemplo

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

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

Requisitos

Encabezado: afxwin.h

Consulte también

Macros y globales

Compartir a través de

Control de la aplicación