How to Use AFX_MANAGE_STATE in an OLE Control (127074)

SUMMARY

The AFX_MANAGE_STATE macro is used to establish the correct module context for OLE controls and should be used for all external entry points to the control.

The existing implementation of COleControl and COlePropertyPage use AFX_MANAGE_STATE in several locations, but there are still some situations where the control writer will need to directly invoke AFX_MANAGE_STATE. This article shows you how.

MORE INFORMATION

OLE controls written with the OLE CDK use a shared MFC DLL to eliminate the need to have a separate copy of MFC in each control. In a way, an OLE control is similar to a standard MFC extension DLL. Previous versions of MFC use the _AFXDLL model to implement extension DLLs, one limitation of this model is that the host executable had to be written to also use the shared MFC DLL, that is it must be used by an MFC application. A different mechanism is needed for OLE controls because they can be used by non-MFC applications.

MFC maintains a small amount of global state information that includes (among other things) the instance handle used when loading resources. Many MFC functions rely on this state information, so it is important that it always reflect the state of the module currently executing.

The AFX_MANAGE_STATE macro creates a small local object on the stack that swaps in the control's state information in its constructor, and then restores the previous state in its destructor. A typical use of the macro looks like this:

STDAPI DllRegisterServer(void)
{
        AFX_MANAGE_STATE(_afxModuleAddrThis);

        if (!AfxOleRegisterTypeLib(AfxGetInstanceHandle(), _tlid))
                return ResultFromScode(SELFREG_E_TYPELIB);

        if (!COleObjectFactoryEx::UpdateRegistryAll(TRUE))
                return ResultFromScode(SELFREG_E_CLASS);

        return NOERROR;
}

All OLE controls implement a self-registration feature by exporting two functions, DllRegisterServer and DllUnregisterServer. These functions are called directly from outside of the control, so AFX_MANAGE_STATE must be invoked at the beginning of each function.

AFX_MANAGE_STATE should also be used when handling messages sent to a child window created by an OLE control. Such messages are sent directly to the child window, bypassing the call to AFX_MANAGE_STATE in COleControl::WindowProc().