com.beaglebuddy.id3.v24.frame_body

## Class ID3v24FrameBodyCommercial

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

-     public class ID3v24FrameBodyCommercial
      extends ID3v24FrameBody

  A commercial frame body is associated with an ID3v2.4 `COMR` `frame` which allows vendors to include a price offer in an .mp3 file. The commercial frame body contains the following fields:

  Commercial Frame Body Fields
  | Field | Description
  --- | --- | ---
  1. | `encoding` | character set used to `encode` the seller and description fields.
  2. | prices | the purchase `price` of the .mp3 file. The purchase price may be specified in equivalent currencies. For example, USD1.00 = GBP0.60 = EUR1.25, etc. However, there may only be one price for a given currency. That is, you may not specify USD1.00 and USD2.00.
  3. | validUntil | date in the format YYYYMMDD indicating how long the price(s) are valid for.
  4. | contactURL | URL or e-mail address with which the seller can be contacted.
  5. | `receivedAs` | indicates how the .mp3 audio file will be `delivered` after is has been bought.
  6. | seller | name of the vendor.
  7. | description | description of the .mp3 file.
  8. | pictureMimeType | an optional field that specifies the vendor's logo image mime type. Only image/png and image/jpeg are allowed. If omitted, image/ will be used.
  9. | sellerLogo | an optional field that contains the raw binary data of the the vendor's logo image. Both this field and the previous pictureMimeType field may be ommitted if the vendor does not have a logo image to attach.

  There may be more than one commercial frame in an ID3v2.4 `tag`, but only one with the same seller.

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

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `static class` | `ID3v24FrameBodyCommercial.ReceivedType` valid ID3v2.4 commercial received as types

  - ### 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
    `ID3v24FrameBodyCommercial()` The default constructor is called when creating a new frame.
    `ID3v24FrameBodyCommercial(Encoding encoding, java.util.List<Price> prices, java.lang.String validUntil, java.lang.String contactURL, ID3v24FrameBodyCommercial.ReceivedType receivedAs, java.lang.String seller, java.lang.String description, java.lang.String pictureMimeType, byte[] sellerLogo)` This constructor is called when creating a new frame.
    `ID3v24FrameBodyCommercial(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` | `getContactURL()` gets the url at which the seller can be contacted.
    `java.lang.String` | `getDescription()` gets the description of the song.
    `Encoding` | `getEncoding()` gets the character encoding of the seller and description fields.
    `java.lang.String` | `getPictureMimeType()` gets the mime type of the seller's logo.
    `java.util.List<Price>` | `getPrices()` gets the price(s) of the .mp3 song.
    `ID3v24FrameBodyCommercial.ReceivedType` | `getReceivedAs()` gets how the song was delivered to the buyer.
    `java.lang.String` | `getSeller()` gets the name of the seller.
    `byte[]` | `getSellerLogo()` gets the raw bytes of the seller's logo image.
    `java.lang.String` | `getValidUntil()` gets the date until which the price is valid.
    `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` | `setContactURL(java.lang.String contactURL)` sets the contact URL.
    `void` | `setDescription(java.lang.String description)` sets the description of the song.
    `void` | `setEncoding(Encoding encoding)` sets the character encoding of the seller and description fields.
    `void` | `setPictureMimeType(java.lang.String pictureMimeType)` sets the seller's logo's mime type.
    `void` | `setPrices(java.util.List<Price> prices)` sets the price(s) of the .mp3 song.
    `void` | `setReceivedAs(ID3v24FrameBodyCommercial.ReceivedType receivedAs)` sets how the song was delivered to the buyer.
    `void` | `setSeller(java.lang.String seller)` sets the name of the seller.
    `void` | `setSellerLogo(byte[] sellerLogo)` sets the raw bytes of the seller's logo image.
    `void` | `setValidUntil(java.lang.String validUntil)` sets how long the price is valid until.
    `java.lang.String` | `toString()` gets a string representation of the commercial 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, 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

    - #### ID3v24FrameBodyCommercial

          public ID3v24FrameBodyCommercial()

      The default constructor is called when creating a new frame. The default values used are:
      - ISO-8859-1 encoding
      - USD 0.00 price
      - valid until 01/01/2099
      - empty contact url
      - received type as other- see `setReceivedAs(com.beaglebuddy.id3.v24.frame_body.ID3v24FrameBodyCommercial.ReceivedType)`
      - empty seller
      - empty description
      - empty seller
      - empty mime type
      - empty seller logo

    - #### ID3v24FrameBodyCommercial

          public ID3v24FrameBodyCommercial(Encoding encoding,
                                   java.util.List<Price> prices,
                                   java.lang.String validUntil,
                                   java.lang.String contactURL,
                                   ID3v24FrameBodyCommercial.ReceivedType receivedAs,
                                   java.lang.String seller,
                                   java.lang.String description,
                                   java.lang.String pictureMimeType,
                                   byte[] sellerLogo)

      This constructor is called when creating a new frame.
      Parameters:
        `encoding` - character set used to encode the seller and the description fields.
        `prices` - price(s) paid for the song.
        `validUntil` - date until which the price is valid in the format YYYYMMDD.
        `contactURL` - url for contacting the seller.
        `receivedAs` - how the song was delivered to the buyer.
        `seller` - name of the seller.
        `description` - description of the song.
        `pictureMimeType` - mime type of the seller's logo image. this field is optional and may be set to null.
        `sellerLogo` - seller's logo image. this field is optional and may be set to null.

    - #### ID3v24FrameBodyCommercial

          public ID3v24FrameBodyCommercial(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 commercial 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 seller and description fields.
      Returns:
        the character encoding of the seller and description fields.
      See Also:
        `setEncoding(Encoding)`

    - #### setEncoding

          public void setEncoding(Encoding encoding)

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

    - #### getPrices

          public java.util.List<Price> getPrices()

      gets the price(s) of the .mp3 song. Mulitple prices may be specified in different currencies.
      Returns:
        the price(s) of the song.
      See Also:
        `setPrices(List)`

    - #### setPrices

          public void setPrices(java.util.List<Price> prices)

      sets the price(s) of the .mp3 song. The purchase price may be specified in a single currecny (ex: USD 0.99) or in equivalent currencies (USD1.00 = GBP0.60 = EUR1.25, etc.). However, there may only be one price for a given currency. That is, you may not specify USD1.00 and USD2.00.
      Parameters:
        `prices` - price(s) paid for the .mp3 file.
      See Also:
        `getPrices()`

    - #### getValidUntil

          public java.lang.String getValidUntil()

      gets the date until which the price is valid.
      Returns:
        the date until which the price is valid.
      See Also:
        `setValidUntil(String)`

    - #### setValidUntil

          public void setValidUntil(java.lang.String validUntil)

      sets how long the price is valid until.
      Parameters:
        `validUntil` - the date until which the price is valid.
      See Also:
        `getValidUntil()`

    - #### getContactURL

          public java.lang.String getContactURL()

      gets the url at which the seller can be contacted.
      Returns:
        the url at which the seller can be contacted.
      See Also:
        `setContactURL(String)`

    - #### setContactURL

          public void setContactURL(java.lang.String contactURL)

      sets the contact URL.
      Parameters:
        `contactURL` - the url at which the seller can be contacted.
      See Also:
        `getContactURL()`

    - #### getReceivedAs

          public ID3v24FrameBodyCommercial.ReceivedType getReceivedAs()

      gets how the song was delivered to the buyer.
      Returns:
        how the song was delivered to the buyer.
      See Also:
        `setReceivedAs(ReceivedType)`

    - #### setReceivedAs

          public void setReceivedAs(ID3v24FrameBodyCommercial.ReceivedType receivedAs)

      sets how the song was delivered to the buyer. The valid methods are listed below:

      Id | Delivery Method
      --- | ---
      0 | other
      1 | standard CD album with other songs
      2 | compressed audio on CD
      3 | file over the Internet
      4 | stream over the Internet
      5 | as note sheets
      6 | as note sheets in a book with other sheets
      7 | music on other media
      8 | non-musical merchandise

      Parameters:
        `receivedAs` - how the song was received by the buyer.
      See Also:
        `getReceivedAs()`

    - #### getSeller

          public java.lang.String getSeller()

      gets the name of the seller.
      Returns:
        the name of the seller.
      See Also:
        `setSeller(String)`

    - #### setSeller

          public void setSeller(java.lang.String seller)

      sets the name of the seller.
      Parameters:
        `seller` - the seller's name.
      See Also:
        `getSeller()`

    - #### getDescription

          public java.lang.String getDescription()

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

    - #### setDescription

          public void setDescription(java.lang.String description)

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

    - #### getPictureMimeType

          public java.lang.String getPictureMimeType()

      gets the mime type of the seller's logo.
      Returns:
        the mime type of the seller's logo.
      See Also:
        `setPictureMimeType(String)`

    - #### setPictureMimeType

          public void setPictureMimeType(java.lang.String pictureMimeType)

      sets the seller's logo's mime type.
      Parameters:
        `pictureMimeType` - the mime type of the seller's logo.
      See Also:
        `getPictureMimeType()`

    - #### getSellerLogo

          public byte[] getSellerLogo()

      gets the raw bytes of the seller's logo image.
      Returns:
        the raw bytes of the seller's logo image
      See Also:
        `setSellerLogo(byte[])`

    - #### setSellerLogo

          public void setSellerLogo(byte[] sellerLogo)

      sets the raw bytes of the seller's logo image.
      Parameters:
        `sellerLogo` - how the song was received by the buyer.
      See Also:
        `getSellerLogo()`

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