/*
 * The contents of this file are subject to the Mozilla Public
 * License Version 1.1 (the "License"); you may not use this file
 * except in compliance with the License. You may obtain a copy of
 * the License at http://www.mozilla.org/MPL/
 *
 * Software distributed under the License is distributed on an "AS
 * IS" basis, WITHOUT WARRANTY OF ANY KIND, either express or
 * implied. See the License for the specific language governing
 * rights and limitations under the License.
 *
 * The Original Code is MP4v2.
 *
 * The Initial Developer of the Original Code is Kona Blend.
 * Portions created by Kona Blend are Copyright (C) 2009.
 * All Rights Reserved.
 *
 * Contributor(s):
 *      Kona Blend, kona8lend@gmail.com
 */
#ifndef MP4V2_ITMF_GENERIC_H
#define MP4V2_ITMF_GENERIC_H

/**************************************************************************//**
 *
 *  @defgroup mp4_itmf_generic MP4v2 iTMF (iTunes Metadata Format) Generic
 *  @{
 *
 *  This is a low-level API used to manage iTMF metadata.
 *
 *  It provides support for virtually any kind of iTMF metadata item, including
 *  meaning atoms, sometimes referred to as reverse-DNS meanings. Structures
 *  are directly modified; i.e. there are no fuctions which modify values for
 *  you. There is little type-safety, logic checks, or specifications
 *  compliance checks. For these reasons it is recommended to use iTMF Tags API
 *  when possible.
 *
 *  At the heart of this API is an #MP4ItmfItem which corresponds to an iTMF
 *  metadata item atom. The item, and any recursive data structures contained
 *  within require <b>manual</b> memory management. The general rule to follow
 *  is that you must always check/free a ptr if you intend to resize data. In
 *  cases where you know the existing data size is exactly what is needed, you
 *  may overwrite the buffer contents.
 *
 *  Each item always has at least 1 data elements which corresponds to a data
 *  atom. Additionally, each item has optional <b>mean</b> and <b>name</b>
 *  values which correspond to mean and name atoms.
 *
 *  Each #MP4ItmfItem has a list of #MP4ItmfData. Similarily, care must be
 *  taken to manage memory with one key difference; these structures also have
 *  a valueSize field. If value is NULL then set valueSize=0. Otherwise, set
 *  valueSize to the size (in bytes) of value buffer.
 *
 *  In rare cases where the number of data elements in a single item is > 1,
 *  the user must manually free/alloc/copy the <b>elements</b> buffer and
 *  update <b>size</b> accordingly.
 *
 *  The mp4 file structure is modified only when MP4AddItem(), MP4SetItem() and
 *  MP4RemoveItem() are used. Simply free'ing the item list does not modify the
 *  mp4 file.
 *
 *  <b>iTMF Generic read workflow:</b>
 *
 *      @li MP4ItmfGetItems()
 *      @li inspect each item...
 *      @li MP4ItmfItemListFree()
 *
 *  <b>iTMF Generic read/modify/remove workflow:</b>
 *
 *      @li MP4ItmfGetItems()
 *      @li inspect/modify item...
 *      @li MP4ItmfSetItem() each modified item...
 *      @li MP4ItmfRemoveItem()...
 *      @li MP4ItmfItemListFree()
 *
 *  <b>iTMF Generic add workflow:</b>
 *
 *      @li MP4ItmfItemAlloc()
 *      @li MP4ItmfAddItem()
 *      @li MP4ItmfItemFree()
 *
 *  @par Warning:
 *  Care must be taken when using multiple mechanisms to modify an open mp4
 *  file as it is not thread-safe, nor does it permit overlapping different API
 *  workflows which have a begin/end to their workflow. That is to say do not
 *  interleave an iTMF Generic workflow with an iTMF Tags workflow.
 *
 *****************************************************************************/

/** Basic types of value data as enumerated in spec. */
typedef enum MP4ItmfBasicType_e
{
    MP4_ITMF_BT_IMPLICIT  = 0,   /**< for use with tags for which no type needs to be indicated */
    MP4_ITMF_BT_UTF8      = 1,   /**< without any count or null terminator */
    MP4_ITMF_BT_UTF16     = 2,   /**< also known as UTF-16BE */
    MP4_ITMF_BT_SJIS      = 3,   /**< deprecated unless it is needed for special Japanese characters */
    MP4_ITMF_BT_HTML      = 6,   /**< the HTML file header specifies which HTML version */
    MP4_ITMF_BT_XML       = 7,   /**< the XML header must identify the DTD or schemas */
    MP4_ITMF_BT_UUID      = 8,   /**< also known as GUID; stored as 16 bytes in binary (valid as an ID) */
    MP4_ITMF_BT_ISRC      = 9,   /**< stored as UTF-8 text (valid as an ID) */
    MP4_ITMF_BT_MI3P      = 10,  /**< stored as UTF-8 text (valid as an ID) */
    MP4_ITMF_BT_GIF       = 12,  /**< (deprecated) a GIF image */
    MP4_ITMF_BT_JPEG      = 13,  /**< a JPEG image */
    MP4_ITMF_BT_PNG       = 14,  /**< a PNG image */
    MP4_ITMF_BT_URL       = 15,  /**< absolute, in UTF-8 characters */
    MP4_ITMF_BT_DURATION  = 16,  /**< in milliseconds, 32-bit integer */
    MP4_ITMF_BT_DATETIME  = 17,  /**< in UTC, counting seconds since midnight, January 1, 1904; 32 or 64-bits */
    MP4_ITMF_BT_GENRES    = 18,  /**< a list of enumerated values */
    MP4_ITMF_BT_INTEGER   = 21,  /**< a signed big-endian integer with length one of { 1,2,3,4,8 } bytes */
    MP4_ITMF_BT_RIAA_PA   = 24,  /**< RIAA parental advisory; { -1=no, 1=yes, 0=unspecified }, 8-bit ingteger */
    MP4_ITMF_BT_UPC       = 25,  /**< Universal Product Code, in text UTF-8 format (valid as an ID) */
    MP4_ITMF_BT_BMP       = 27,  /**< Windows bitmap image */

    MP4_ITMF_BT_UNDEFINED = 255  /**< undefined */
} MP4ItmfBasicType;

