Package org.eclipse.swt.ole.win32

Class Variant

java.lang.Object
org.eclipse.swt.ole.win32.Variant
public final class Variant extends Object
A Variant is a generic OLE mechanism for passing data of different types via a common interface.

It is used within the OleAutomation object for getting a property, setting a property or invoking a method on an OLE Control or OLE Document.

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final Variant
    NULL
    A shared Variant instance with type VT_NULL.
    static final int
    sizeof
    The size in bytes of a native VARIANT struct.

  • Constructor Summary

    Constructors
    Constructor
    Description
    Variant()
    Create an empty Variant object with type VT_EMPTY.
    Variant(boolean val)
    Create a Variant object which represents a Java boolean as a VT_BOOL.
    Variant(double val)
    Create a Variant object which represents a Java double as a VT_R8.
    Variant(float val)
    Create a Variant object which represents a Java float as a VT_R4.
    Variant(int val)
    Create a Variant object which represents a Java int as a VT_I4.
    Variant(long val)
    Create a Variant object which represents a Java long as a VT_I8.
    Variant(long ptr, short byRefType)
    Create a Variant object which contains a reference to the data being transferred.
    Variant(short val)
    Create a Variant object which represents a Java short as a VT_I2.
    Variant(String string)
    Create a Variant object which represents a Java String as a VT_BSTR.
    Variant(org.eclipse.swt.internal.ole.win32.IDispatch idispatch)
    Create a Variant object which represents an IDispatch interface as a VT_Dispatch.
    Variant(org.eclipse.swt.internal.ole.win32.IUnknown unknown)
    Create a Variant object which represents an IUnknown interface as a VT_UNKNOWN.
    Variant(OleAutomation automation)
    Create a Variant object which represents an IDispatch interface as a VT_Dispatch.

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    dispose()
    Calling dispose will release resources associated with this Variant.
    OleAutomation
    getAutomation()
    Returns the OleAutomation object represented by this Variant.
    boolean
    getBoolean()
    Returns the Java boolean represented by this Variant.
    long
    getByRef()
    Returns a pointer to the referenced data represented by this Variant.
    byte
    getByte()
    Returns the Java byte represented by this Variant.
    char
    getChar()
    Returns the Java char represented by this Variant.
    org.eclipse.swt.internal.ole.win32.IDispatch
    getDispatch()
    Returns the IDispatch object represented by this Variant.
    double
    getDouble()
    Returns the Java double represented by this Variant.
    float
    getFloat()
    Returns the Java float represented by this Variant.
    int
    getInt()
    Returns the Java int represented by this Variant.
    long
    getLong()
    Returns the Java long represented by this Variant.
    short
    getShort()
    Returns the Java short represented by this Variant.
    String
    getString()
    Returns the Java String represented by this Variant.
    short
    getType()
    Returns the type of the variant type.
    org.eclipse.swt.internal.ole.win32.IUnknown
    getUnknown()
    Returns the IUnknown object represented by this Variant.
    void
    setByRef(boolean val)
    Update the by reference value of this variant with a new boolean value.
    void
    setByRef(float val)
    Update the by reference value of this variant with a new float value.
    void
    setByRef(long val)
    Update the by reference value of this variant with a new integer value.
    void
    setByRef(short val)
    Update the by reference value of this variant with a new short value.
    String
    toString()
    Returns a string containing a concise, human-readable description of the receiver.
    static void
    win32_copy(long pVarDest, Variant varSrc)
    Invokes platform specific functionality to copy a variant into operating system memory.
    static Variant
    win32_new(long pVariant)
    Invokes platform specific functionality to wrap a variant that was allocated in operating system memory.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

  • Field Details

    • sizeof

      public static final int sizeof
      The size in bytes of a native VARIANT struct.

    • NULL

      public static final Variant NULL
      A shared Variant instance with type VT_NULL.
      Since:
      3.7

  • Constructor Details

    • Variant

      public Variant()
      Create an empty Variant object with type VT_EMPTY.
      Since:
      2.0

    • Variant

      public Variant(float val)
      Create a Variant object which represents a Java float as a VT_R4.
      Parameters:
      val - the Java float value that this Variant represents

    • Variant

      public Variant(double val)
      Create a Variant object which represents a Java double as a VT_R8.
      Parameters:
      val - the Java double value that this Variant represents
      Since:
      3.2

    • Variant

      public Variant(int val)
      Create a Variant object which represents a Java int as a VT_I4.
      Parameters:
      val - the Java int value that this Variant represents

    • Variant

      public Variant(long ptr, short byRefType)
      Create a Variant object which contains a reference to the data being transferred.

      When creating a VT_BYREF Variant, you must give the full Variant type including VT_BYREF such as 

      short byRefType = OLE.VT_BSTR | OLE.VT_BYREF
      .
      Parameters:
      ptr - a pointer to the data being transferred.
      byRefType - the type of the data being transferred such as OLE.VT_BSTR | OLE.VT_BYREF

    • Variant

      public Variant(OleAutomation automation)
      Create a Variant object which represents an IDispatch interface as a VT_Dispatch.
      Parameters:
      automation - the OleAutomation object that this Variant represents

    • Variant

      public Variant(org.eclipse.swt.internal.ole.win32.IDispatch idispatch)
      Create a Variant object which represents an IDispatch interface as a VT_Dispatch.

      The caller is expected to have appropriately invoked unknown.AddRef() before creating this Variant.

      Parameters:
      idispatch - the IDispatch object that this Variant represents
      Since:
      2.0

    • Variant

      public Variant(org.eclipse.swt.internal.ole.win32.IUnknown unknown)
      Create a Variant object which represents an IUnknown interface as a VT_UNKNOWN.

      The caller is expected to have appropriately invoked unknown.AddRef() before creating this Variant.

      Parameters:
      unknown - the IUnknown object that this Variant represents

    • Variant

      public Variant(long val)
      Create a Variant object which represents a Java long as a VT_I8.
      Parameters:
      val - the Java long value that this Variant represents
      Since:
      3.2

    • Variant

      public Variant(String string)
      Create a Variant object which represents a Java String as a VT_BSTR.
      Parameters:
      string - the Java String value that this Variant represents

    • Variant

      public Variant(short val)
      Create a Variant object which represents a Java short as a VT_I2.
      Parameters:
      val - the Java short value that this Variant represents

    • Variant

      public Variant(boolean val)
      Create a Variant object which represents a Java boolean as a VT_BOOL.
      Parameters:
      val - the Java boolean value that this Variant represents

  • Method Details

    • win32_copy

      public static void win32_copy(long pVarDest, Variant varSrc)
      Invokes platform specific functionality to copy a variant into operating system memory.

      IMPORTANT: This method is not part of the public API for Variant. It is marked public only so that it can be shared within the packages provided by SWT. It is not available on all platforms, and should never be called from application code.

      Parameters:
      pVarDest - destination pointer to a variant
      varSrc - source Variant
      Since:
      3.3
      Restriction:
      This method is not intended to be referenced by clients.

    • win32_new

      public static Variant win32_new(long pVariant)
      Invokes platform specific functionality to wrap a variant that was allocated in operating system memory.

      IMPORTANT: This method is not part of the public API for Variant. It is marked public only so that it can be shared within the packages provided by SWT. It is not available on all platforms, and should never be called from application code.

      Parameters:
      pVariant - pointer to a variant
      Returns:
      a new Variant
      Since:
      3.3
      Restriction:
      This method is not intended to be referenced by clients.

    • dispose

      public void dispose()
      Calling dispose will release resources associated with this Variant. If the resource is an IDispatch or IUnknown interface, Release will be called. If the resource is a ByRef pointer, nothing is released.
      Since:
      2.1

    • getAutomation

      public OleAutomation getAutomation()
      Returns the OleAutomation object represented by this Variant.

      If this Variant does not contain an OleAutomation object, an attempt is made to coerce the Variant type into an OleAutomation object. If this fails, an error is thrown. Note that OleAutomation objects must be disposed when no longer needed.

      Returns:
      the OleAutomation object represented by this Variant
      Throws:
      SWTException -
      • ERROR_CANNOT_CHANGE_VARIANT_TYPE when type of Variant can not be coerced into an OleAutomation object

    • getDispatch

      public org.eclipse.swt.internal.ole.win32.IDispatch getDispatch()
      Returns the IDispatch object represented by this Variant.

      If this Variant does not contain an IDispatch object, an attempt is made to coerce the Variant type into an IDIspatch object. If this fails, an error is thrown.

      Returns:
      the IDispatch object represented by this Variant
      Throws:
      SWTException -
      • ERROR_CANNOT_CHANGE_VARIANT_TYPE when type of Variant can not be coerced into an IDispatch object
      Since:
      2.0

    • getBoolean

      public boolean getBoolean()
      Returns the Java boolean represented by this Variant.

      If this Variant does not contain a Java boolean, an attempt is made to coerce the Variant type into a Java boolean. If this fails, an error is thrown.

      Returns:
      the Java boolean represented by this Variant
      Throws:
      SWTException -
      • ERROR_CANNOT_CHANGE_VARIANT_TYPE when type of Variant can not be coerced into a boolean

    • getByRef

      public long getByRef()
      Returns a pointer to the referenced data represented by this Variant.

      If this Variant does not contain a reference to data, zero is returned.

      Returns:
      a pointer to the referenced data represented by this Variant or 0

    • getByte

      public byte getByte()
      Returns the Java byte represented by this Variant.

      If this Variant does not contain a Java byte, an attempt is made to coerce the Variant type into a Java byte. If this fails, an error is thrown.

      Returns:
      the Java byte represented by this Variant
      Throws:
      SWTException -
      • ERROR_CANNOT_CHANGE_VARIANT_TYPE when type of Variant can not be coerced into a byte
      Since:
      3.3

    • getChar

      public char getChar()
      Returns the Java char represented by this Variant.

      If this Variant does not contain a Java char, an attempt is made to coerce the Variant type into a Java char. If this fails, an error is thrown.

      Returns:
      the Java char represented by this Variant
      Throws:
      SWTException -
      • ERROR_CANNOT_CHANGE_VARIANT_TYPE when type of Variant can not be coerced into a char
      Since:
      3.3

    • getDouble

      public double getDouble()
      Returns the Java double represented by this Variant.

      If this Variant does not contain a Java double, an attempt is made to coerce the Variant type into a Java double. If this fails, an error is thrown.

      Returns:
      the Java double represented by this Variant
      Throws:
      SWTException -
      • ERROR_CANNOT_CHANGE_VARIANT_TYPE when type of Variant can not be coerced into a double
      Since:
      3.2

    • getFloat

      public float getFloat()
      Returns the Java float represented by this Variant.

      If this Variant does not contain a Java float, an attempt is made to coerce the Variant type into a Java float. If this fails, an error is thrown.

      Returns:
      the Java float represented by this Variant
      Throws:
      SWTException -
      • ERROR_CANNOT_CHANGE_VARIANT_TYPE when type of Variant can not be coerced into a float

    • getInt

      public int getInt()
      Returns the Java int represented by this Variant.

      If this Variant does not contain a Java int, an attempt is made to coerce the Variant type into a Java int. If this fails, an error is thrown.

      Returns:
      the Java int represented by this Variant
      Throws:
      SWTException -
      • ERROR_CANNOT_CHANGE_VARIANT_TYPE when type of Variant can not be coerced into a int

    • getLong

      public long getLong()
      Returns the Java long represented by this Variant.

      If this Variant does not contain a Java long, an attempt is made to coerce the Variant type into a Java long. If this fails, an error is thrown.

      Returns:
      the Java long represented by this Variant
      Throws:
      SWTException -
      • ERROR_CANNOT_CHANGE_VARIANT_TYPE when type of Variant can not be coerced into a long
      Since:
      3.2

    • getShort

      public short getShort()
      Returns the Java short represented by this Variant.

      If this Variant does not contain a Java short, an attempt is made to coerce the Variant type into a Java short. If this fails, an error is thrown.

      Returns:
      the Java short represented by this Variant
      Throws:
      SWTException -
      • ERROR_CANNOT_CHANGE_VARIANT_TYPE when type of Variant can not be coerced into a short

    • getString

      public String getString()
      Returns the Java String represented by this Variant.

      If this Variant does not contain a Java String, an attempt is made to coerce the Variant type into a Java String. If this fails, an error is thrown.

      Returns:
      the Java String represented by this Variant
      Throws:
      SWTException -
      • ERROR_CANNOT_CHANGE_VARIANT_TYPE when type of Variant can not be coerced into a String

    • getType

      public short getType()
      Returns the type of the variant type. This will be an OLE.VT_* value or a bitwise combination of OLE.VT_* values as in the case of OLE.VT_BSTR | OLE.VT_BYREF.
      Returns:
      the type of the variant data
      Since:
      2.0

    • getUnknown

      public org.eclipse.swt.internal.ole.win32.IUnknown getUnknown()
      Returns the IUnknown object represented by this Variant.

      If this Variant does not contain an IUnknown object, an attempt is made to coerce the Variant type into an IUnknown object. If this fails, an error is thrown.

      Returns:
      the IUnknown object represented by this Variant
      Throws:
      SWTException -
      • ERROR_CANNOT_CHANGE_VARIANT_TYPE when type of Variant can not be coerced into an IUnknown object

    • setByRef

      public void setByRef(boolean val)
      Update the by reference value of this variant with a new boolean value.
      Parameters:
      val - the new boolean value
      Throws:
      SWTException -
      • ERROR_CANNOT_CHANGE_VARIANT_TYPE when type of Variant is not a (VT_BYREF | VT_BOOL) object
      Since:
      2.1

    • setByRef

      public void setByRef(float val)
      Update the by reference value of this variant with a new float value.
      Parameters:
      val - the new float value
      Throws:
      SWTException -
      • ERROR_CANNOT_CHANGE_VARIANT_TYPE when type of Variant is not a (VT_BYREF | VT_R4) object
      Since:
      2.1

    • setByRef

      public void setByRef(long val)
      Update the by reference value of this variant with a new integer value.
      Parameters:
      val - the new integer value
      Throws:
      SWTException -
      • ERROR_CANNOT_CHANGE_VARIANT_TYPE when type of Variant is not a (VT_BYREF | VT_I4) object
      Since:
      2.1

    • setByRef

      public void setByRef(short val)
      Update the by reference value of this variant with a new short value.
      Parameters:
      val - the new short value
      Throws:
      SWTException -
      • ERROR_CANNOT_CHANGE_VARIANT_TYPE when type of Variant is not a (VT_BYREF | VT_I2) object
      Since:
      2.1

    • toString

      public String toString()
      Returns a string containing a concise, human-readable description of the receiver.
      Overrides:
      toString in class Object
      Returns:
      a string representation of the Variant