VarStrMarshaler Custom Marshaling Sample

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

Description

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.

Hook class usage

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.

Using the Sample

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.

Technologies Demonstrated

Custom Marshaling

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