# APE Reference

Copyright 2007 by Thomas Becker, D-49080 Osnabrück.
All rights reserved.

## Methods and functions

### function tak_APE_Valid

Pascal:

    function tak_APE_Valid (ATag : TtakAPEv2Tag) : TtakBool; cdecl;

C:

    TtakBool tak_APE_Valid (TtakAPEv2Tag ATag);

Returns tak_True if no fatal error occurred. Then the object is ready for further use.

### function tak_APE_State

Pascal:

    function tak_APE_State (ATag : TtakAPEv2Tag) : TtakResult; cdecl;

C:

    TtakResult tak_APE_State (TtakAPEv2Tag ATag);

Provides the current error status, respectively the worst error occurred so far.

See also:

tak_res_xxx, tak_res_ape_xxx

### function tak_APE_GetErrorString

Pascal:

    function tak_APE_GetErrorString (AError      : TtakResult;
                                     AString     : PtakAnsiChar;
                                     AStringSize : TtakInt32) : TtakResult; cdecl;

C:

    TtakResult tak_APE_GetErrorString (TtakResult     AError,
                                       TtakAnsiChar * AString,
                                       TtakInt32      AStringSize);

Provides an english error text for AError in AString. AStringSize contains the size of AString in Bytes and should be at least tak_ErrorStringSizeMax.

With valid parameters, the result is always tak_res_Ok.

### function tak_APE_ReadOnly

Pascal:

    function tak_APE_ReadOnly (ATag : TtakAPEv2Tag) : TtakBool; cdecl;

C:

    TtakBool tak_APE_ReadOnly (TtakAPEv2Tag ATag);

Returns tak_True if the tag cannot be modified.

### function tak_APE_GetDesc

Pascal:

    function tak_APE_GetDesc (    ATag  : TtakAPEv2Tag;
                              var ADesc : TtakAPEv2TagDesc) : TtakResult; cdecl;

C:

    TtakResult tak_APE_GetDesc (TtakAPEv2Tag       ATag,
                                TtakAPEv2TagDesc * ADesc);

Provides information about the tag in ADesc.

See also:

TtakAPEv2TagDesc

### function tak_APE_GetItemNum

Pascal:

    function tak_APE_GetItemNum (ATag : TtakAPEv2Tag) : TtakInt32; cdecl;

C:

    TtakInt32 tak_APE_GetItemNum (TtakAPEv2Tag ATag);

Returns the item count or -1 in case a fatal error occurred.

### function tak_APE_GetIndexOfKey

Pascal:

    function tak_APE_GetIndexOfKey (    ATag : TtakAPEv2Tag;
                                        AKey : PtakAnsiChar;
                                    var AIdx : TtakInt32) : TtakResult; cdecl;

C:

    TtakResult tak_APE_GetIndexOfKey (      TtakAPEv2Tag   ATag,
                                      const TtakAnsiChar * AKey,
                                            TtakInt32  *   AIdx);

Provides the index of the item with the key AKey in AIdx. AKey has to be coded in ASCII and null-terminated. All item functions require the particular item to be specified by its index (its position in the item list).

Special function results:

tak_res_tag_NotAvail

There is no item with this key.

### function tak_APE_GetItemDesc

Pascal:

    function tak_APE_GetItemDesc (    ATag  : TtakAPEv2Tag;
                                      AIdx  : TtakInt32;
                                  var ADesc : TtakAPEv2ItemDesc) : TtakResult; cdecl;

C:

    TtakResult tak_APE_GetItemDesc (TtakAPEv2Tag        ATag,
                                    TtakInt32           AIdx,
                                    TtakAPEv2ItemDesc * ADesc);

Provides information about the item at the index AIdx in ADesc.

See also:

TtakAPEv2ItemDesc

### function tak_APE_GetItemKey

Pascal:

    function tak_APE_GetItemKey (    ATag     : TtakAPEv2Tag;
                                     AIdx     : TtakInt32;
                                     AKey     : PtakAnsiChar;
                                     AMaxSize : TtakInt32;
                                 var ASize    : TtakInt32) : TtakResult; cdecl;

C:

    TtakResult tak_APE_GetItemKey (TtakAPEv2Tag   ATag,
                                   TtakInt32      AIdx,
                                   TtakAnsiChar * AKey,
                                   TtakInt32      AMaxSize,
                                   TtakInt32 *    ASize);

Provides in AKey the key of the item at the index AIdx, null-terminated and coded in ASCII. AMaxSize specifies the size of AKey in bytes. ASize provides the minimum space required to hold the key.

Special function results:

tak_res_tag_BufferTooSmall

AKey is too small and undefined.

### function tak_APE_GetItemValue

Pascal:

    function tak_APE_GetItemValue (    ATag     : TtakAPEv2Tag;
                                       AIdx     : TtakInt32;
                                       AValue   : Pointer;
                                       AMaxSize : TtakInt32;
                                   var ASize    : TtakInt32) : TtakResult; cdecl;

C:

    TtakResult tak_APE_GetItemValue (TtakAPEv2Tag  ATag,
                                     TtakInt32     AIdx,
                                     void *        AValue,
                                     TtakInt32     AMaxSize,
                                     TtakInt32 *   ASize);

Copies the UTF8-coded value of the item at the index AIdx to AValue. AMaxSize specifies the size of AValue in bytes. ASize provides the minimum space required to hold the item value.

