Package com.ms.com

Previous

Microsoft Packages

Index

Next

Class Variant

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();
    public Variant(int val);
    public Variant(double val);
    public Variant(boolean val);  
    public Variant(String val);
    public Variant(Object val);
    public Variant(int variantType, int val);
    public Variant(int variantType, boolean val);
    public Variant(int variantType, double val);
    public Variant(int variantType, Object val);

   // Methods
    public void    changeType(short vartype);
    public Variant clone();
    public Variant cloneIndirect();
    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 String  getString();
    public Object  getDispatch();
    public int     getError();
    public boolean getBoolean();
    public Object  getObject();
    public byte    getByte();
    public Variant[] getVariantArray();
    public short   getShortRef(); 
    public int     getIntRef(); 
    public float   getFloatRef(); 
    public double  getDoubleRef(); 
    public long    getCurrencyRef(); 
    public double  getDateRef(); 
    public String  getStringRef();
    public Object  getDispatchRef();
    public int     getErrorRef();
    public boolean getBooleanRef();
    public Object  getObjectRef();
    public byte    getByteRef();
    public Variant[] getVariantArrayRef();
    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 void    putString(String  val);
    public void    putDispatch(Object  val);
    public void    putError(int     val); 
    public void    putBoolean(boolean val); 
    public void    putObject(Object  val);
    public void    putByte(byte    val); 
    public void    putVariantArray(Variant v[]);
    public void    putShortRef(short val);
    public void    putIntRef(int val);
    public void    putFloatRef(float val);
    public void    putDoubleRef(double val);
    public void    putCurrencyRef(long val);
    public void    putDateRef(double val);
    public void    putStringRef(String val);
    public void    putDispatchRef(Object val);
    public void    putErrorRef(int val);
    public void    putBooleanRef(boolean val);
    public void    putObjectRef(Object val);
    public void    putByteRef(byte val);
    public void    putVariantArrayRef(Variant v[]);
    public short   toShort();
    public int     toInt();
    public float   toFloat();
    public double  toDouble();
    public long    toCurrency();
    public double  toDate();
    public toString();
    public Object  toDispatch();
    public int     toError();
    public boolean toBoolean();
    public Object  toObject();
    public byte    toByte();   
    public Variant[] toVariantArray();
    public void    VariantClear();
    public Variant[] toVariantArray();
}

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 an IDispatch interface; 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.

See also package com.ms.com.

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;

Array of values of the given type.

VariantByref = 0x4000;

Value is being passed by reference; any changes made to the parameter value by the called party 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.

Constructors

Variant

public Variant( );

Constructs a new Variant object.

Variant

public Variant(int val)

Creates and initializes a new Variant object of type VariantInt.

Parameter	Description
val	Value of the object to be created.

Variant

public Variant(double val)

Creates a new Variant object of type VariantDouble.

Parameter	Description
val	Value of the object to be created.

Variant

public Variant(boolean val)

Creates a new Variant object of type VariantBoolean.

Parameter	Description
val	Value of the object to be created.

Variant

public Variant(String val)

Creates a new Variant object of type VariantString.

Parameter	Description
val	Value of the object to be created.

Variant

public Variant(Object val)

Creates a new Variant object of type VariantDispatch.

Parameter	Description
val	Value of the object to be created.

Variant

public Variant(int variantType, int val)

Creates a new Variant object of the specified type and value.

Parameter	Description
variantType	Type of object to be created. Can be one of the following: VariantShort VariantInt VariantByte VariantShort| VariantByref VariantInt | VariantByref VariantByte | VariantByref
val	Value of the object to be created.

Variant

public Variant(int variantType, boolean val)

Creates a new Variant object of the specified type and value.

Parameter	Description
variantType	Type of object to be created. Can be one of the following: VariantBoolean VariantBoolean | VariantByref
val	Value of the object to be created.

Variant

public Variant(int variantType, double val)

Creates a new Variant object of the specified type and value.

Parameter	Description
variantType	Type of object to be created. Can be one of the following: VariantDouble VariantDouble | VariantByref VariantFloat VariantFloat | VariantByref VariantDate VariantDate | VariantByref
val	Value of the object to be created.

Variant

public Variant(int variantType, Object val)

Creates a new Variant object of the specified type and value.

Parameter	Description
variantType	Type of object to be created. Can be one of the following: VariantObject VariantObject | VariantByref VariantDispatch VariantDispatch | VariantByref VariantString VariantString | VariantByref
val	Value of the object to be created.

Methods

changeType

public void changeType(short vartype);

Converts the value stored in the Variant object to the specified type.

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

See Also: getvt

clone

public Variant clone( );

Creates a copy of 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.

getvt

public short getvt( );

Retrieves the type of the value currently stored in the Variant object. 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          String  getString(); 
public          Object  getDispatch(); 
public          int     getError(); 
public          boolean getBoolean(); 
public          Object  getObject(); 
public          byte    getByte(); 
public          Variant[] getVariantArray();

Retrieves the value stored in the Variant object.

See Also: putXXXX, putXXXXRef, getvt

getXXXXRef

public          short   getShortRef(); 
public          int     getIntRef(); 
public          float   getFloatRef(); 
public          double  getDoubleRef(); 
public          long    getCurrencyRef(); 
public          double  getDateRef(); 
public          String  getStringRef(); 
public          Object  getDispatchRef(); 
public          int     getErrorRef(); 
public          boolean getBooleanRef(); 
public          Object  getObjectRef(); 
public          byte    getByteRef(); 
public          Variant[] getVariantArrayRef();

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. Calling this method allocates the space needed in which the callee will place the value. 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 does not 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 Object Definition Language (ODL) description of the interface. When methods with optional parameters are exposed in Java, the Java version declares all the parameters.

When you want 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 Workspace interface 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          void    putString(String  val);
public          void    putDispatch(Object  val);
public          void    putError(int     val); 
public          void    putBoolean(boolean val); 
public          void    putObject(Object  val);
public          void    putByte(byte    val); 
public          void    putVariantArray(Variant v[]);

Sets the value stored in the Variant object.

Parameter	Description
val	Value to be passed.

See Also: getXXXX, putXXXXRef, getvt

putXXXXRef

public          void    putShortRef(short     val);
public          void    putIntRef(int       val);
public          void    putFloatRef(float     val);
public          void    putDoubleRef(double    val);
public          void    putCurrencyRef(long    val);
public          void    putDateRef(double    val);
public          void    putStringRef(String    val);
public          void    putDispatchRef(Object  val);
public          void    putErrorRef(int       val);
public          void    putBooleanRef(boolean  val);
public          void    putObjectRef(Object    val);
public          void    putByteRef(byte      val); 
public          void    putVariantArrayRef(Variant v[]);

Sets the value stored in the Variant object when it is used to pass a parameter by reference.

Parameter	Description
val	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. Calling this method allocates the space in which the callee will place the value. 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 could 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 short   toShort();
public          int     toInt();
public          float   toFloat();
public          double  toDouble();
public          long    toCurrency();
public          double  toDate();
public          String  toString(); 
public          Object  toDispatch();
public          int     toError();
public          boolean toBoolean();
public          Object  toObject();
public          byte    toByte();    
public          Variant[] toVariantArray();

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 void VariantClear( );

Clears a Variant object.