In this chapter, we will take a look at the distribution architecture of the Objective Grid class library. We will also go into details of how Dynamic Link Libraries (DLLs) in general, and MFC extension DLLs in particular, integrate with MFC applications. Objective Grid is primarily built and linked to as an MFC extension DLL. It is also possible to link to the Objective Grid library statically.

Please refer to the samples located at:

DLLs are a very important part of Windows. DLLs are pieces of program code that are separate from the main program. These segments of code can be loaded by the main program on demand and used in a transparent manner. All of the support required for doing this is built into the Windows operating system.

MFC in its present form supports three types of DLLs. These are:

Understanding how these DLL types function is essential to understanding the DLL architecture that is used by the Objective Grid class library.

These are the MFC DLL variants that are closest to regular Win32 DLLs. They use MFC internally and statically link to it. These DLLs have a CWinApp-derived object and can be called by any Win32 application. The calling application does not have to be an MFC application. Regular DLLs cannot (normally) export MFC objects. They are normally used to export C-style functions. These functions can be called by external programs. For example, consider the following function:

This function can be called from any application that links to this DLL.

As can be seen from above, these DLLs can use MFC just like any other MFC application, but cannot export MFC objects.

These are not very different from the regular DLLs explained above. The only difference is that they link dynamically to MFC. This is a considerable advantage, since it can make the DLL considerably smaller. Yet another unique possibility is available with this DLL. MFC extension DLLs (explained below) cannot be used with non-MFC applications. As a workaround, it is possible to create a regular DLL that links dynamically with MFC. This regular DLL would in turn link to the extension DLL. This lets us use the extension DLL from non-MFC applications. This approach is particularly useful for building COM severs with MFC (Objective Grid CCE uses this approach). With extension DLLs, management of run time classes and class factories is very easy. The functionality is then exported for use by other applications through a regular DLL COM server.

Regular DLLs dynamically linked to MFC also have CWinApp-derived application objects.

These DLLs are the most interesting DLLs from an MFC programmer’s perspective. They can be used to export cool MFC derived functionality in a seamless manner that is otherwise not possible. Let us say that we have a cool CView-derived class that we would like to share among programs (and perhaps among programmers). We can simply put this CView-derived class in an MFC extension DLL, and it can be shared in seamless manner from any MFC application! To understand how this works, let us take a look at the initialization code in an MFC extension DLL.

MFC extension DLLs do not have a CWinApp-derived object. Their DllMain() function is very similar to what you would normally expect from a WIN32 DLL.

We can see that the DLL makes a call to AfxInitExtensionModule().

This function just saves data that is used by MFC, the DLL module handle, the run-time class list head, and also the class factory list head. This is the first part of the initialization.

The extension DLL acts as part of the application that hosts it. To make this possible, an object of class CDynLinkLibrary is created on the heap. This is the second part of the initialization.

Creating an instance of CDynLinkLibrary causes the data that is inherent to the DLL to become part of a global linked list that MFC maintains.

The first part of the CDynLinkLibrary saves state information:

The second part of the constructor adds this CDynLinkLibrary object to the linked list that is maintained by the MFC framework.

Adding this CDynLinkLibrary to the linked list that is maintained by the framework ensures that the newly loaded MFC extension DLL functions as a seamless part of the application. Whenever MFC locates a resource, run-time class, or a class factory, it looks up this list and basically iterates through it. This ensures that there is no delineation between the calling application and this DLL. To illustrate this, let us look at the code for CRuntimeClass::Load().

First, the above code loads the run-time class name. It then attempts to look up the run-time class in the application. It then looks at the classes in extension DLLs simply iterating through them as highlighted above. This explains how MFC extension DLLs work like a part of the calling application.

To understand the mechanism for importing and exporting symbols (functions and variables) that are used in Stingray Studio libraries, refer to “Extending Stingray Libraries” in the Getting Started part

Now that we have covered the various important aspects about MFC DLLs that concern an Objective Grid programmer, let us look at yet another related important topic, the concept of module state.

In its simplest sense, the module state is state information that is used by the MFC library for everything from loading resources to creating ActiveX objects. Each application that links to the MFC DLL has a unique module state that separates itself from every other user of that DLL. You can think of discrete module state cubes as separate MFC processes. To understand a little better, let us look at the definition of AFX_MODULE_STATE (shown with some data omitted for brevity).

