com.beaglebuddy.id3.v23.frame_body

## Class ID3v23FrameBodyLinkedInformation

- java.lang.Object
- - com.beaglebuddy.util.Utility
  - - com.beaglebuddy.id3.v23.frame_body.ID3v23FrameBodyUtility
    - - com.beaglebuddy.id3.v23.frame_body.ID3v23FrameBody
      - - com.beaglebuddy.id3.v23.frame_body.ID3v23FrameBodyLinkedInformation

-     public class ID3v23FrameBodyLinkedInformation
      extends ID3v23FrameBody

  A linked information frame body is associated with an ID3v2.3 `LINK` `frame` which is used to link information from another ID3v2 tag that might reside in another audio file or alone in a binary file. The linked information frame body contains the following fields:

  Linked Information Frame Body Fields
  | Field | Description
  --- | --- | ---
  1. | `linkedFrameType` | type of ID3v2.3 frame being linked.
  2. | url | reference to the file where the frame is given.
  3. | additionalIdData | this optional field is used to help locate a specific frame in another file when the frame type alone is not sufficient to uniquely identify it. For example, an ID3v2.3 tag may contain several images, such as the `CD front cover`, `CD back cover`, image of a `live performance`, etc. Thus, the `attached picture` frame type alone is not enough to uniquely identify a single, specific frame. The frames `IPLS`, `MCDI`, `ETCO`, `MLLT`, `SYTC`, `RVAD`, `EQUA`, `RVRB`, `RBUF`, the text information frames (`TALB`, `TBPM`, `TCOM`, `TCON`, `TCOP`, `TDAT`, `TDLY`, `TENC`, `TEXT`, `TFLT`, `TIME`, `TIT1`, `TIT2`, `TIT3`, `TKEY`, `TLAN`, `TLEN`, `TMED`, `TOAL`, `TOFN`, `TOLY`, `TOPE`, `TORY`, `TOWN`, `TPE1`, `TPE2`, `TPE3`, `TPE4`, `TPOS`, `TPUB`, `TRCK`, `TRDA`, `TRSN`, `TRSO`, `TSIZ`, `TSRC`, `TSSE`, `TYER`), and the URL link frames (`WCOM`, `WCOP`, `WOAF`, `WOAR`, `WOAS`, `WORS`, `WPAY`, `WPUB`) may be linked without any additional ID data. The `AENC`, `APIC`, `GEOB` and `TXXX` frames may be linked with the content descriptor as additional ID data. The `COMM`, `SYLT` and `USLT` frames may be linked with the three character ISO-639-2 `language code` followed by a description as additional ID data.

  There may be more than one linked information frame, but only one with the same contents.

  See Also:
    `ID3v23Frame`, ID3 tag version 2.3.0 standard, wikipedia history of ID3 tags

