Class Variant

Package com.ms.com

Previous

Microsoft Packages

Index

Next

Class Variant

Fields , Constructor , Methods

public final class com.ms.com.Variant

{
    // Fields
    public static final short VariantEmpty;
    public static final short VariantNull;
    public static final short VariantShort;
    public static final short VariantInt;
    public static final short VariantFloat;
    public static final short VariantDouble;
    public static final short VariantCurrency;
    public static final short VariantDate;
    public static final short VariantString;
    public static final short VariantDispatch;
    public static final short VariantError;
    public static final short VariantBoolean;
    public static final short VariantVariant;
    public static final short VariantObject;
    public static final short VariantByte;
    public static final short VariantTypeMask;
    public static final short VariantArray;
    public static final short VariantByref;

    // Constructors
    public Variant();

    // Methods
    public  native  void    changeType(short vartype);
    public  Variant clone();
    public  Variant cloneIndirect();

    protected  void    finalize(); 
    public          short   getvt();
    public          void    getEmpty(); 
    public          void    getNull();
    public          short   getShort(); 
    public          int     getInt(); 
    public          float   getFloat(); 
    public          double  getDouble(); 
    public          long    getCurrency(); 
    public          double  getDate(); 
    public  native  String  getString();
    public  native  Object  getDispatch();
    public          int     getError();
    public  native  boolean getBoolean();
    public  native  Object  getObject();
    public  native  byte    getByte();
    public  native  short   getShortRef(); 
    public  native  int     getIntRef(); 
    public  native  float   getFloatRef(); 
    public  native  double  getDoubleRef(); 
    public  native  long    getCurrencyRef(); 
    public  native  double  getDateRef(); 
    public  native  String  getStringRef();
    public  native  Object  getDispatchRef();
    public  native  int     getErrorRef();
    public  native  boolean getBooleanRef();
    public  native  Object  getObjectRef();
    public  native  byte    getByteRef();
    public void noParam();
    public          void    putEmpty();
    public          void    putNull();
    public          void    putShort(short   val); 
    public          void    putInt(int     val); 
    public          void    putFloat(float   val); 
    public          void    putDouble(double  val); 
    public          void    putCurrency(long    val); 
    public          void    putDate(double  val); 
    public  native  void    putString(String  val);
    public  native  void    putDispatch(Object  val);
    public          void    putError(int     val); 
    public          void    putBoolean(boolean val); 
    public  native  void    putObject(Object  val);
    public          void    putByte(byte    val); 
    public  native  void    putShortRef(short val);
    public  native  void    putIntRef(int val);
    public  native  void    putFloatRef(float val);
    public  native  void    putDoubleRef(double val);
    public  native  void    putCurrencyRef(long val);
    public  native  void    putDateRef(double val);
    public  native  void    putStringRef(String val);
    public  native  void    putDispatchRef(Object val);
    public  native  void    putErrorRef(int val);
    public  native  void    putBooleanRef(boolean val);
    public  native  void    putObjectRef(Object val);
    public  native  void    putByteRef(byte val);
    public  native  short   toShort();
    public  native  int     toInt();
    public  native  float   toFloat();
    public  native  double  toDouble();
    public  native  long    toCurrency();
    public  native  double  toDate();
    public  native  String  toString();
    public  native  Object  toDispatch();
    public  native  int     toError();
    public  native  boolean toBoolean();
    public  native  Object  toObject();
    public  native  byte    toByte();   
    public  native  void    VariantClear();

}

The Variant class is the Java wrapper for the VARIANT structure defined by the Component Object Model (COM). A VARIANT structure can store any one of many different types of values, and is typically used to pass parameters to interfaces derived from IDispatch; a VARIANT can be used to pass a parameter either by value or by reference.

Use the Java Variant class when using COM services from Java, or when implementing COM services using Java.

Fields

Class Variant has the following fields. These describe the types of values that a Variant object can contain:

