com.beaglebuddy.id3.v24

## Class ID3v24TagExtendedHeader

- java.lang.Object
- - com.beaglebuddy.id3.v24.ID3v24TagExtendedHeader

-     public class ID3v24TagExtendedHeader
      extends java.lang.Object

  This class provides methods for reading and writing the optional ID3v2.4 tag extended header. It contains fields that are not vital to the processing of the ID3v2.4 tag and hence is optional. The ID3v2.4 tag extended header, if present, is at least 10 bytes long and directly follows the standard tag header.

  The structure of an .mp3 file containing an ID3v2.4 tag is shown below.

  An ID3v2.4 extended header contains the following fields:

  ID3v2.4 Tag Extended Header Fields
  | Field | Description
  --- | --- | ---
  1. | size | specifies the size, in bytes, of the extended header.
  2. | tagIsAnUpdate | this flag indicates whether the tag is an update of a tag found earlier in the present .mp3 file or stream.
  3. | CRCDataPresent | this flag indicates whether the CRC for the .mp3 file has been calculated and the result stored in the CRCData field.
  4. | tagHasRestrictions | this flag indicates whether whether the ID3v2.4 tag had any restrictions when it was encoded.
  5. | CRCData | valid only if the CRCDataPresent flag is set, this field contains the actual CRC data for the .mp3 file.
  6. | tagSizeRestriction | valid only if the tagHasRestrictions flag is set, this field specifies the restrictions on the size of the ID3v2.4 tag and on the number of frames in the tag.
  7. | textEncodingRestriction | valid only if the tagHasRestrictions flag is set, this field specifies the restrictions on the which character sets may be used to encode strings.
  8. | textSizeRestriction | valid only if the tagHasRestrictions flag is set, this field specifies the restrictions on the size of text strings within the ID3v2.4 tag.
  9. | imageEncodingRestrictiond | valid only if the tagHasRestrictions flag is set, this field specifies the restrictions on the which image formats may be used to encode images.
  10. | imageSizeRestriction | valid only if the tagHasRestrictions flag is set, this field specifies the restrictions on the dimensions of images within the ID3v2.4 tag.

  See Also:
    ID3 tag version 2.4.0 standard, wikipedia history of ID3 tags

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `ID3v24TagExtendedHeader()` The default constructor is called when creating a new ID3v2.4 tag extended header.
    `ID3v24TagExtendedHeader(java.io.InputStream inputStream)` This constructor is called when reading in an existing ID3v2.tag 4 extended header from an .mp3 file.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `byte[]` | `getCRCData()` gets the CRC data for this .mp3 file..
    `ImageEncodingRestriction` | `getImageEncodingRestriction()`
    `ImageSizeRestriction` | `getImageSizeRestriction()`
    `int` | `getSize()` gets the total number of bytes in the ID3v2.4 tag extended header.
    `TagSizeRestriction` | `getTagSizeRestriction()`
    `TextEncodingRestriction` | `getTextEncodingRestriction()`
    `TextSizeRestriction` | `getTextSizeRestriction()`
    `boolean` | `isCRCDataPresent()` get whether this ID3v2.4 tag has a Cyclic Redundancy Check (CRC-32 [ISO-3309]).
    `boolean` | `isDirty()` indicates whether or not the tag's extended header's fields have been modified.
    `boolean` | `isTagIsAnUpdate()` get whether this ID3v2.4 tag is an update of a tag found earlier in the .mp3 file or stream.
    `void` | `save(java.io.OutputStream outputStream)` save the ID3v2.4 tag extended header to the .mp3 file.
    `void` | `save(java.io.RandomAccessFile file)` save the ID3v2.4 tag extended header to the .mp3 file.
    `void` | `setBuffer()` if the tag's extended header's values have been modified, then resize the raw binary buffer and store the new values there.
    `void` | `setCRCData(byte[] CRCData)` sets the CRC data for this .mp3 file.
    `void` | `setCRCDataPresent(boolean CRCDataPresent)` set whether this ID3v2.4 tag contains CRC data.
    `void` | `setImageEncodingRestriction(ImageEncodingRestriction imageEncodingRestriction)` set the restriction on which character sets may be used to encode image strings within the ID3v2.4 tag.
    `void` | `setImageSizeRestriction(ImageSizeRestriction imageSizeRestriction)` sets the restriction on the size of image strings within the ID3v2.4 tag.
    `void` | `setTagHasRestrictions(boolean tagHasRestrictions)` set whether the ID3v2.4 tag has any restrictions.
    `void` | `setTagIsAnUpdate(boolean tagIsAnUpdate)` set whether this ID3v2.4 tag is an update of a tag found earlier in the .mp3 file or stream.
    `void` | `setTagSizeRestriction(TagSizeRestriction tagSizeRestriction)` sets the restriction on the size of the ID3v2.4 tag and on the number of frames it may contain.
    `void` | `setTextEncodingRestriction(TextEncodingRestriction textEncodingRestriction)` set the restriction on which character sets may be used to encode text strings within the ID3v2.4 tag.
    `void` | `setTextSizeRestriction(TextSizeRestriction textSizeRestriction)` sets the restriction on the size of text strings within the ID3v2.4 tag.
    `boolean` | `tagHasRestrictions()`
    `java.lang.String` | `toString()` gets a string representation of the ID3v2.4 tag extended header showing the values of its fields.

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

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

