SAMPLE: Multiple Application Instance Data in a DLL

• Microsoft Windows Software Development Kit (SDK) for Windows versions 3.1 and 3.0

SUMMARY

DLLINST is a file in the Microsoft Software Library that demonstrates how a dynamic-link library (DLL) can interact with more than one application at a time with each interaction independent from the others. To illustrate the independence of each interaction, the DLL maintains separate data for each application instance. This article discusses the techniques used in DLLINST.

MORE INFORMATION

When a DLL receives a call from an application, nothing in the call specifies the application instance involved. Because instance information is required to ensure that each interaction is independent, the application's instance is one of the parameters for the interface functions provided by the DLL.

If the DLL contains global data that are used by each application instance, the following techniques help avoid data access conflicts:

1. Use a flag as a mutual-exclusion semaphore. This will ensure that only one application instance can use the DLL at any given time.

2. Use additional storage in the DLL to provide each application instance with its own data area. One way to implement this is through a list of records that is indexed by the instance.

Download DLLINST.EXE, a self-extracting file, from the Microsoft Software Library (MSL) on the following services:

• Microsoft Download Service (MSDL)

        Dial (206) 936-6735 to connect to MSDL
        Download DLLINST.EXE (size: 27397 bytes) 
  

• Internet (anonymous FTP)

        ftp ftp.microsoft.com
        Change to the \SOFTLIB\MSLFILES directory
        Get DLLINST.EXE (size: 27397 bytes) 
  

Multiple instances of the DLLINST application can call into the DLGDLL DLL to demonstrate the techniques.

Note that the application passes hInst (the application's instance handle) to the DLL through the call to the TestDLLDlg function in MainWndProc.

As an alternative, the DLL can call the GetCurrentTask function to determine which instance is calling. This eliminates the requirement that hInst be passed in. If the DLL uses hWnd, the DLL can maintain a separate data area for each window rather than for each instance. This technique might be useful for a Multiple Document Interface (MDI) application.

DLLINST "unregisters" each application before it returns, which frees the buffer for use by another instance. This prevents data from persisting across calls to the DLL. Although the DLL can recognize and register a new instance that calls the DLL for the first time, to implement persistent data, each instance must call a cleanup function in the DLL before terminating. This prevents a possible problem where an instance terminates and its handle is reused by a new instance.

In Windows version 3.1, the TOOLHELP DLL provides the NFY_EXITTASK notification to inform a callback function that a task terminated. The DLL can use this to unregister an application, even if it terminated abnormally. The callback function can use the GetCurrentTask and TaskFindHandle functions to determine if the terminating task has called the DLL.

The following relevant function is in the DLLINST.C file:

MainWndProc    Processes messages for the application. Calls the
               TestDLLDlg function in DLGDLL to display a dialog box
               that edits data for a calling instance.

DlgProc        Processes messages for DLL dialog box and writes
               DlgItemText to the correct buffer.

TestDLLDlg     Called by each instance of the application to display a
               dialog box.