It is clear that this data is what defines much of how an extension DLL behaves as part of a chain of DLLs. We can readily see that if a DLL is registered in one module state, it will not be found in another module state list. Even within the same process, we can see that lists of run-time classes, ActiveX class factories etc., are visible only from within the correct module state.

Now that we understand the basics of AFX_MODULE_STATE, let us proceed to look at situations where distinct module states come into play and where they don’t. In general, the most important points to remember are:

We can see from the above that for a MFC extension DLL to function normally, it will have to be in the module state context that it was initialized in. In any other context, calls into the DLL will fail in a cryptic manner, with ASSERT_VALID triggering or resources failing to load. To gain a better understanding, let us look at a few real life scenarios and attempt to analyze them in terms of what we have seen so far.

There is no problem with this approach, since the module state context in which the DLL is initialized is the same as that which is used when calls are made into the DLL. This is the situation that most users will find themselves in. You don’t have to worry much about the module state in this case.

In this case we can readily discern, based on what we know, that there are two distinct module states—one that pertains to the application, and one that pertains to the regular DLL. Since this regular DLL is what makes calls into the grid, this is the module that should initialize the grid. So we just initialize the grid in terms of the regular DLLs module state. To do this, we have to make a special call to an initialization function that is exported by the grid extension DLL:

All that this function does is to create a CDynLinkLibrary on the heap. Why is this not done implicitly, as with all extension DLL usage? The reason is that when the DLL is loaded, the module state that is active will be the state of the calling application. If we initialize in this context, then we will be in for some surprises, as seen in the comments that AppWizard generates when we generate an extension DLL project.

When we move this one line of code into a separate function (in this case GXInitDll), everything falls in place. When the extension DLL calls this function, the module state that is active is that of the regular DLL. Thus, the extension goes into the correct module state, and everything works as expected.

This is an unpleasant situation that should be avoided. You can readily see the reason. When the application calls the grid DLL, the module state is incorrect. This also leads to another situation that is not as easily seen. Suppose one of the exported methods that the regular DLL has calls into the grid. Will that cause problems? The answer is yes. The reason is that when calls are made into the regular DLL, the module state is not automatically set to that of the DLL. MFC has no way of knowing which calls you export. So the burden is on you to make sure that all exported calls are protected with the AFX_MANAGE_STATE macro. This macro simply ensures that the correct module state is set for the duration of that call. This switch is automatically made if this is an MFC exported COM interface method or a message handler. MFC knows and takes care of these entry points. For others, it is our responsibility to do so.

Almost all other cases can be explained in terms of the simple rules and situations that we have seen above. This stuff is not so confusing after all!

In versions of Objective Grid prior to 6.1, it was necessary to call the GXTerminate() function during grid cleanup in order to clean up some grid state information that was maintained in the process's address space. This was true whenever the grid was used in a regular application or any kind of DLL, whether it was a regular DLL, an MFC extension DLL, or an ActiveX control (also known as an OCX).

For Objective Grid versions 6.1 and later, cleanup is handled differently because grid state information is now maintained in the module state local data. If the grid is being used inside of an ActiveX control, you will need to call the GXForceTerminate() function to correctly reset the module state as part of cleaning up your ActiveX control. If you are not using the grid in an ActiveX control, you do not need to do anything at all. The grid will do all necessary cleanup automatically in these cases.

If you are using Objective Grid 6.1 or later, you may safely remove all calls to GXTerminate() that were added when using a previous version of the grid. (Remember, if the grid is inside of an ActiveX control, you must call GXForceTerminate() upon cleanup.) In some cases, leaving the old GXTerminate() calls in will not cause any harm, but in other cases, this will cause problems. To be safe, we recommend that you remove any old GXTerminate() calls from your code.

You will need to protect calls across module states with the AFX_MANAGE_STATE macro. The AFX_MANAGE_STATE macro should be the first call you make in a function, before any memory is assessed or allocated. This a requirement for MFC in general; it has nothing to do with Objective Grid. If you neglect to call AFX_MANAGE_STATE first or if you fail to call it altogether, you might experience unpredictable behavior. For example, the control will assert when the mouse cursor is moved across any of the headers because it won't get the correct resource handle.

If you call mfc42.dll from a regular MFC DLL (instead of from an MFC program or extension DLL), because the global variables in which it stores data aren’t synchronized, you’ll need to insert the following as the first line of all exported functions in your regular DLLs: