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:

#define DRICOMPANION_API __declspec(dllexport)
#define DRICOMPANION_API __declspec(dllimport)

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


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 {

                           DWORD dwValue) PURE;
                           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 : Defines the entry point for the DLL application.

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

                       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:
    return TRUE;

// This is an example of an exported variable.

// 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

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

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

Understanding the DLL Header File

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 you can 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.

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

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 and CodeGuru, she has written several books, including Making Win 32 Applications Mobile.



  • There are no comments yet. Be the first to comment!

Leave a Comment
  • Your email address will not be published. All fields are required.

Top White Papers and Webcasts

  • Live Event Date: October 29, 2014 @ 11:00 a.m. ET / 8:00 a.m. PT Are you interested in building a cognitive application using the power of IBM Watson? Need a platform that provides speed and ease for rapidly deploying this application? Join Chris Madison, Watson Solution Architect, as he walks through the process of building a Watson powered application on IBM Bluemix. Chris will talk about the new Watson Services just released on IBM bluemix, but more importantly he will do a step by step cognitive …

  • Protecting business operations means shifting the priorities around availability from disaster recovery to business continuity. Enterprises are shifting their focus from recovery from a disaster to preventing the disaster in the first place. With this change in mindset, disaster recovery is no longer the first line of defense; the organizations with a smarter business continuity practice are less impacted when disasters strike. This SmartSelect will provide insight to help guide your enterprise toward better …

Most Popular Programming Stories

More for Developers

Latest Developer Headlines

RSS Feeds