- - ### Field Summary

    - ### Fields inherited from class com.beaglebuddy.id3.v23.frame_body.ID3v23FrameBody

      `buffer, dirty, frameType`

    - ### Fields inherited from class com.beaglebuddy.id3.v23.frame_body.ID3v23FrameBodyUtility

      `nextNullTerminatorIndex, nullTerminatorIndex`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `ID3v23FrameBodyLinkedInformation()` The default constructor is called when creating a new frame.
    `ID3v23FrameBodyLinkedInformation(FrameType linkedFrameType, java.lang.String url, byte[] additionalIdData)` This constructor is called when creating a new frame.
    `ID3v23FrameBodyLinkedInformation(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
    --- | ---
    `byte[]` | `getAdditionalIdData()` gets the additional id data which is used to help locate a specific frame in another file when the frame type alone is not sufficient to uniquely identify it.
    `FrameType` | `getLinkedFrameType()` gets the type of ID3v2.3 frame that is linked.
    `java.lang.String` | `getURL()` gets the url which holds a reference to the file which contains the linked frame.
    `void` | `parse()` parses the raw bytes of the frame body and stores the parsed values in the frame's fields.
    `void` | `setAdditionalIdData(byte[] additionalIdData)` sets the additional id data which is used to help locate a specific frame in another file when the frame type alone is not sufficient to uniquely identify it.
    `void` | `setBuffer()` If the frame body's values have been modified, then resize the raw binary buffer and store the new values there.
    `void` | `setLinkedFrameType(FrameType linkedFrameType)` sets the type of ID3v2.3 frame that is linked.
    `void` | `setURL(java.lang.String url)` sets the url which holds a reference to the file which contains the linked frame.
    `java.lang.String` | `toString()` gets a string representation of the linked information frame body showing all of the frame's fields and their values.

    - ### Methods inherited from class com.beaglebuddy.id3.v23.frame_body.ID3v23FrameBody

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

    - ### Methods inherited from class com.beaglebuddy.id3.v23.frame_body.ID3v23FrameBodyUtility

      `getNextNullTerminator, pricesToString, stringToBytes`

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

      `bytesToInt, bytesToInt, bytesToShort, bytesToShort, bytesToSynchsafeInt, bytesToSynchsafeShort, formateDate, 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

    - #### ID3v23FrameBodyLinkedInformation

          public ID3v23FrameBodyLinkedInformation()

      The default constructor is called when creating a new frame. The default values used are:
      - `attached picture` frame type
      - empty URL
      - no additional id data

    - #### ID3v23FrameBodyLinkedInformation

          public ID3v23FrameBodyLinkedInformation(FrameType linkedFrameType,
                                          java.lang.String url,
                                          byte[] additionalIdData)

      This constructor is called when creating a new frame.
      Parameters:
        `linkedFrameType` - the type of ID3v2.3 linked frame.
        `url` - the url which holds a reference to the file which contains the linked frame.
        `additionalIdData` - the extra data which together with the frame type uniquely identifies a single frame in another file.

    - #### ID3v23FrameBodyLinkedInformation

          public ID3v23FrameBodyLinkedInformation(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 linked information 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 `ID3v23FrameBody`
      Throws:
        `java.lang.IllegalArgumentException` - if an invalid value is detected while parsing the frame body's raw bytes.

    - #### getLinkedFrameType

          public FrameType getLinkedFrameType()

      gets the type of ID3v2.3 frame that is linked.
      Returns:
        the type of ID3v2.3 frame that is linked.
      See Also:
        `setLinkedFrameType(FrameType)`

    - #### setLinkedFrameType

          public void setLinkedFrameType(FrameType linkedFrameType)

      sets the type of ID3v2.3 frame that is linked.
      Parameters:
        `linkedFrameType` - the type of ID3v2.3 frame that is linked.
      See Also:
        `ID3v23FrameBody.getFrameType()`

    - #### getURL

          public java.lang.String getURL()

      gets the url which holds a reference to the file which contains the linked frame.
      Returns:
        the url which holds a reference to the file which contains the linked frame.
      See Also:
        `setURL(String)`

    - #### setURL

          public void setURL(java.lang.String url)

      sets the url which holds a reference to the file which contains the linked frame.
      Parameters:
        `url` - the url which holds a reference to the file which contains the linked frame.
      See Also:
        `getURL()`

    - #### getAdditionalIdData

          public byte[] getAdditionalIdData()

      gets the additional id data which is used to help locate a specific frame in another file when the frame type alone is not sufficient to uniquely identify it.
      Returns:
        the extra data which together with the frame type uniquely identifies a single frame in another file.
      See Also:
        `setAdditionalIdData(byte[])`

    - #### setAdditionalIdData

          public void setAdditionalIdData(byte[] additionalIdData)

      sets the additional id data which is used to help locate a specific frame in another file when the frame type alone is not sufficient to uniquely identify it.
      Parameters:
        `additionalIdData` - the extra data which together with the frame type uniquely identifies a single frame in another file.
      See Also:
        `getAdditionalIdData()`

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

    - #### toString

          public java.lang.String toString()

      gets a string representation of the linked information 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.