- - ### Constructor Detail

    - #### ID3v24TagExtendedHeader

          public ID3v24TagExtendedHeader()

      The default constructor is called when creating a new ID3v2.4 tag extended header. The default values used are:
      - tag is not an update
      - tag does not have restrictions
      - no CRC

    - #### ID3v24TagExtendedHeader

          public ID3v24TagExtendedHeader(java.io.InputStream inputStream)
                                  throws java.io.IOException

      This constructor is called when reading in an existing ID3v2.tag 4 extended header from an .mp3 file.
      Parameters:
        `inputStream` - input stream pointing to the end of the beginning of the ID3v2.4 tag extended header in the .mp3 file.
      Throws:
        `java.io.IOException` - if the ID3v2.4 tag extended header can not be loaded from the .mp3 file.

  - ### Method Detail

    - #### isDirty

          public boolean isDirty()

      indicates whether or not the tag's extended header's fields have been modified.
      Returns:
        whether or not the extended header has been modified.
      See Also:
        `setBuffer()`

    - #### setBuffer

          public void setBuffer()

      if the tag's extended header's values have been modified, then resize the raw binary buffer and store the new values there. When finished, reset the dirty flag to indicate that the buffer is up to date, and the extended header is now ready to be saved to the .mp3 file.

    - #### getSize

          public int getSize()

      gets the total number of bytes in the ID3v2.4 tag extended header.
      Returns:
        the total number of bytes in the ID3v2.4 tag extended header.

    - #### isTagIsAnUpdate

          public boolean isTagIsAnUpdate()
                                  throws java.lang.IllegalStateException

      get whether this ID3v2.4 tag is an update of a tag found earlier in the .mp3 file or stream.
      Returns:
        whether this ID3v2.4 tag is an update of a tag found earlier in the .mp3 file or stream.
      Throws:
        `java.lang.IllegalStateException` - if the extendedHeaderPresent flag is not true. The extendedHeaderPresent flag must be true in order to call this method.
      See Also:
        `setTagIsAnUpdate(boolean)`

    - #### setTagIsAnUpdate

          public void setTagIsAnUpdate(boolean tagIsAnUpdate)

      set whether this ID3v2.4 tag is an update of a tag found earlier in the .mp3 file or stream. If frames defined as unique are found in the current tag, they are to override any corresponding ones found in the earlier ID3v2.4 tag.
      Parameters:
        `tagIsAnUpdate` - whether this ID3v2.4 tag is an update of a tag found earlier in the .mp3 file or stream.
      See Also:
        `isTagIsAnUpdate()`

    - #### isCRCDataPresent

          public boolean isCRCDataPresent()

      get whether this ID3v2.4 tag has a Cyclic Redundancy Check (CRC-32 [ISO-3309]).
      Returns:
        whether this ID3v2.4 tag contains CRC data.
      See Also:
        `setCRCDataPresent(boolean)`

    - #### setCRCDataPresent

          public void setCRCDataPresent(boolean CRCDataPresent)

      set whether this ID3v2.4 tag contains CRC data. corresponding ones found in the earlier ID3v2.4 tag.
      Parameters:
        `CRCDataPresent` - whether this ID3v2.4 tag contains CRC data.
      See Also:
        `isTagIsAnUpdate()`

    - #### getCRCData

          public byte[] getCRCData()
                            throws java.lang.IllegalStateException

      gets the CRC data for this .mp3 file..
      Returns:
        the CRC data for this .mp3 file..
      Throws:
        `java.lang.IllegalStateException` - if the CRCDataPresent flag is not set.
      See Also:
        `setCRCData(byte[])`

    - #### setCRCData

          public void setCRCData(byte[] CRCData)

      sets the CRC data for this .mp3 file. The CRC is calculated on all the data between the header and footer as indicated by the header's tag length field, minus the extended header. Note that this includes the padding (if there is any), but excludes the footer. The CRC-32 is stored as a 35 bit synchsafe integer, leaving the upper four bits always zeroed.
      Parameters:
        `CRCData` - the CRC data for this .mp3 file.
      See Also:
        `getCRCData()`

    - #### tagHasRestrictions

          public boolean tagHasRestrictions()

      Returns:
        if the ID3v2.4 extended header has tag restrictions.
      See Also:
        `setTagHasRestrictions(boolean)`

    - #### setTagHasRestrictions

          public void setTagHasRestrictions(boolean tagHasRestrictions)

      set whether the ID3v2.4 tag has any restrictions.
      Parameters:
        `tagHasRestrictions` - whether the ID3v2.4 tag has any restrictions.
      See Also:
        `tagHasRestrictions()`

    - #### getTagSizeRestriction

          public TagSizeRestriction getTagSizeRestriction()
                                                   throws java.lang.IllegalStateException

      Returns:
        gets the restriction on the size of the ID3v2.4 tag and on the number of frames it may contain.
      Throws:
        `java.lang.IllegalStateException` - if the tagHasRestrictions flag is not set.
      See Also:
        `setTagSizeRestriction(TagSizeRestriction)`

    - #### setTagSizeRestriction

          public void setTagSizeRestriction(TagSizeRestriction tagSizeRestriction)

      sets the restriction on the size of the ID3v2.4 tag and on the number of frames it may contain.
      Parameters:
        `tagSizeRestriction` - the restriction on the total size of the ID3v2.4 tag and on the number of frames it may contain.
      See Also:
        `getTagSizeRestriction()`

    - #### getTextEncodingRestriction

          public TextEncodingRestriction getTextEncodingRestriction()
                                                             throws java.lang.IllegalStateException

      Returns:
        gets the restriction on which character sets may be used to encode text strings within the ID3v2.4 tag.
      Throws:
        `java.lang.IllegalStateException` - if the tagHasRestrictions flag is not set.
      See Also:
        `setTextEncodingRestriction(TextEncodingRestriction)`

    - #### setTextEncodingRestriction

          public void setTextEncodingRestriction(TextEncodingRestriction textEncodingRestriction)

      set the restriction on which character sets may be used to encode text strings within the ID3v2.4 tag.
      Parameters:
        `textEncodingRestriction` - the restriction on which character sets may be used to encode text strings within the ID3v2.4 tag.
      See Also:
        `getTextEncodingRestriction()`

    - #### getTextSizeRestriction

          public TextSizeRestriction getTextSizeRestriction()
                                                     throws java.lang.IllegalStateException

      Returns:
        gets the restriction on the size of text strings within the ID3v2.4 tag.
      Throws:
        `java.lang.IllegalStateException` - if the tagHasRestrictions flag is not set.
      See Also:
        `setTextSizeRestriction(TextSizeRestriction)`

    - #### setTextSizeRestriction

          public void setTextSizeRestriction(TextSizeRestriction textSizeRestriction)

      sets the restriction on the size of text strings within the ID3v2.4 tag.
      Parameters:
        `textSizeRestriction` - the restriction on the size of text strings within the ID3v2.4 tag.
      See Also:
        `getTextSizeRestriction()`

    - #### getImageEncodingRestriction

          public ImageEncodingRestriction getImageEncodingRestriction()
                                                               throws java.lang.IllegalStateException

      Returns:
        gets the restriction on which character sets may be used to encode image strings within the ID3v2.4 tag.
      Throws:
        `java.lang.IllegalStateException` - if the tagHasRestrictions flag is not set.
      See Also:
        `setImageEncodingRestriction(ImageEncodingRestriction)`

    - #### setImageEncodingRestriction

          public void setImageEncodingRestriction(ImageEncodingRestriction imageEncodingRestriction)

      set the restriction on which character sets may be used to encode image strings within the ID3v2.4 tag.
      Parameters:
        `imageEncodingRestriction` - the restriction on which character sets may be used to encode image strings within the ID3v2.4 tag.
      See Also:
        `getImageEncodingRestriction()`

    - #### getImageSizeRestriction

          public ImageSizeRestriction getImageSizeRestriction()
                                                       throws java.lang.IllegalStateException

      Returns:
        gets the restriction on the size of image strings within the ID3v2.4 tag.
      Throws:
        `java.lang.IllegalStateException` - if the tagHasRestrictions flag is not set.
      See Also:
        `setImageSizeRestriction(ImageSizeRestriction)`

    - #### setImageSizeRestriction

          public void setImageSizeRestriction(ImageSizeRestriction imageSizeRestriction)

      sets the restriction on the size of image strings within the ID3v2.4 tag.
      Parameters:
        `imageSizeRestriction` - the restriction on the size of image strings within the ID3v2.4 tag.
      See Also:
        `getImageSizeRestriction()`

    - #### save

          public void save(java.io.OutputStream outputStream)
                    throws java.io.IOException

      save the ID3v2.4 tag extended header to the .mp3 file.
      Parameters:
        `outputStream` - output stream pointing to the starting location of the ID3v2.4 tag extended header within the .mp3 file.
      Throws:
        `java.io.IOException` - if there was an error writing the ID3v2.4 tag extended header to the .mp3 file.

    - #### save

          public void save(java.io.RandomAccessFile file)
                    throws java.io.IOException

      save the ID3v2.4 tag extended header to the .mp3 file.
      Parameters:
        `file` - random access file pointing to the starting location of the ID3v2.4 tag extended header within the .mp3 file.
      Throws:
        `java.io.IOException` - if there was an error writing the ID3v2.4 tag extended header to the .mp3 file.

    - #### toString

          public java.lang.String toString()

      gets a string representation of the ID3v2.4 tag extended header showing the values of its fields.
      Overrides:
        `toString` in class `java.lang.Object`
      Returns:
        a string representation of the ID3v2.4 tag extended header.