com.beaglebuddy.id3.v24.frame_body

## Class ID3v24FrameBodyGeneralEncapsulatedObject

- java.lang.Object
- - com.beaglebuddy.util.Utility
  - - com.beaglebuddy.id3.v24.frame_body.ID3v24FrameBodyUtility
    - - com.beaglebuddy.id3.v24.frame_body.ID3v24FrameBody
      - - com.beaglebuddy.id3.v24.frame_body.ID3v24FrameBodyGeneralEncapsulatedObject

-     public class ID3v24FrameBodyGeneralEncapsulatedObject
      extends ID3v24FrameBody

  A general encapsulated object frame body is associated with an ID3v2.4 `GEOB` `frame` which is used to embed a file in the .mp3 file. The file may be of any type. This is a generalization of the `attached picture` frame which only allows image files to be embedded in the .mp3 file. The general encapsulated object frame body contains the following fields:

  General Encapsulated Object Frame Body Fields
  | Field | Description
  --- | --- | ---
  1. | `encoding` | character set used to `encode` the filename and description fields.
  2. | mimeType | the MIME type and subtype for the encapsulated object. This field is optional and may be left blank.
  3. | filename | name of the file from which the encapsulated object was read from. This field is optional and may be left blank.
  4. | description | description of the encapsulated object.
  5. | object | raw binary data of the encapsulated object.

  There may be more than one general encapsulated object frame in an ID3v2.4 `tag`, but only one with the same description field.

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

- - ### Field Summary

    - ### Fields inherited from class com.beaglebuddy.id3.v24.frame_body.ID3v24FrameBody

      `buffer, dirty, frameType`

    - ### Fields inherited from class com.beaglebuddy.id3.v24.frame_body.ID3v24FrameBodyUtility

      `nextNullTerminatorIndex, nullTerminatorIndex`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `ID3v24FrameBodyGeneralEncapsulatedObject()` The default constructor is called when creating a new frame.
    `ID3v24FrameBodyGeneralEncapsulatedObject(Encoding encoding, java.lang.String mimeType, java.lang.String filename, java.lang.String description, byte[] object)` This constructor is called when creating a new frame.
    `ID3v24FrameBodyGeneralEncapsulatedObject(java.io.InputStream inputStream, int frameBodySize)` This constructor is called when reading in an existing frame from an .mp3 file.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `java.lang.String` | `getDescription()` gets the description of the content.
    `Encoding` | `getEncoding()` gets the character encoding of the filename and desctiption fields.
    `java.lang.String` | `getFilename()` gets the name of the file from which the encapsulated object was read from.
    `java.lang.String` | `getMimeType()` gets the mime type of the encapsulated object.
    `byte[]` | `getObject()` gets the raw binary data of the encapsulated object.
    `void` | `parse()` parses the raw bytes of the frame body and stores the parsed values in the frame's fields.
    `void` | `setBuffer()` If the frame body's values have been modified, then resize the raw binary buffer and store the new values there.
    `void` | `setDescription(java.lang.String description)` sets the description of the content.
    `void` | `setEncoding(Encoding encoding)` sets the character encoding of the filename and desctiption fields.
    `void` | `setFilename(java.lang.String filename)` sets the name of the file from which the encapsulated object was read from.
    `void` | `setMimeType(java.lang.String mimeType)` sets the mime type of the encapsulated object.
    `void` | `setObject(byte[] object)` sets the raw binary data of the encapsulated object.
    `java.lang.String` | `toString()` gets a string representation of the general encapsulated object frame body showing all of the frame's fields and their values.

    - ### Methods inherited from class com.beaglebuddy.id3.v24.frame_body.ID3v24FrameBody

      `getFrameType, getNextNullTerminator, getSize, isDirty, save, save`

    - ### Methods inherited from class com.beaglebuddy.id3.v24.frame_body.ID3v24FrameBodyUtility

      `getNextNullTerminator, pricesToString, stringToBytes`

    - ### Methods inherited from class com.beaglebuddy.util.Utility

      `bytesToInt, bytesToInt, bytesToShort, bytesToShort, bytesToSynchsafeInt, bytesToSynchsafeShort, formateDate, getUTF16String, getUTF8String, hex, hex, hex, intToBytes, littleEndianBytesToInt, pad, shortToBytes, synchsafeIntToBytes`

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

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

