Copyright 2007 by Thomas Becker, D-49080 Osnabrück.
All rights reserved.
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.
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:
Pascal:
function tak_APE_GetErrorString (AError : TtakResult; AString : PChar; AStringSize : TtakInt32) : TtakResult; cdecl;
C:
TtakResult tak_APE_GetErrorString (TtakResult AError, char * 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.
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.
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:
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.
Pascal:
function tak_APE_GetIndexOfKey ( ATag : TtakAPEv2Tag; AKey : PChar; var AIdx : TtakInt32) : TtakResult; cdecl;
C:
TtakResult tak_APE_GetIndexOfKey (TtakAPEv2Tag ATag, const char * 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.
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:
Pascal:
function tak_APE_GetItemKey ( ATag : TtakAPEv2Tag; AIdx : TtakInt32; AKey : PChar; AMaxSize : TtakInt32; var ASize : TtakInt32) : TtakResult; cdecl;
C:
TtakResult tak_APE_GetItemKey (TtakAPEv2Tag ATag, TtakInt32 AIdx, char * 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.
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.
Pascal:
function tak_APE_GetTextItemValueAsAnsi ( ATag : TtakAPEv2Tag; AIdx : TtakInt32; AValueIdx : TtakInt32; AValueSeparator : Char; AValue : PChar; AMaxSize : TtakInt32; var ASize : TtakInt32) : TtakResult; cdecl;
C:
TtakResult tak_APE_GetTextItemValueAsAnsi (TtakAPEv2Tag ATag, TtakInt32 AIdx, TtakInt32 AValueIdx, char AValueSeparator, char * 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.
APEv2 tag instance.
Pascal:
type TtakAPEv2Tag = Pointer;
C:
typedef void * TtakAPEv2Tag;
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.
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.
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.
The library creates tags with this version number and reads tags with this or a higher version number (if compatible).
The maximum number of items supported by the library.
The maximum size of tags supported by the library (in bytes).
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.