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.

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static int[]` | `SUPPORTED_TYPES` HPSF is able to read these `Variant` types.

    - ### 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

    Constructors
    Constructor and Description
    `VariantSupport()`

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `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 java.lang.Object` | `read(LittleEndianByteArrayInputStream lei, int length, long type, int codepage)`
    `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

    - #### 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`

    - #### read

          public static java.lang.Object read(LittleEndianByteArrayInputStream lei,
                                              int length,
                                              long type,
                                              int codepage)
                                       throws ReadingNotSupportedException,
                                              java.io.UnsupportedEncodingException

      Throws:
        `ReadingNotSupportedException`
        `java.io.UnsupportedEncodingException`

    - #### 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.

      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 2020 The Apache Software Foundation or its licensors, as applicable.