- - ### Constructor Detail

    - #### ID3v24FrameBodyGeneralEncapsulatedObject

          public ID3v24FrameBodyGeneralEncapsulatedObject()

      The default constructor is called when creating a new frame. The default values used are:
      - UTF-16 encoding
      - empty mime type
      - empty filename
      - "encapsulated object" as the description
      - 0 byte object

    - #### ID3v24FrameBodyGeneralEncapsulatedObject

          public ID3v24FrameBodyGeneralEncapsulatedObject(Encoding encoding,
                                                  java.lang.String mimeType,
                                                  java.lang.String filename,
                                                  java.lang.String description,
                                                  byte[] object)

      This constructor is called when creating a new frame.
      Parameters:
        `encoding` - character set used to encode the description field.
        `mimeType` - mime type of the encapsulated object. this field is optional, and may be empty, as is the filename field.
        `filename` - filename that held the encapuslated object on disk.
        `description` - description of the content.
        `object` - raw binary data of the encapsulated object.

    - #### ID3v24FrameBodyGeneralEncapsulatedObject

          public ID3v24FrameBodyGeneralEncapsulatedObject(java.io.InputStream inputStream,
                                                  int frameBodySize)
                                                   throws java.io.IOException

      This constructor is called when reading in an existing frame from an .mp3 file. This is then followed by a call to the parse() method.
      Parameters:
        `inputStream` - input stream pointing to a general encapsulated object frame body in the .mp3 file.
        `frameBodySize` - size (in bytes) of the frame's body.
      Throws:
        `java.io.IOException` - if there is an error while reading the frame body.

  - ### Method Detail

    - #### parse

          public void parse()
                     throws java.lang.IllegalArgumentException

      parses the raw bytes of the frame body and stores the parsed values in the frame's fields.
      Overrides:
        `parse` in class `ID3v24FrameBody`
      Throws:
        `java.lang.IllegalArgumentException` - if an invalid value is detected while parsing the frame body's raw bytes.

    - #### getEncoding

          public Encoding getEncoding()

      gets the character encoding of the filename and desctiption fields.
      Returns:
        the character encoding of the filename and desctiption fields.
      See Also:
        `setEncoding(Encoding)`

    - #### setEncoding

          public void setEncoding(Encoding encoding)

      sets the character encoding of the filename and desctiption fields.
      Parameters:
        `encoding` - the character set used to encode the filename and desctiption fields. Only ISO 8859-1 and UTF-16 are allowed.
      See Also:
        `getEncoding()`

    - #### getMimeType

          public java.lang.String getMimeType()

      gets the mime type of the encapsulated object.
      Returns:
        the mime type of the encapsulated object.
      See Also:
        `setMimeType(String)`

    - #### setMimeType

          public void setMimeType(java.lang.String mimeType)

      sets the mime type of the encapsulated object. This field is optional and may be left blank.
      Parameters:
        `mimeType` - the mime type.
      See Also:
        `getMimeType()`

    - #### getFilename

          public java.lang.String getFilename()

      gets the name of the file from which the encapsulated object was read from.
      Returns:
        the name of the file from which the encapsulated object was read from.
      See Also:
        `setFilename(String)`

    - #### setFilename

          public void setFilename(java.lang.String filename)

      sets the name of the file from which the encapsulated object was read from.
      Parameters:
        `filename` - the name of the file from which the encapsulated object was read from.
      See Also:
        `getFilename()`

    - #### getDescription

          public java.lang.String getDescription()

      gets the description of the content.
      Returns:
        the description of the content.
      See Also:
        `setDescription(String)`

    - #### setDescription

          public void setDescription(java.lang.String description)

      sets the description of the content.
      Parameters:
        `description` - the description of the content.
      See Also:
        `getDescription()`

    - #### getObject

          public byte[] getObject()

      gets the raw binary data of the encapsulated object.
      Returns:
        the raw binary data of the encapsulated object.
      See Also:
        `setObject(byte[])`

    - #### setObject

          public void setObject(byte[] object)

      sets the raw binary data of the encapsulated object.
      Parameters:
        `object` - byte[] array containing the raw binary data of the encapsulated object.
      See Also:
        `getObject()`

    - #### setBuffer

          public void setBuffer()

      If the frame body's values have been modified, then resize the raw binary buffer and store the new values there. When finished, the dirty flag is reset to indicate that the buffer is up to date, and the frame is now ready to be saved to the .mp3 file.
      Overrides:
        `setBuffer` in class `ID3v24FrameBody`

    - #### toString

          public java.lang.String toString()

      gets a string representation of the general encapsulated object frame body showing all of the frame's fields and their values.
      Overrides:
        `toString` in class `java.lang.Object`
      Returns:
        a string representation of the frame body.