If only ASize has to be detected, Nil (or NULL, respectively) must be provided as AValue.

Special function results:

tak_res_tag_BufferTooSmall

AValue is too small and undefined.

### function tak_APE_GetTextItemValueAsAnsi

Pascal:

    function tak_APE_GetTextItemValueAsAnsi (    ATag            : TtakAPEv2Tag;
                                                 AIdx            : TtakInt32;
                                                 AValueIdx       : TtakInt32;
                                                 AValueSeparator : TtakAnsiChar;
                                                 AValue          : PtakAnsiChar;
                                                 AMaxSize        : TtakInt32;
                                             var ASize           : TtakInt32) : TtakResult; cdecl;

C:

    TtakResult tak_APE_GetTextItemValueAsAnsi (TtakAPEv2Tag   ATag,
                                               TtakInt32      AIdx,
                                               TtakInt32      AValueIdx,
                                               TtakAnsiChar   AValueSeparator,
                                               TtakAnsiChar * AValue,
                                               TtakInt32      AMaxSize,
                                               TtakInt32 *    ASize);

Copies one selected or all values of the text item at the index AIdx to AValue as a null-terminated ANSI string. AMaxSize specifies the size of AValue in bytes. ASize returns the minimum size required for holding the item value(s).

If only ASize has to be detected, Nil (or NULL, respectively) must be provided as AValue.

In case a text item has multiple values, the desired value can be selected by means of AValueIdx. The number of values can be detected using tak_APE_GetItemDesc.

If -1 is given as AValueIdx, all values are joined and AValueSeparator (must not be 0!) is used as a separator.

If an item has only one value, the results of the AValueIdx 0 and -1 are identical.

Special function results:

tak_res_tag_InvalidType

The item is not a text item.

tak_res_tag_BufferTooSmall

AValue is too small. Only AMaxSize - 1 characters and the trailing 0 have been written. If AMaxSize is 0, nothing has been written.

## Types

### type TtakAPEv2Tag

APEv2 tag instance.

Pascal:

    type
      TtakAPEv2Tag = Pointer;

C:

    typedef void * TtakAPEv2Tag;

### type TtakAPEv2ItemType

Specifies the type of an APEv2 item.

Pascal:

    type
      TtakAPEv2ItemType = TtakInt32;

C:

    typedef TtakInt32 TtakAPEv2ItemType;

Following values are possible:

tak_apev2_ItemType_Text

tak_apev2_ItemType_Binary

tak_apev2_ItemType_External

These values represent the according information in the APEv2 item header.

### type TtakAPEv2ItemDesc

Information about an APEv2 item.

Pascal:

    type
      TtakAPEv2ItemDesc = packed record
        ItemType  : TtakAPEv2ItemType;
        Flags     : TtakUInt32;
        KeySize   : TtakUInt32;
        ValueSize : TtakUInt32;
        ValueNum  : TtakInt32;
      end;

C:

    typedef struct TtakAPEv2ItemDesc {
        TtakAPEv2ItemType ItemType;
        TtakUInt32        Flags;
        TtakUInt32        KeySize;
        TtakUInt32        ValueSize;
        TtakInt32         ValueNum;
    } TtakAPEv2ItemDesc;

Fields:

ItemType

The item type

Flags

The flags from the APEv2 item header.

KeySize

The size of the ASCII-coded key values in bytes (without trailing 0).

ValueSize

The size of the UTF8-coded item value in bytes. If an item has multiple values, this is the total size.

ValueNum

The number of values assigned to a key. Can only be bigger than 1 with text items.

### type TtakAPEv2TagDesc

Information about an APEv2 tag.

Pascal:

    type
      TtakAPEv2TagDesc = packed record
        Version   : TtakUInt32;
        Flags     : TtakUInt32;
        StreamPos : TtakInt64;
        TotSize   : TtakInt64;
      end;

C:

    typedef struct TtakAPEv2TagDesc {
        TtakUInt32 Version;
        TtakUInt32 Flags;
        TtakInt64  StreamPos;
        TtakInt64  TotSize;
    } TtakAPEv2TagDesc;

Fields:

Version

Tag version from the APEv2 tag header.

Flags

Flags from the APEv2 tag header.

StreamPos

The stream position the Tag begins at, or -1 if the position is unknown.

TotSize

The total tag size in bytes.

## Constants

### const tak_apev2_Version = 2000

The library creates tags with this version number and reads tags with this or a higher version number (if compatible).

### const tak_apev2_ItemNumMax = 100

The maximum number of items supported by the library.

### const tak_apev2_TagSizeMax = 16 * 1024 * 1024

The maximum size of tags supported by the library (in bytes).

### const tak_res_ape_xxx

APEv2 tag-specific errors and warnings.

Hierarchy: Higher values = worse.

Warnings:

tak_res_ape_NotAvail

The requested information (an item with a particular key) is not contained in the tag.

tak_res_ape_InvalidType

The desired operation cannot be performed on this item type.

tak_res_ape_BufferTooSmall

A buffer given as a parameter is too small to hold the whole desired information.

Fatal errors:

tak_res_ape_None

The stream contains no APEv2 tag.

tak_res_ape_Incompatible

The tag contained in the stream is incompatible to this library version.

tak_res_ape_Invalid

The tag structure is erroneous.

tak_res_ape_IoErr

An IO error occurred during stream access.

tak_res_ape_FatalErrorFirst

Codes >= this value are fatal errors.