This chapter describes SilverStream's native DLL support. It gives an overview of DLL integration with SilverStream and explains how to call DLLs directly from SilverStream applications.
This chapter covers the following topics:
In some situations, a SilverStream application needs to be able to call native code. SilverStream applications can use the Java Native Interface (JNI) to call native methods. However, JNI is a low-level interface that requires that you write additional C or C++ code. Writing good JNI code is difficult.To simplify access to native code, SilverStream lets you use either of the following programming techniques:
The remainder of this chapter describes how to call native DLL functions directly. For information about invoking the services of COM objects, see Using COM Objects.
A DLL is a Windows dynamic link library that contains a set of machine-language procedures. DLLs provide separate entry points for functions that can be called by a process.
SilverStream 3.0 provides a mechanism for calling DLLs directly from Java without writing any native code. The DllLib class in the com.sssw.rt.com package has several static methods that let you load a DLL into memory, get a function pointer, and make a call to the function. DllLib also provides services for memory management and for Java to C parameter conversion.
CAUTION! By accessing DLLs directly, you can expand the capabilities of your applications in many ways. However, you need to use a much lower level interface to access a DLL than to access a COM object. Therefore, you must exercise caution when you write Java code to access a DLL. When you access a DLL from Java, you are able to manipulate C pointers directly. In addition, because SilverStream does not provide compile time checking for code that makes native calls, your code may not be type-safe. Even small typographical errors can result in runtime errors that will bring down the SilverStream Server. For example, if you misspell the name of the DLL or function you want to access (or use the wrong case), you will crash the server.
DllLib provides many of the same services as J/Direct, a Microsoft facility that lets you call functions in a Win32 DLL. On the positive side, DllLib is not tied directly to the Microsoft virtual machine and compiler, whereas J/Direct is. On the negative side, DllLib requires that you write Java code to access a DLL, whereas J/Direct lets you use compiler directives.
Although you need to have a good understanding of C programming concepts to use DllLib, you do not need to write additional C code to access a native DLL, as you would if you used the Java Native Interface (JNI). This greatly simplifies native DLL access. However, code that relies on DllLib is, in general, more error-prone than code that uses JNI and will run on Windows NT only.
Once you've identified the DLL you want to access from a SilverStream application, you can begin writing Java code to access the DLL. You can access a native DLL from any SilverStream business object, form, or page.
To call a DLL function from a business object, form, or page, you need to write Java code to perform these operations:
DLLGetHandle().DLLGetMethod().DllLib provides several functions for parameter conversion.
allocCoTaskMem() or allocHGlobal().call(). You need to pass the pointer returned by DLLGetMethod() to the call() method.freeCoTaskMem() or freeHGlobal().DLLFreeHandle().
To allow you to work with native Windows pointers in the Java context, DllLib represents pointers as integers.
DllLib provides several functions for converting Java objects to native memory. The following table describes these functions.
DllLib also provides functions for converting native objects to Java. The following table describes these functions.
In addition to these functions, DllLib provides functions that let you read and write values in a native memory block.
To pass a structure as a parameter to a native DLL function, you need to know the structure's layout. In particular, you need to know the offset of each field within the structure. To read values from and write values to the structure, you need to specify the offset of each field you want to access.
To pass a structure, you need to write Java code to perform these operations:
allocCoTaskMem() or allocHGlobal(). write() functions (write1(), write2(), write4(), or writeN(), which is inherited from AgCom).read() functions available with DllLib (read1(), read2(), read4(), or readN(), which is inherited from AgCom).
To simplify the process of calling many of the functions in the Win32 API, SilverStream provides a class called Kernel32 that maps the functions in the kernel32.dll to Java functions. This class removes the need to call the DLLGetHandle() and DLLGetMethod() functions to load the DLL and get a handle to the function.
To use the kernel32 class to call a DLL function, you need to write Java code to perform these operations:
getKernelProc() static method on the Kernel32 class, passing the name of the function in kernel32.dll that you want to call. The getKernelProc() method returns a pointer to the function in kernel32.dll.
call() method. You need to pass the pointer returned by getKernelProc() to the call() method.
The following code makes a call to the GetCurrentProcessID() function in kernel32.dll. For the purpose of illustration, it shows how you would use DLLGetHandle() and DLLGetMethod() to load the DLL and get a handle to the function. In Example 2, you will see how to use the Kernel32 class to call a kernel32.dll function.
The SilverStream function getPID() performs these operations:
DLLGetHandle().GetCurrentProcessID() function in kernel32.dll by calling DLLGetMethod().call().DLLFreeHandle().
Here's the code for the getPID() function:
public int getPID() {
//Get our DLL handle
int hKern = DllLib.DLLGetHandle("kernel32.dll");
//Get the function pointer
int pp_getpid =
DllLib.DLLGetMethod(hKern,"GetCurrentProcessId");
//DWORD GetCurrentProcessId(VOID)
int ans = DllLib.call(pp_getpid);
//Unload DLL
DllLib.DLLFreeHandle(hKern);
return ans;
}
The following code makes a call to the GetEnvironmentVariableA() function in kernel32.dll. It demonstrates several of the parameter handling services that DllLib provides. In addition, it shows how to use the Kernel32 class to get a handle to a method in a DLL.
The SilverStream function getEnvVar() performs these operations:
GetEnvironmentVariableA() function in kernel32.dll by calling the getKernelProc() static method on Kernel32.stringToPtrAnsi().allocCoTaskMem(). call() method.ptrToStringAnsi().freeCoTaskMem().
Here's the code for the getEnvVar() function:
public String getEnvVar() {
int pp_getenv =
Kernel32.getKernelProc("GetEnvironmentVariableA");
int namebuf = DllLib.stringToPtrAnsi("Path");
int valbuf = DllLib.allocCoTaskMem(4096);
DllLib.call(pp_getenv, namebuf, valbuf, 4096);
String value = DllLib.ptrToStringAnsi(valbuf);
DllLib.freeCoTaskMem(valbuf);
DllLib.freeCoTaskMem(namebuf);
return value;
}