This sample is located in \Samples\Com\CustomMarshal\Varstr.
Note To use this sample, it is recommended that you have Microsoft® Visual C++® version 5.0 or higher installed.
Description
Using the Sample
Technologies Demonstrated
The basic hook class, FixedPtMarshaler, assumes that ETYPE doesn't contain embedded pointers or handles to allocated resources to free when ETYPE is no longer needed. In C++ terms, if ETYPE is a class in a basic hook class, it is assumed ETYPE doesn't have a destructor. Some structures, however, need to clean up embedded resources. A well-known example is the VARIANT structure used in COM Automation. A VARIANT is a fixed-size structure, yet it can have allocated objects such as BSTR, SAFEARRAYS, and COM objects referenced by it. The Java equivalent of a destructor for a VARIANT is the VariantClear API, which checks the type of the variant and performs the appropriate cleanup (for example, freeing the BSTR, freeing the SAFEARRAY, calling Release on the COM object, and so on).
Arranging for proper cleanup of embedded resources requires only one new method, releaseByValExternal.
The VarStrMarshaler example maps VARIANT types, confining itself to only one case: marshaling BSTR VARIANT types to Java String objects. That is, the JTYPE is String, and the ETYPE is as follows:
struct { short vt; // Always use VT_BSTR for this example. short unused; short unused1; short unused2; BSTR bstrVal; // Points to characters in BSTR. long unused3; // Never used in this example. } VARIANT;
The source code for VarStrMarshaler is in \Samples\Com\CustomMarshal\varstr. Copy the executables VarStrMarshaler.class and VarStrMarshaler.dll to the run location.
This hook class can be used as described in the following table.
COM type | Marshaled to Java as |
HRESULT func([in] VARIANT) | func(String) |
HRESULT func([out,retval] VARIANT*) | String func() |
HRESULT func([in] VARIANT*) | func(String) |
HRESULT func([out] VARIANT*) | func(String[]) |
HRESULT func([in,out] VARIANT*) | func(String[]) |
As before, String is immutable: The const modifier should be used for it in the .jnf file.
To compile the sample
Use Nmake.exe to compile the makefile in the \Samples\Com\CustomMarshal\varstr directory. Type the following command:
Nmake
To run the sample
Run Go.bat from the \Samples\Com\CustomMarshal\rundir directory.