## org.apache.poi.hpsf
Class VariantSupport

    java.lang.Object
      org.apache.poi.hpsf.Variant
          org.apache.poi.hpsf.VariantSupport

    public class VariantSupport

extends Variant

Supports reading and writing of variant data.

FIXME (3): Reading and writing should be made more uniform than it is now. The following items should be resolved:

- Reading requires a length parameter that is 4 byte greater than the actual data, because the variant type field is included.

- Reading reads from a byte array while writing writes to an byte array output stream.

Author:
  Rainer Klute <klute@rainer-klute.de>

Field Summary
`static int[]` `SUPPORTED_TYPES` HPSF is able to read these `Variant` types.
`protected static java.util.List` `unsupportedMessage` Keeps a list of the variant types an "unsupported" message has already been issued for.

Fields inherited from class org.apache.poi.hpsf.Variant

`LENGTH_0, LENGTH_2, LENGTH_4, LENGTH_8, LENGTH_UNKNOWN, LENGTH_VARIABLE, VT_ARRAY, VT_BLOB, VT_BLOB_OBJECT, VT_BOOL, VT_BSTR, VT_BYREF, VT_CARRAY, VT_CF, VT_CLSID, VT_CY, VT_DATE, VT_DECIMAL, VT_DISPATCH, VT_EMPTY, VT_ERROR, VT_FILETIME, VT_HRESULT, VT_I1, VT_I2, VT_I4, VT_I8, VT_ILLEGAL, VT_ILLEGALMASKED, VT_INT, VT_LPSTR, VT_LPWSTR, VT_NULL, VT_PTR, VT_R4, VT_R8, VT_RESERVED, VT_SAFEARRAY, VT_STORAGE, VT_STORED_OBJECT, VT_STREAM, VT_STREAMED_OBJECT, VT_TYPEMASK, VT_UI1, VT_UI2, VT_UI4, VT_UI8, VT_UINT, VT_UNKNOWN, VT_USERDEFINED, VT_VARIANT, VT_VECTOR, VT_VERSIONED_STREAM, VT_VOID`

Constructor Summary
`VariantSupport()`

Method Summary
`static java.lang.String` `codepageToEncoding(int codepage)` Turns a codepage number into the equivalent character encoding's name.
`static boolean` `isLogUnsupportedTypes()` Checks whether logging of unsupported variant types warning is turned on or off.
`boolean` `isSupportedType(int variantType)` Checks whether HPSF supports the specified variant type.
`static java.lang.Object` `read(byte[] src, int offset, int length, long type, int codepage)` Reads a variant type from a byte array.
`static void` `setLogUnsupportedTypes(boolean logUnsupportedTypes)` Specifies whether warnings about unsupported variant types are to be written to `System.err` or not.
`static int` `write(java.io.OutputStream out, long type, java.lang.Object value, int codepage)` Writes a variant value to an output stream.
`protected static void` `writeUnsupportedTypeMessage(UnsupportedVariantTypeException ex)` Writes a warning to `System.err` that a variant type is unsupported by HPSF.

Methods inherited from class org.apache.poi.hpsf.Variant
`getVariantLength, getVariantName`

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Field Detail

### unsupportedMessage

    protected static java.util.List unsupportedMessage

  Keeps a list of the variant types an "unsupported" message has already been issued for.

### SUPPORTED_TYPES

    public static final int[] SUPPORTED_TYPES

  HPSF is able to read these `Variant` types.

Constructor Detail

### VariantSupport

    public VariantSupport()

Method Detail

### setLogUnsupportedTypes

    public static void setLogUnsupportedTypes(boolean logUnsupportedTypes)

  Specifies whether warnings about unsupported variant types are to be written to `System.err` or not.

  Parameters:
    `logUnsupportedTypes` - If `true` warnings will be written, if `false` they won't.

### isLogUnsupportedTypes

    public static boolean isLogUnsupportedTypes()

  Checks whether logging of unsupported variant types warning is turned on or off.

  Returns:
    `true` if logging is turned on, else `false`.

### writeUnsupportedTypeMessage

    protected static void writeUnsupportedTypeMessage(UnsupportedVariantTypeException ex)

  Writes a warning to `System.err` that a variant type is unsupported by HPSF. Such a warning is written only once for each variant type. Log messages can be turned on or off by

  Parameters:
    `ex` - The exception to log

### isSupportedType

    public boolean isSupportedType(int variantType)

  Checks whether HPSF supports the specified variant type. Unsupported types should be implemented included in the `SUPPORTED_TYPES` array.

  Parameters:
    `variantType` - the variant type to check
  Returns:
    `true` if HPFS supports this type, else `false`
  See Also:
    `Variant`

### read

    public static java.lang.Object read(byte[] src,
                                        int offset,
                                        int length,
                                        long type,
                                        int codepage)
                                 throws ReadingNotSupportedException,
                                        java.io.UnsupportedEncodingException

  Reads a variant type from a byte array.

  Parameters:
    `src` - The byte array
    `offset` - The offset in the byte array where the variant starts
    `length` - The length of the variant including the variant type field
    `type` - The variant type to read
    `codepage` - The codepage to use for non-wide strings
  Returns:
    A Java object that corresponds best to the variant field. For example, a VT_I4 is returned as a `Long`, a VT_LPSTR as a `String`.
  Throws:
    `ReadingNotSupportedException` - if a property is to be written who's variant type HPSF does not yet support
    `java.io.UnsupportedEncodingException` - if the specified codepage is not supported.
  See Also:
    `Variant`

### codepageToEncoding

    public static java.lang.String codepageToEncoding(int codepage)
                                               throws java.io.UnsupportedEncodingException

  Turns a codepage number into the equivalent character encoding's name.

  Parameters:
    `codepage` - The codepage number
  Returns:
    The character encoding's name. If the codepage number is 65001, the encoding name is "UTF-8". All other positive numbers are mapped to "cp" followed by the number, e.g. if the codepage number is 1252 the returned character encoding name will be "cp1252".
  Throws:
    `java.io.UnsupportedEncodingException` - if the specified codepage is less than zero.

### write

    public static int write(java.io.OutputStream out,
                            long type,
                            java.lang.Object value,
                            int codepage)
                     throws java.io.IOException,
                            WritingNotSupportedException

  Writes a variant value to an output stream. This method ensures that always a multiple of 4 bytes is written.

  If the codepage is UTF-16, which is encouraged, strings must always be written as `Variant.VT_LPWSTR` strings, not as `Variant.VT_LPSTR` strings. This method ensure this by converting strings appropriately, if needed.

  Parameters:
    `out` - The stream to write the value to.
    `type` - The variant's type.
    `value` - The variant's value.
    `codepage` - The codepage to use to write non-wide strings
  Returns:
    The number of entities that have been written. In many cases an "entity" is a byte but this is not always the case.
  Throws:
    `java.io.IOException` - if an I/O exceptions occurs
    `WritingNotSupportedException` - if a property is to be written who's variant type HPSF does not yet support

Copyright 2012 The Apache Software Foundation or its licensors, as applicable.