Calling External APIs

You might need to access external APIs from within LabVIEW code. Most often, you access external APIs to obtain functionality that the operating system provides. Normally, you can use the LabVIEW Call Library Function Node to accomplish this goal. You must provide the following information to the Call Library Function Node to access external APIs from within LabVIEW code:

• Function name as it appears in the library
• Function prototype
• Library or module in which the function resides
• Calling conventions of the function
• Thread-safe status of the function

Caution��Do not specify the location of a system shared library, such as kernel32.dll, by path. Because LabVIEW automatically includes by-path shared libraries in build specifications, you might distribute a system shared library to another computer inadvertently. Redistributing some shared libraries, such as kernel32.dll, might cause the target computer to crash. Therefore, always specify system shared libraries by name.

Common Pitfalls with the Call Library Function Node

The function reference documentation for any API should provide most of the information that the Call Library Function Node requires. However, you should keep in mind the common errors listed in this section.

Note��Configure the Call Library Function Node to return an error when some of the pitfalls described below occur by selecting the Maximum or Default control on the Error Checking tab of the Call Library Function dialog box.

Incorrect Function Name

Your library call can fail when the name of the function as it appears in the library is different than is expected. Usually this error occurs due to function name redefinition, or to function name decoration, as in the following examples:

• Redefinition�This pitfall appears when an API manufacturer uses a define mechanism, such as #define directive in ANSI C, to define an abstracted function name to one of many functions present in the library, based on some external condition such as language or debug mode. In such cases, you can look in the header ( .h) file for the API to determine whether a #define directive redefined the name of a function you want to use.
• Function Name Decoration�This pitfall appears when certain functions have their names decorated when they are linked. A typical C compiler tracks name decoration, and when it looks for a function in a shared library, it recognizes the decorated name. However, because LabVIEW is not a C compiler, it does not recognize decorated names. If you suspect that function name decoration is causing difficulty, inspect the shared library�s exported functions. If the function name that appears in the function prototype section has characters such as @ appended to it, the function was decorated when the DLL was built. This is most common with C++ compilers.
  
  In LabVIEW, the Function name control in the Call Library Function dialog box is a pull-down menu where you can access a list of all functions within the library you have selected. In addition, most operating systems have a utility you can use to view a library�s exports, for example, QuickView on the Windows operating system and the nm command on most Linux systems.
  
  If the Function name list contains entries but the function you want to call does not appear in the list, the most likely reason is that the function has not been exported. Refer to the documentation for your compiler for information about how to mark functions for export.

Data Types

Your library call can fail when you do not use the correct data types. LabVIEW only supports basic numeric data types and C strings. Also, you can select Adapt to Type from the Type pull-down menu of the Call Library Function dialog box and direct LabVIEW to pass its own internal data types for a given parameter. You might encounter the following specific problems:

• Non-Standard Data Type Definitions�Frequently, other APIs use non-standard definitions for data types. For example, instead of using char, short, and long, the Windows API uses BYTE, WORD, and DWORD. If an API that you are using makes use of such data types, you need to find the equivalent basic C data type so that you can properly configure the Call Library Function Node.
• Structure and Class Data Types�Some APIs have structure and, in the case of C++, class data types. LabVIEW cannot use these data types. If you need to use a function that has a structure or class as an argument, you should write a shared library wrapper function that takes as inputs the data types that LabVIEW supports and that appropriately packages them before LabVIEW calls the desired function.
• ActiveX Objects�If you want to call a shared library that contains ActiveX objects, use the Automation Open function with the Property Node and the Invoke Node instead of the Call Library Function Node.

(Windows) Refer to the labview\examples\Connectivity\Libraries and Executables\Libraries and Executables.lvproj for an example of using data types in shared libraries.

Open example� � Find related examples

Constants

Your library call can fail when your external code uses identifiers in place of constants. Many APIs define identifiers for constants to make the code easier to read. LabVIEW must receive the actual value of the constant rather than the identifier that a particular API uses. Constants are usually numeric, but they might also be strings or other values. To identify all constants, inspect the header file for the API to find the definitions. The definition might either be in #define statements or in enumerations, which use the enum keyword.

Calling Conventions

Your library call can fail when certain operating systems use calling conventions other than the C calling convention and the Standard (__stdcall) calling convention. The calling convention defines how data is passed to a function and how clean up occurs after the function call is complete. The documentation for the API should say which calling convention(s) you must use. The Standard (__stdcall) calling convention is also known as the WINAPI convention, or the Pascal convention.

Use of calling conventions other than the C or Standard calling conventions frequently causes the failure of library calls in LabVIEW because those other calling conventions use an incompatible method for maintaining the stack.