Understanding the DLL Header File

Developer.com content and product recommendations are editorially independent. We may make money when you click on links to our partners. Learn More.

In the last lesson, you explored the constraints that govern remote function invocation. Now, you’ll get down to the business of creating a DLL to contain your own remotely invoked function. The key to this job is creating the correct header file.

The most important job of the header file in the example that follows is to make sure that the function you want to expose to CeRapiInvoke() is exported properly. Here are two things to note:

• You want to make sure it is treated as a C-style symbol.
• You must be scrupulously careful about the parameter list and their types.

Notice this generated code at the top of the header file:

#ifdef DRICOMPANION_EXPORTS
#define DRICOMPANION_API __declspec(dllexport)
#else
#define DRICOMPANION_API __declspec(dllimport)
#endif

These conditionally applied macros do two things. First, they correctly apply the __declspec attribute based on whether the header is being included in the compilation of a DLL (which is exporting functions for use by other modules) or a module that is importing the same functions. The fragment

__declspec(dllexport)

explicitly defines the calling convention and interface to the function that it modifies. Declaring functions as dllexport eliminates the need for a module-definition (.DEF) file, and makes the function available to be called by another application (as in the case at hand) or by another DLL. In the code below, the DRICOMPANION_API macro applies the __declspec(dllexport) modifier to the function you export for use by CeRapiInvoke().

Recall from the typedef at the beginning of this section that one of the parameters to an invokable function is of type IRAPIStream**. To properly type this parameter, you must first add a declaration for the interface and its data structures. The following lines provide the necessary declarations:

// Not included in a server-side include file
typedef enum tagRAPISTREAMFLAG {
    STREAM_TIMEOUT_READ
} RAPISTREAMFLAG;

DECLARE_INTERFACE_ (IRAPIStream,  IStream)
{
    STDMETHOD(SetRapiStat)(THIS_ RAPISTREAMFLAG Flag,
                           DWORD dwValue) PURE;
    STDMETHOD(GetRapiStat)(THIS_ RAPISTREAMFLAG Flag,
                           DWORD *pdwValue) PURE;
};

Finally, and most critically, you must include a prototype that exactly matches the expectations of CeRapiInvoke() and properly exports the function.

//------------------------------------------------------------------
// Function prototypes declared as exports from the DLL.

DRICOMPANION_API INT LaunchViewer (DWORD cbInput, BYTE *pInput,
                                   DWORD *pcbOutput, BYTE **ppOutput,
                                   IRAPIStream *pIRAPIStream);

The implementing source code for the DLL is surprisingly brief. Your only real interest here is the LaunchViewer() function.

DRICompanion.cpp
// DRICompanion.cpp : Defines the entry point for the DLL application.
//

#include "stdafx.h"
extern "C"
{
#include "DRICompanion.h"
}


BOOL APIENTRY DllMain( HANDLE hModule,
                       DWORD  ul_reason_for_call,
                       LPVOID lpReserved
                     )
{
    switch (ul_reason_for_call)
    {
        case DLL_PROCESS_ATTACH:
        case DLL_THREAD_ATTACH:
        case DLL_THREAD_DETACH:
        case DLL_PROCESS_DETACH:
            break;
    }
    return TRUE;
}


// This is an example of an exported variable.
DRICOMPANION_API int nDRICompanion=0;

// This is an example of an exported function.
DRICOMPANION_API int fnDRICompanion(void)
{
    return 42;
}

// This is the constructor of a class that has been exported.
// see DRICompanion.h for the class definition
CDRICompanion::CDRICompanion()
{
    return;
}

DRICOMPANION_API int LaunchViewer(DWORD cbInput, BYTE *pInput,
                                  DWORD *pcbOutput, BYTE **ppOutput,
                                  IRAPIStream *pIRAPIStream)
{
    PROCESS_INFORMATION piHtmlViewer;

    CreateProcess( TEXT("MyHtmlViewer.exe"),
                   NULL, NULL, NULL, FALSE,
                   0, NULL, NULL, NULL,
                   &piHtmlViewer );
    return 0;
}

Notice that LaunchViewer() includes but a single call: CreateProcess(). To my way of thinking, this bit of logic epitomizes the elegance of CE’s remote procedure call functionality. While there are very strict limitations on how you can invoke a function, the function you invoke is virtually unlimited in its capability because it can in turn create processes. In a nutshell, the whole device is your oyster once you successfully invoke the first function.

Here are the parameters to CreateProcess():

BOOL CreateProcess( LPCTSTR lpApplicationName,
                    LPTSTR lpCommandLine,
                    LPSECURITY_ATTRIBUTES lpProcessAttributes,
                    LPSECURITY_ATTRIBUTES lpThreadAttributes,
                    BOOL bInheritHandles,
                    DWORD dwCreationFlags,
                    LPVOID lpEnvironment,
                    LPCTSTR lpCurrentDirectory,
                    LPSTARTUPINFO lpStartupInfo,
                    LPPROCESS_INFORMATION lpProcessInformation );

Notice that like CeRapiInvoke(), CreateProcess() provides a means by which to pass data to the function being invoked (via a command line). By using these functions in concert, you create a fundamentally unlimited integration of the CE and desktop Windows worlds.

Download the source code file for this article here.

Looking Ahead

In the next lesson, you’ll complete this application system by creating an HTML viewer control on the CE device. Once animated, this control allows you to pass any data that is capable of being rendered using HTML tags from the desktop device to the CE device. The power and elegance of this approach can hardly be overstated. Not only does it provide enormous flexibility, it largely insulates the application designer from the vagaries of various CE platforms.

About the Author

Nancy Nicolaisen is a software engineer who has designed and implemented highly modular Windows CE products that include features such as full remote diagnostics, CE-side data compression, dynamically constructed user interface, automatic screen size detection, and entry time data validation.

In addition to writing for Developer.com, she has written several books, including Making Win 32 Applications Mobile.

# # #