Microsoft SDK for Java

Hook Class Overview

Custom marshaling, except for the extra step of writing a hook class and listing your data types in the .jnf file, is the same as integrating any other COM library with Java.

A hook class is a Java class whose methods are used to marshal fields or parameters. The hook class must be installed and visible to the class path on any system where the user-defined types are used. Otherwise, hook classes remain mostly hidden. The Microsoft VM loads the hook class as part of loading a jactivex-created interface file that references the user-defined types, and invokes methods on the hook class to marshal them.

The wiHookClass field of the MCTypeDesc attribute information structure associated with the field or parameter designates the hook class. The value of wiHookClass is an index into the constant pool of the containing class. The constant pool entry must be of type CONSTANT_Class (directly references the hook class) or CONSTANT_Utf8 (names the hook class, loaded relative to containing class).

The Java/COM integration layer of the Microsoft VM never creates an instance of a hook class. There are around 10 fields and methods recognized as hook class members. They are all either optional or have reasonable defaults, so most hook classes need to implement only a subset of the members.

A hook class has the following responsibilities:

In turn, the Microsoft VM is responsible for calling the appropriate hook methods at the right time whenever ETYPEs are passed to or from COM methods. Once the hook class is written, the VM automatically supports passing ETYPEs (if it is fixed-size), ETYPE*, and ETYPE**, as well as returning ETYPE*. The VM also implements the correct semantics for [in], [out], [in,out], and [out,retval] type library attributes, which jactivex passes along using the extra bits in the .class file. An [out] attribute or double indirection is mapped to a one-element array of JTYPE rather than to JTYPE itself.

Hook Class Implementation

Although hook classes are packaged as Java classes, they cannot be written in Java. Hook classes must receive and pass memory addresses (pointers). Java methods can receive pointers as integers, but Java cannot dereference, allocate, destroy, or otherwise manipulate pointers. Therefore, use the Raw Native Interface (RNI) to write hook classes. RNI allows Java methods to be implemented as C functions inside a DLL. RNI also offers a small set of APIs that can be called from C to create, manipulate, and destroy Java objects.

Using Template Files to Write a Hook Class

The Microsoft SDK for Java contains samples showing how to write hook classes to achieve custom marshaling. The sample files for this section are in the Microsoft SDK for Java. The sources for a working copy of this example are in %SDKDIR%\Samples\Com\CustomMarshal\Template. For more information, see the COM Samples Overview. For information about other samples in this SDK, see the Samples Overview.

The easiest way to start is by copying the files under the template subdirectory to a new directory. The key files here are:

To compile the files, follow the instructions in each of the comments marked TODO in TemplateMarshaler.java and TemplateMarshaler.c. This involves replacing ETYPE and JTYPE with your particular type, and uncommenting some optional methods.

The template contains C functions for eight hook methods. The comments inside each function describe what that hook function does. Details are provided in the examples. Note the following information about hook functions:

© 1999 Microsoft Corporation. All rights reserved. Terms of use.