/** Data structure.
 *  Models an iTMF data atom contained in an iTMF metadata item atom.
 */
typedef struct MP4ItmfData_s
{
    uint8_t          typeSetIdentifier; /**< always zero. */
    MP4ItmfBasicType typeCode;          /**< iTMF basic type. */
    uint32_t         locale;            /**< always zero. */
    uint8_t*         value;             /**< may be NULL. */
    uint32_t         valueSize;         /**< value size in bytes. */
} MP4ItmfData;

/** List of data. */
typedef struct MP4ItmfDataList_s
{
    MP4ItmfData* elements; /**< flat array. NULL when size is zero. */
    uint32_t     size;     /**< number of elements. */
} MP4ItmfDataList;

/** Item structure.
 *  Models an iTMF metadata item atom contained in an ilst atom.
 */
typedef struct MP4ItmfItem_s
{
    void* __handle; /**< internal use only. */

    char*           code;     /**< four-char code identifing atom type. NULL-terminated. */
    char*           mean;     /**< may be NULL. UTF-8 meaning. NULL-terminated. */
    char*           name;     /**< may be NULL. UTF-8 name. NULL-terminated. */
    MP4ItmfDataList dataList; /**< list of data. can be zero length. */
} MP4ItmfItem;

/** List of items. */
typedef struct MP4ItmfItemList_s
{
    MP4ItmfItem* elements; /**< flat array. NULL when size is zero. */
    uint32_t     size;     /**< number of elements. */
} MP4ItmfItemList;

/** Allocate an item on the heap.
 *  @param code four-char code identifying atom type. NULL-terminated.
 *  @param numData number of data elements to allocate. Must be >= 1.
 *  @return newly allocated item.
 */
MP4V2_EXPORT
MP4ItmfItem* MP4ItmfItemAlloc(
    const char* code,
    uint32_t    numData );

/** Free an item (deep free).
 *  @param item to be free'd.
 */
MP4V2_EXPORT
void MP4ItmfItemFree(
    MP4ItmfItem* item );

/** Free an item list (deep free).
 *  @param itemList to be free'd.
 */
MP4V2_EXPORT
void MP4ItmfItemListFree(
    MP4ItmfItemList* itemList );

/** Get list of all items from file.
 *  @param hFile handle of file to operate on.
 *  @return On succes, list of items, which must be free'd. On failure, NULL.
 */
MP4V2_EXPORT
MP4ItmfItemList* MP4ItmfGetItems(
    MP4FileHandle hFile );

/** Get list of items by code from file.
 *  @param hFile handle of file to operate on.
 *  @param code four-char code identifying atom type. NULL-terminated.
 *  @return On succes, list of items, which must be free'd. On failure, NULL.
 */
MP4V2_EXPORT
MP4ItmfItemList* MP4ItmfGetItemsByCode(
    MP4FileHandle hFile,
    const char*   code );

/** Get list of items by meaning from file.
 *  Implicitly only returns atoms of code <b>{----}</b>.
 *  @param hFile handle of file to operate on.
 *  @param meaning UTF-8 meaning. NULL-terminated.
 *  @param name may be NULL. UTF-8 name. NULL-terminated.
 *  @return On succes, list of items, which must be free'd. On failure, NULL.
 */
MP4V2_EXPORT
MP4ItmfItemList* MP4ItmfGetItemsByMeaning(
    MP4FileHandle hFile,
    const char*   meaning,
    const char*   name );

/** Add an item to file.
 *  @param hFile handle of file to operate on.
 *  @param item object to add.
 *  @return <b>true</b> on success, <b>false</b> on failure.
 */
MP4V2_EXPORT
bool MP4ItmfAddItem(
    MP4FileHandle      hFile,
    const MP4ItmfItem* item );

/** Overwrite an existing item in file.
 *  @param hFile handle of file to operate on.
 *  @param item object to overwrite. Must have a valid index obtained from prior get.
 *  @return <b>true</b> on success, <b>false</b> on failure.
 */
MP4V2_EXPORT
bool MP4ItmfSetItem(
    MP4FileHandle      hFile,
    const MP4ItmfItem* item );

/** Remove an existing item from file.
 *  @param hFile handle of file to operate on.
 *  @param item object to remove. Must have a valid index obtained from prior get.
 *  @return <b>true</b> on success, <b>false</b> on failure.
 */
MP4V2_EXPORT
bool MP4ItmfRemoveItem(
    MP4FileHandle      hFile,
    const MP4ItmfItem* item );

/** @} ***********************************************************************/

#endif /* MP4V2_ITMF_GENERIC_H */