|
|
|||||||||||||||
How the VM Chooses Between ANSI and UnicodeThe simple MessageBox example that starts this document glosses over a subtle, but important fact: USER32 does not export a function named MessageBox. Because the MessageBox function takes a string, it (like all Win32 functions that deal with strings) must exist in two versions: an ANSI version and a Unicode version (named MessageBoxA and MessageBoxW, respectively). When you code a call to MessageBox in C or C++, the MessageBox "function" you call is actually a macro that expands to either MessageBoxA or MessageBoxW, depending on whether the UNICODE macro is defined. Calling the ANSI Version of a DLL FunctionBy default, the Microsoft Win32 VM for Java assumes that the ANSI version of MessageBox is the one that is needed. If you import the MessageBox function using @dll.import (without a modifier) as follows, /** @dll.import("USER32") */ static native int MessageBox(int hwnd, String text, String title, int style); the Microsoft VM will go through the following steps.
Calling the Unicode Version of a DLL FunctionSuppose, instead, you wanted to call the Unicode version of MessageBox. You can do this by using the unicode modifier with the @dll.import directive: /** @dll.import("USER32",unicode) */ static native int MessageBox(int hwnd, String text, String title, int style); Since the unicode modifier is present, the Microsoft VM will go through the following steps.
Calling the Optimal Version of a DLL FunctionUnfortunately, neither of these situations is an ideal way to invoke the Win32 functions. Using the default ANSI mode allows your code to run on any Win32 platform, but causes unnecessary performance penalties on fully Unicode systems such as Microsoft® Windows® NT. Using the unicode modifier removes the performance penalty but restricts you to running on systems that implement the Unicode API. Fortunately, you can use the auto modifier with the @dll.import directive to call the optimal version of a DLL function based on the host operating system. Using the auto modifier gives you the best of both worlds. The following example shows how to call the optimal version of the MessageBox function. /** @dll.import("USER32",auto) */ static native int MessageBox(int hwnd, String text, String title, int style); When the auto modifier is present, the Microsoft VM determines at run time whether the underlying platform supports the Unicode APIs. If Unicode is supported, the Microsoft VM acts as if the unicode modifier had been specified. Otherwise, the Microsoft VM behaves as if the ansi modifier had been specified. Thus, the auto modifier allows you to generate a single binary which runs well on both ANSI and Unicode Windows systems using the optimal API set available on the given platform. In general, the auto modifier should be used whenever you call Windows API functions. If you are calling your own DLLs, select either ansi (the default) or unicode depending on your needs. Here are the details of how the Microsoft VM decides whether to use ANSI or Unicode when you use the auto modifier.
It is not necessary to set the DllImportDefaultType registry key yourself. It exists primarily so that the installation program can set the appropriate choice on future Windows platforms. You can programatically query the preferred mode on your platform by reading the com.ms.dll.DllLib.systemDefaultCharSize field. This field will be set to 1 on ANSI systems, 2 on Unicode systems. The ansi, unicode, and auto modifiers can also be used with the @dll.struct directive.
|
© 1998 Microsoft Corporation. All rights reserved. Terms of use. |