VariantEmpty = 0;: No value.
VariantNull = 1;: Value is null.
VariantShort = 2;: Value is a two-byte integer.
VariantInt = 3;: Value is a four-byte integer.
VariantFloat = 4;: Value is a single-precision (four-byte) floating point number.
VariantDouble = 5;: Value is a double-precision (8-byte) floating point number.
VariantCurrency = 6;: Value is a currency amount.
VariantDate = 7;: Value is a date.
VariantString = 8;: Value is a string.
VariantDispatch = 9;: Value is a dispatch interface.
VariantError = 10;: Value is an error value.
VariantBoolean = 11;: Value is a Boolean.
VariantVariant = 12;: Value is a variant.
VariantObject = 13;: Value is an object.
VariantByte = 17;: Value is a byte.
VariantTypeMask = 0xfff;: Useful if you don't care about the type of the value being passed, but are interested in the "shape," that is, whether it is a VariantByref or not.
VariantArray = 0x2000;: Indicates an array of values of the given type.
VariantByref = 0x4000;: Indicates that the value is being passed by reference, that is, any changes that the callee makes to the value of a parameter are visible to the caller.

You can use these contents when examining the return value of the getvt method. You can also pass one of these constants when calling the changeType method.

Constructor

Variant

public Variant( );
Constructs a new Variant object.

Methods

changeType

public native void changeType(short vartype);
Converts the value stored in the Variant object to the specified type.

Parameter Description

vartype The destination type. Must be one of the Variant constants.

See Also: getvt

clone

public Variant clone( );
Clones a Variant object.

cloneIndirect

public Variant cloneIndirect( );
Creates a copy of the Variant object without the VariantByref flag set. See the Win32 API VariantCopyInd for more information.

finalize

protected void finalize( );
Destroys a Variant object.

getvt

public short getvt( );
Retrieves the type of the value currently stored in the Variant. The return value is some combination of the Variant constants.
See Also: changeType

getXXXX

public          void    getEmpty(); 
public          void    getNull(); 
public          short   getShort(); 
public          int     getInt(); 
public          float   getFloat(); 
public          double  getDouble(); 
public          long    getCurrency(); 
public          double  getDate(); 
public  native  String  getString(); 
public  native  Object  getDispatch(); 
public          int     getError(); 
public  native  boolean getBoolean(); 
public  native  Object  getObject(); 
public          byte    getByte();

Retrieves the value stored in the Variant object.

See Also: putXXXX, putXXXXRef, getvt

getXXXXRef

public  native  short   getShortRef(); 
public  native  int     getIntRef(); 
public  native  float   getFloatRef(); 
public  native  double  getDoubleRef(); 
public  native  long    getCurrencyRef(); 
public  native  double  getDateRef(); 
public  native  String  getStringRef(); 
public  native  Object  getDispatchRef(); 
public  native  int     getErrorRef(); 
public  native  boolean getBooleanRef(); 
public  native  Object  getObjectRef(); 
public  native  byte    getByteRef(); 
Retrieves the value stored in the Variant object after it was used to pass a parameter by reference.
In the case of using COM services from Java, when you use a Variant object to pass a value by reference, you must call the appropriate putXXXXRef method before passing the Variant. This is needed to allocate the space in which the value will be placed by the callee. Then call the appropriate getXXXXRef method to read the value; changes are not made to the variable you passed to the putXXXXRef method.
For example, suppose you are passing an integer to a method that takes an integer parameter by reference. You would use code like the following:
// IFoo is a COM interface with a ChangeInt method 
// foo is a variable of type IFoo
Variant var = new Variant();
var.putIntRef(0);        // allocate the space needed
foo.ChangeInt(var);   // pass var to a COM method
int i = var.getIntRef(); // get the value back
This example calls putIntRef before passing the Variant, even if the ChangeInt method doesn't use the value it receives.
In the case of implementing a COM service using Java, you can use getXXXXRef to read the value passed in by the caller.
See Also: getXXXX, putXXXXRef, getvt

noParam

