org.apache.poi.hpsf

## Class Property

- java.lang.Object
- - org.apache.poi.hpsf.Property

- Direct Known Subclasses:
    CustomProperty

      public class Property
      extends java.lang.Object

  A property in a `Section` of a `PropertySet`.

  The property's `ID` gives the property a meaning in the context of its `Section`. Each `Section` spans its own name space of property IDs.

  The property's `type` determines how its `value` is interpreted. For example, if the type is `Variant.VT_LPSTR` (byte string), the value consists of a DWord telling how many bytes the string contains. The bytes follow immediately, including any null bytes that terminate the string. The type `Variant.VT_I4` denotes a four-byte integer value, `Variant.VT_FILETIME` some date and time (of a file).

  Please note that not all `Variant` types yet. This might change over time but largely depends on your feedback so that the POI team knows which variant types are really needed. So please feel free to submit error reports or patches for the types you need.

  See Also:
    `Section`, `Variant`, [MS-OLEPS]: Object Linking and Embedding (OLE) Property Set Data Structures

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static int` | `DEFAULT_CODEPAGE` Default codepage for `CodePageStrings`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `Property()` Creates an empty property.
    `Property(long id, byte[] src, long offset, int length, int codepage)` Creates a `Property` instance by reading its bytes from the property set stream.
    `Property(long id, LittleEndianByteArrayInputStream leis, int length, int codepage)` Creates a `Property` instance by reading its bytes from the property set stream.
    `Property(long id, long type, java.lang.Object value)` Creates a property.
    `Property(Property p)` Creates a `Property` as a copy of an existing `Property`.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `boolean` | `equals(java.lang.Object o)` Compares two properties.
    `long` | `getID()` Returns the property's ID.
    `protected int` | `getSize(int property)` Returns the property's size in bytes.
    `long` | `getType()` Returns the property's type.
    `java.lang.Object` | `getValue()` Returns the property's value.
    `int` | `hashCode()`
    `void` | `setID(long id)` Sets the property's ID.
    `void` | `setType(long type)` Sets the property's type.
    `void` | `setValue(java.lang.Object value)` Sets the property's value.
    `java.lang.String` | `toString()`
    `java.lang.String` | `toString(int codepage, PropertyIDMap idMap)`
    `int` | `write(java.io.OutputStream out, int codepage)` Writes the property to an output stream.

    - ### Methods inherited from class java.lang.Object

      `clone, finalize, getClass, notify, notifyAll, wait, wait, wait`

- - ### Field Detail

    - #### DEFAULT_CODEPAGE

          public static final int DEFAULT_CODEPAGE

      Default codepage for `CodePageStrings`
      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### Property

          public Property()

      Creates an empty property. It must be filled using the set method to be usable.

    - #### Property

          public Property(Property p)

      Creates a `Property` as a copy of an existing `Property`.
      Parameters:
        `p` - The property to copy.

    - #### Property

          public Property(long id,
                          long type,
                          java.lang.Object value)

      Creates a property.
      Parameters:
        `id` - the property's ID.
        `type` - the property's type, see `Variant`.
        `value` - the property's value. Only certain types are allowed, see `Variant`.

    - #### Property

          public Property(long id,
                          byte[] src,
                          long offset,
                          int length,
                          int codepage)
                   throws java.io.UnsupportedEncodingException

      Creates a `Property` instance by reading its bytes from the property set stream.
      Parameters:
        `id` - The property's ID.
        `src` - The bytes the property set stream consists of.
        `offset` - The property's type/value pair's offset in the section.
        `length` - The property's type/value pair's length in bytes.
        `codepage` - The section's and thus the property's codepage. It is needed only when reading string values.
      Throws:
        `java.io.UnsupportedEncodingException` - if the specified codepage is not supported.

    - #### Property

          public Property(long id,
                          LittleEndianByteArrayInputStream leis,
                          int length,
                          int codepage)
                   throws java.io.UnsupportedEncodingException

      Creates a `Property` instance by reading its bytes from the property set stream.
      Parameters:
        `id` - The property's ID.
        `leis` - The bytes the property set stream consists of.
        `length` - The property's type/value pair's length in bytes.
        `codepage` - The section's and thus the property's codepage. It is needed only when reading string values.
      Throws:
        `java.io.UnsupportedEncodingException` - if the specified codepage is not supported.

  - ### Method Detail

    - #### getID

          public long getID()

      Returns the property's ID.
      Returns:
        The ID value

    - #### setID

          public void setID(long id)

      Sets the property's ID.
      Parameters:
        `id` - the ID

    - #### getType

          public long getType()

      Returns the property's type.
      Returns:
        The type value

    - #### setType

          public void setType(long type)

      Sets the property's type.
      Parameters:
        `type` - the property's type

    - #### getValue

          public java.lang.Object getValue()

      Returns the property's value.
      Returns:
        The property's value

    - #### setValue

          public void setValue(java.lang.Object value)

      Sets the property's value.
      Parameters:
        `value` - the property's value

    - #### getSize

          protected int getSize(int property)
                         throws WritingNotSupportedException

      Returns the property's size in bytes. This is always a multiple of 4.
      Parameters:
        `property` - The integer property to check
      Returns:
        the property's size in bytes
      Throws:
        `WritingNotSupportedException` - if HPSF does not yet support the property's variant type.

    - #### equals

          public boolean equals(java.lang.Object o)

      Compares two properties.

      Please beware that a property with ID == 0 is a special case: It does not have a type, and its value is the section's dictionary. Another special case are strings: Two properties may have the different types Variant.VT_LPSTR and Variant.VT_LPWSTR;

      Overrides:
        `equals` in class `java.lang.Object`
      See Also:
        `Object.equals(java.lang.Object)`

    - #### hashCode

          public int hashCode()

      Overrides:
        `hashCode` in class `java.lang.Object`
      See Also:
        `Object.hashCode()`

    - #### toString

          public java.lang.String toString()

      Overrides:
        `toString` in class `java.lang.Object`
      See Also:
        `Object.toString()`

    - #### toString

          public java.lang.String toString(int codepage,
                                           PropertyIDMap idMap)

    - #### write

          public int write(java.io.OutputStream out,
                           int codepage)
                    throws java.io.IOException,
                           WritingNotSupportedException

      Writes the property to an output stream.
      Parameters:
        `out` - The output stream to write to.
        `codepage` - The codepage to use for writing non-wide strings
      Returns:
        the number of bytes written to the stream
      Throws:
        `java.io.IOException` - if an I/O error occurs
        `WritingNotSupportedException` - if a variant type is to be written that is not yet supported

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