Getting Started

This section provides a message box application that uses @dll.import. Then, the syntaxes of the @dll.import, @dll.struct, and @dll.structmap compiler directives are presented.

Example

Using Microsoft® J/Direct™ to call Win32 DLLs from Java code is straightforward. Here is a short Java application that displays a message box.

class ShowMsgBox {
   public static void main(String args[])
   {
      MessageBox(0, "It worked!", 
                 "This messagebox brought to you from Java", 0);
   }
	   
   /** @dll.import("USER32") */
   private static native int MessageBox(int hwndOwner, String text, 
                                        String title, int fuStyle);
} 

The @dll.import directive tells the compiler that the MessageBox method will link to the Win32 USER32.DLL using the J/Direct protocol rather than the Raw Native Interface protocol supported in previous versions. In addition, the Microsoft Win32 VM for Java provides automatic type marshaling from String objects to the null-terminated strings expected by C.

You may have noticed that it is not necessary to indicate whether the ANSI MessageBox (MessageBoxA) function or the Unicode MessageBox function (MessageBoxW) should be called. In the previous example, the ANSI version is always called. The How the VM Chooses Between ANSI and Unicode section explains how to use the auto modifier to call the optimal version of the function, depending on the version of Microsoft® Windows® that is hosting the application.

Quick Syntax Reference

The following sections give a quick reference to the @dll.import, @dll.struct, and @dll.structmap directives. For each directive, the required syntax is shown and explained.

Syntax for @dll.import

Syntax for @dll.struct

Syntax for @dll.structmap

Be aware that white space within @dll directives can cause syntax errors. You can put white space between the directive and the comment tags, but not within the directive itself. For example, the following directive would cause a syntax error.

  /**@dll.import("MyDll",   auto)*/

But this one would not cause an error.

  /**       @dll.import("MyDll",auto) */

Syntax for @dll.import

The @dll.import directive should be placed just above the method declaration. The syntax of the directive is as follows.

  /**@dll.import("LibName",<Modifier>)*/
  ...method declaration...;

LibName is the name of the DLL that contains the function you want to invoke. Modifier is optional, and the value that you should supply for it varies depending on your needs. In the method declaration, you can use the function name that the DLL uses, or you can give the method a different name by using aliasing (see Aliasing (Method Renaming)). The Java data types that you choose for the parameters and for the return value of the method should be types that map to the types of the DLL function parameters and return value. See How Data Types are Marshaled for more information about how Java data types map to native types.

The following table presents the @dll.import syntax for several situations that are described in this article.

Situation	Required Syntax	Explanation
Calling Win 32 DLLs	/**@dll.import("LibName")*/
Calling OLE APIs	/**@dll.import("LibName",ole)*/
Aliasing	/**@dll.import("LibName",entrypoint="DLLFunctionName")*/	In the method declaration, use the Java name that you selected.
Linking by Ordinal	/**@dll.import("LibName",entrypoint="#ordinal")*/	"ordinal" is a 16-bit integer, specified in decimal, that indicates the DLL function that you are importing.

Syntax for @dll.struct

The @dll.struct directive should be placed just above the class declaration. The syntax of @dll.struct is as follows.

  /**@dll.struct(<LinkTypeModifier>,<pack=n>)*/
  ...class declaration...;

LinkTypeModifier tells the compiler whether fields of type String and char represent ANSI or Unicode characters in native format. LinkTypeModifier can be ansi, unicode, or auto. If you do not specify LinkTypeModifier, ansi is used by default. The How the VM Chooses Between ANSI and Unicode section can help you learn more about which value to use for LinkTypeModifier.

You can also specify pack=n to tell the compiler to set the packing size of the structure to either 1,2,4, or 8, depending on the value you specify for n. If you omit the pack=n modifier, the packing size is set to 8 by default. See the Structure Packing section of this article for more information on setting the packing size.

Within the class declaration, you need to supply fields whose Java types map to the types of the fields in the native structure, in the order they occur in the native structure. See the section on Correspondence Between Types Inside Structures for information about choosing the data types of the fields.

The following table describes the syntax for several situations in which you might use the @dll.struct directive.

Situation	Required Syntax	Explanation
Declare a Structure	/**@dll.struct()*/	When you do not specify LinkTypeModifier, char or String fields are assumed to represent ANSI characters.
Set a Structure's Packing Size	/**@dll.struct(pack=n)*/	n can be 1,2,4, or 8.
Declare a Structure that has a Field of Type char	/**@dll.struct(ansi)*/	The character field represents an ANSI character.
Declare a Structure with a Field of Type String and Set the Packing Size	/**@dll.struct(unicode,pack=n)*/	The String fields will be in Unicode format, and the packing size is set to 1,2,4, or 8, depending on the value of n.

Syntax for @dll.structmap

The @dll.structmap directive is used to declare fixed-size strings and arrays embedded in structures. It should be placed within a structure that is declared with @dll.struct, and directly above the declaration of the fixed-size string or array field. For more information on how to use @dll.structmap, see the Fixed-size Strings Embedded within Structures and Fixed-size Scalar Arrays Embedded within Structures sections of this article.

The following table presents the syntax of the @dll.structmap directive.

Situation	Required Syntax	Explanation
Structure that contains a fixed-size string.	/**@dll.structmap([type=TCHAR[Size]])*/	Size is a decimal integer that indicates the number of characters in the string, including space for the null terminator.
Structure that contains a fixed-size array.	/**@dll.structmap([type=FIXEDARRAY,size=n])*/	n is a decimal integer that represents the size of the array.