public void noParam( );
Makes the Variant object an optional parameter. This is useful when using COM methods that have optional Variant parameters; these are indicated with the optional attribute in the ODL (Object Definition Language) description of the interface. When methods with optional parameters are exposed in Java, the Java version declares all the parameters.
When you wish to specify a value for an optional parameter, pass a regular Variant object when calling the method. When you wish to omit an optional parameter, simply create a Variant object, call the noParam method on it, and pass it in place of an actual value.
For example, with Data Access Objects (DAO), the interface Workspace defines a method named OpenDatabase which takes four parameters, three of which are optional. You could call OpenDatabase and specify only the first parameter as follows:
// myDB is a variable of type dao3032.Database 
// myWorkspc is a variable of type dao3032.Workspace  
Variant opt = new Variant();
opt.noParam();
myDB = myWorkspc.OpenDatabase("Inventory", opt, opt, opt);

putXXXX

public          void    putEmpty();
public          void    putNull();
public          void    putShort(short   val); 
public          void    putInt(int     val); 
public          void    putFloat(float   val); 
public          void    putDouble(double  val); 
public          void    putCurrency(long    val); 
public          void    putDate(double  val); 
public  native  void    putString(String  val);
public  native  void    putDispatch(Object  val);
public          void    putError(int     val); 
public          void    putBoolean(boolean val); 
public  native  void    putObject(Object  val);
public          void    putByte(byte    val);

Sets the value stored in the Variant object.

Parameter Description

val The value to be passed.

See Also: getXXXX, putXXXXRef, getvt

putXXXXRef

public  native  void    putShortRef(short     val);
public  native  void    putIntRef(int       val);
public  native  void    putFloatRef(float     val);
public  native  void    putDoubleRef(double    val);
public  native  void    putCurrencyRef(long    val);
public  native  void    putDateRef(double    val);
public  native  void    putStringRef(String    val);
public  native  void    putDispatchRef(Object  val);
public  native  void    putErrorRef(int       val);
public  native  void    putBooleanRef(boolean  val);
public  native  void    putObjectRef(Object    val);
public  native  void    putByteRef(byte      val); 
Sets the value stored in the Variant object when it is used to pass a parameter by reference.

Parameter Description

val The value to be passed.

Remarks:
In the case of using COM services from Java, when you use a Variant object to pass a value by reference, you must call the appropriate putXXXXRef method before passing the Variant. This is needed to allocate the space in which the value will be placed by the callee. Then call the appropriate getXXXXRef method to read the value; changes are not made to the variable you passed to the putXXXXRef method.
For example, suppose you are passing an integer to a method that takes an integer parameter by reference. You would use code like the following:
// IFoo is a COM interface with a ChangeInt method 
// foo is a variable of type IFoo 
Variant var = new Variant();
var.putIntRef(0);        // allocate the space needed
foo.ChangeInt(var);   // pass var to a COM method
int i = var.getIntRef(); // get the value back
This example calls putIntRef before passing the Variant, even if the ChangeInt method doesn't use the value it receives.
In the case of implementing COM services from Java, you call putXXXXRef to specify the value that you return to the caller. You must use the correct type when setting the value; for example, if the Variant object contains a double value, you must call putDoubleRef.
Throws:
A ClassCastException if you call a method that does not match the type of the variable currently stored in the object.
See Also: getXXXX, putXXXX, getvt

toXXXX

public  native  short   toShort();
public  native  int     toInt();
public  native  float   toFloat();
public  native  double  toDouble();
public  native  long    toCurrency();
public  native  double  toDate();
public  native  String  toString(); 
public  native  Object  toDispatch();
public  native  int     toError();
public  native  boolean toBoolean();
public  native  Object  toObject();
public  native  byte    toByte();    
Gets the value stored in the Variant object, cast to the specified type.
These methods do not modify the value stored within the Variant object.
Throws:
A ClassCastException if the cast fails.
See Also: changeType, getvt

VariantClear

public native void VariantClear( );
Clears a Variant object.

Parameter	Description
vartype	The destination type. Must be one of the Variant constants.