Understanding the DLL Header File

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;
}