Online document ___________________________________________________________________________ ObjectWindows dynamic link libraries CONTENTS ___________________________________________________________________________ ObjectWindows dynamic Macro expansion . . . . . . 7 link libraries 1 Pointers and typedefs . . . 7 C++ DLLs . . . . . . . . . . . . . 1 Building a shared class in a Writing DLL functions . . . . . 1 DLL . . . . . . . . . . . . . 10 LibMain and WEP . . . . . . . 2 Using a shared class . . . . 10 DLL-specific functions . . . . 3 Calling an ObjectWindows DLL from Exporting DLL functions . . . . 3 outside ObjectWindows . . . . . 11 Calling DLL functions . . . . . 4 Using ObjectWindows as a DLL . . 12 ObjectWindows DLLs . . . . . . . 4 The module object . . . . . . 5 Shared classes . . . . . . . . . 6 Declaring and defining a shared class . . . . . . . . . . . . 6 A dynamic-link library (DLL) is a library of functions whose references are resolved at run time rather than at compile time. DLL functions are dynamically linked to a calling application. Each application using statically linked code has its own copy of the code. The code for functions defined in a DLL is shared by all calling applications; only one copy is placed in memory. Defining code shared by a group of applications in a DLL therefore reduces the size of the .EXEs of the calling applications. You might want to define complex windowing behavior, shared by a group of your applications, in an Object- Windows DLL. In this chapter, you'll learn how to write and use an ObjectWindows DLL. You'll also learn how to use the ObjectWindows dynamic-link library (OWL31.DLL). =========================================================================== C++ DLLs =========================================================================== DLLs can contain ordinary functions or a combination of functions and exported C++ classes. First, we'll examine DLLs in the context of a library of ordinary functions. This section contains an overview of Borland C++ DLLs; you'll learn how to write, export, and call a DLL function using Borland C++. Writing DLL functions ======================================================= Windows requires that two functions be defined in every DLL: LibMain and WEP (Windows Exit Procedure). - 1 - ------------------ You must supply the LibMain function, which is the main LibMain and WEP entry point for a Windows DLL. Windows calls LibMain once, when the library is first loaded. LibMain ------------------ initializes the DLL; this initialization depends almost entirely on the particular DLL's function, but might include the following tasks: o unlocking the data segment with UnlockData, if it has been declared as MOVEABLE o setting up global variables for the DLL, if it uses any Note The DLL startup code C0Dx.OBJ initializes the local heap automatically. The following parameters are passed to LibMain: int PASCAL LibMain(HANDLE hInstance, WORD wDataSeg, WORD cbHeapSize, LPSTR lpCmdLine) HANDLE, WORD, and o hInstance is the instance handle of the DLL. LPSTR are defined in windows.h. o wDataSeg is the value of the data segment (DS) register. o cbHeapSize is the size of the local heap specified in the module definition file for the DLL. o lpCmdLine is a far pointer to the command line specified when the DLL was loaded. This is almost always null, because typically DLLs are loaded automatically without parameters. It is possible, however, to supply a command line to a DLL when it is loaded explicitly. The return value for LibMain is either 1 (successful initialization) or 0 (unsuccessful initialization). Windows will unload the DLL from memory if the value is 0. WEP is the exit point of a DLL; Windows calls it prior to unloading the DLL. This function is not necessary in a DLL (because the Borland C++ run-time libraries provide a default one), but can be supplied by the writer of a DLL to perform any cleanup of the DLL before it is unloaded from memory. Under Borland C++, WEP does not need to be exported. This is the prototype for WEP: int FAR PASCAL WEP (int nParameter) - 2 - o nParameter is either WEP_SYSTEMEXIT (all of Windows shuts down) or WEP_FREE_DLL (just this DLL is unloaded). WEP returns 1 to indicate success. Note that Windows currently doesn't use this return value. The additional functions defined in your DLL depend on ------------------ the services your DLL provides. When writing functions DLL-specific that will be called from an application, you need to functions keep these things in mind: ------------------ o Make calls to DLL functions far calls, and make pointers specified as parameters and return values far pointers. This is because a DLL has different code and data segments than the calling application. o Static data defined in a DLL is global to all calling applications. Global data set by one caller can be accessed by another. If you need data to be private for a given caller, you need to dynamically allocate and manage the data yourself. Exporting DLL functions ======================================================= After writing your DLL functions, you must export the functions that you want available to a calling application. There are two steps involved: compiling your DLL functions as exportable functions and exporting them. You can do this in the following ways: o If you flag a function with the _export keyword, it's compiled as exportable and is then exported. o If you don't flag a function with _export and you use the -WD command-line switch or the Windows DLL All Functions Exportable IDE option when compiling, the function is compiled as exportable. However, the function only gets exported if you also list it in the EXPORTS section of the module definition (.DEF) file. o If you add the _export keyword to a class declaration, the entire class (data and function members) will be compiled as exportable and exported. - 3 - Calling DLL ======================================================= functions You call a DLL function within an application just as you would call a function defined in the application itself. However, you must import the DLL functions that your application calls. There are two ways to import a DLL function: 1. You can add an IMPORTS section to the calling application's module definition (.DEF) file and list the DLL function as an import. 2. You can link an import library that contains import information for the DLL function to the calling application. (Use IMPLIB to make the import library.) When your application is executed, the .DLL files for the DLLs that it calls must be in the current directory, on the path, or in the Windows or Windows system directory; otherwise, your application won't load. ObjectWindows DLLs ======================================================= ObjectWindows DLLs differ from ordinary DLLs in that, with ObjectWindows DLLs, you export cla...
mek4test