Chapter 2 Shared Libraries (DLLs)

Figure 2-4. VI That Calls Hardware

Example 3: Call the Win32 API

LabVIEW users frequently want to access the 32-bit Windows platform API (the Win32 API). In Win32 environments, various DLLs permit your application to interact with the operating system and with the graphical user interface. Because the API offers thousands of functions, programmers must rely on the documentation for the Microsoft Software Development Kit (SDK). Microsoft Visual Studio products give you access to the SDK documentation. You can also access this information at the Microsoft Web site on the Internet.

Note Instead of using the Windows DLL as described in this example, you could easily create this message box in LabVIEW.

In this example you call the Windows MessageBox function, a function which illustrates several of the typical complexities of the Win32 API. MessageBox is a simple SDK function that presents a small dialog box with a message, and has the following prototype:

int MessageBox( HWND hWnd, // handle to owner window LPCTSTR lpText, // text in message box LPCTSTR lpCaption, // message box title UINT uType // message box style );

Notice the non-standard data types like HWND, and LPCTSTR. The Win32 API uses hundreds of data types in the SDK, and very few of them are standard C data types. However, many of the non-standard data types are merely aliases for standard C data types. The API uses the aliases to identify the context of a particular data type. The data types in the preceding prototype correspond to the following standard C data types:

Chapter 2 Shared Libraries (DLLs)

Table 2-1. Mapping Win32 Data Types to Standard C Data Types

In order to properly call the MessageBox function in LabVIEW, you need to identify the equivalent LabVIEW data types, which you can usually infer from the C data types. Mapping LPCTSTR and UINT to LabVIEW is straightforward: LPCTSTR is a C String and UINT is a U32.

Mapping HWND is more complex. The preceding table shows HWND to be a double pointer to an integer. However, inspection of the function shows that MessageBox uses HWND merely as a reference number that identifies the owner of the window. Because of this fact, you do not need to know the integer value for which the HWND is a handle. Instead, you need to know the value of the HWND variable itself. Because it is a double pointer, and hence a pointer, you can be treat it as an unsigned 32-bit integer, or, in LabVIEW terms, a U32. It is very common to run across handles like HWND in the Win32 SDK. In LabVIEW you are almost always interested in the handle itself, and not the data to which it points. Therefore, you can usually treat handles—whose names always begin with the letter H in the Win32 API—as U32.

If the SDK documentation does not make clear what C data type corresponds to a Win32 type, search windef.h for the appropriate

#define or typedef statement.

Table 2-2. Mapping Win32 Data Types to LabVIEW Data Types

Constants

This section presents methods for finding the numerical values of constants in the Win32 API, using MessageBox constants as examples. The following table lists selected constants for MessageBox.

Chapter 2 Shared Libraries (DLLs)

Table 2-3. Selected Constants for MessageBox

In Visual Studio, programmers do not use the actual values of constants. In LabVIEW, however, you need to pass the actual numeric value of the constant to the function. You find these values in the header files that come with the SDK. The SDK online documentation normally lists the relevant header file at the bottom of the help topic for a given function. For MessageBox, the SDK online documentation has the following statement:

Header: Declared in winuser.h

The header file named in this statement usually declares the constants. Searching through that header file you should be able to find a #define statement or an enumeration that assigns the constant text a value. winuser.h defines values for some of the MessageBox constants as follows:

#define MB_OK 0x00000000L

#define MB_ABORTRETRYIGNORE 0x00000002L #define MB_ICONWARNING MB_ICONEXCLAMATION

Thus, MB_OK has the decimal value 0, MB_ABORTRETRYIGNORE has the decimal

value 2, and MB_ICONWARNING is defined as MB_ICONEXCLAMATION.

Elsewhere in winuser.h you find the following statement defining

MB_ICONEXCLAMATION.

#define MB_ICONEXCLAMATION 0x00000030L

A hexadecimal value of 30 translates to a decimal value of 48.

Tip Keep in mind that constants in the SDK often are used in bitfields. A bitfield is usually a single integer in which each bit controls a certain property. The uType parameter in MessageBox is an example of a bitfield. Often, you can combine multiple constants in order to set multiple properties through one parameter. In order to combine these constants,

Chapter 2 Shared Libraries (DLLs)

you use a bit-wise OR operation ( | ). For example, to set the MessageBox to have a warning icon and the buttons Abort, Retry, and Ignore, you pass the following value of uType to MessageBox:

MB_ABORTRETRYIGNORE | MB_ICONEXCLAMATION = 0x32

In LabVIEW, you combine multiple constants by wiring integer types to the OR operator.

Figure 2-5. Combining Function Constants in LabVIEW

Determining the Proper Library and Function Name

Before you can configure this call to the Win32 API, you must identify the DLL that contains MessageBox and the specific name of MessageBox within the DLL. Refer to the description of MessageBox in the documentation that comes with your SDK or search for “MessageBox” on the Microsoft Web site. A Requirements section follows the function description for MessageBox and contains the following information:

“Requirements:

Windows NT: Requires version 3.1 or later.

Windows: Requires Windows 95 or later.

Windows CE: Requires version 1.0 or later.

Header: Declared in winuser.h.

Import Library: Use user32.lib.

Unicode: Implemented as Unicode and ANSI versions on Windows and Windows NT.”

The Import Library line names the static library user32.lib that you need to link to in order to build a program in the C language. Every static library in the SDK has a dynamic counterpart that has the same filename, but has a .dll extension instead of a .lib extension. This DLL that contains the actual implementation of the desired function. So, in this case you know that user32.dll contains MessageBox.