APE Referenz

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

Methoden und Funktionen

function tak_APE_Valid

Pascal:

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

C:

TtakBool tak_APE_Valid (TtakAPEv2Tag ATag);

Liefert tak_True, wenn kein fataler Fehler aufgetreten ist. Dann kann das Objekt weiterverwendet werden.

function tak_APE_State

Pascal:

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

C:

TtakResult tak_APE_State (TtakAPEv2Tag ATag);

Liefert den aktuellen Fehlerstatus bzw. den schlimmsten bislang aufgetretenen Fehler.

Siehe auch:

tak_res_xxx, tak_res_ape_xxx

function tak_APE_GetErrorString

Pascal:

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

C:

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

Liefert in AString einen englischen Fehlertext für den Fehler AError. AStringSize enthält die Größe von AString in Bytes und sollte wenigstens tak_ErrorStringSizeMax sein.

Das Ergebnis ist immer tak_res_Ok, wenn die Parameter gültig sind.

function tak_APE_ReadOnly

Pascal:

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

C:

TtakBool tak_APE_ReadOnly (TtakAPEv2Tag ATag);

Liefert tak_True, wenn das Tag nicht modifiziert werden kann.

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);

Liefert in ADesc Informationen über das Tag.

Siehe auch:

TtakAPEv2TagDesc

function tak_APE_GetItemNum

Pascal:

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

C:

TtakInt32 tak_APE_GetItemNum (TtakAPEv2Tag ATag);

Liefert die Itemanzahl oder -1, wenn ein fataler Fehler aufgetreten ist.

function tak_APE_GetIndexOfKey

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);

Liefert in AIdx den Index des Items mit dem Schlüssel AKey. AKey muß ASCII-kodiert und null-terminiert sein. Alle Itemfunktionen verlangen, daß das gewünschte Item über seinen Index (bzw. seine Position in der Itemliste) spezifiziert wird.

Spezielle Funktionsergebnisse:

tak_res_tag_NotAvail

Es gibt kein Item mit diesem Schlüssel.

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);

Liefert in ADesc Informationen über das Item an Position AIdx.

Siehe auch:

TtakAPEv2ItemDesc

function tak_APE_GetItemKey

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);

Liefert in AKey den ASCII-kodierten null-terminierten Schüssel des Items an Position AIdx. AMaxSize spezifiziert die Größe von AKey in Bytes. ASize liefert die für die Aufnahme des Schlüssels erforderliche Mindestgröße zurück.

Spezielle Funktionsergebnisse:

tak_res_tag_BufferTooSmall

AKey ist zu klein und undefiniert.

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);

Kopiert den UTF8-kodierten Wert des Items an Position AIdx nach AValue. AMaxSize spezifiziert die Größe von AValue in Bytes. ASize liefert die für die Aufnahme des Itemwertes erforderliche Mindestgröße zurück.

Soll nur ASize ermittelt werden, ist als AValue Nil bzw. NULL zu übergeben.

Spezielle Funktionsergebnisse:

tak_res_tag_BufferTooSmall

AValue ist zu klein und undefiniert.

function tak_APE_GetTextItemValueAsAnsi

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);

Kopiert einen ausgewählten oder alle Werte des Textitems an Position AIdx als null-terminierten Ansi-String nach AValue. AMaxSize spezifiziert die Größe von AValue in Bytes. ASize liefert die für die Aufnahme des bzw. der Itemwerte erforderliche Mindestgröße zurück.

Soll nur ASize ermittelt werden, ist als AValue Nil bzw. NULL zu übergeben.

Sind einem Textitem mehrere Werte zugeordnet, kann mittels AValueIdx der gewünschte ausgewählt werden. Die Werteanzahl kann mittels tak_APE_GetItemDesc ermittelt werden.

Wird als AValueIdx -1 angegeben, werden alle Werte aneinandergehängt und dabei wird AValueSeparator (darf nicht 0 sein!) als Trennzeichen eingesetzt.

Ist einem Item nur ein Wert zugeordnet, ist das Ergebnis für einen AValueIdx von 0 und -1 identisch.

Spezielle Funktionsergebnisse:

tak_res_tag_InvalidType

Das Item ist kein Textitem.

tak_res_tag_BufferTooSmall

AValue ist zu klein. Es wurden nur AMaxSize - 1 Zeichen und die abschließende Null geschrieben. Ist AMaxSize 0, wurde gar nichts geschrieben.

Typen

type TtakAPEv2Tag

APEv2-Tag-Instanz.

Pascal:

type
  TtakAPEv2Tag = Pointer;

C:

typedef void * TtakAPEv2Tag;

type TtakAPEv2ItemType

Spezifiziert den Typ eines APEv2-Items.

Pascal:

type
  TtakAPEv2ItemType = TtakInt32;

C:

typedef TtakInt32 TtakAPEv2ItemType;

Folgende Werte sind möglich:

tak_apev2_ItemType_Text

tak_apev2_ItemType_Binary

tak_apev2_ItemType_External

Diese Werte repräsentieren die entsprechenden Angaben im APEv2-Itemheader.

type TtakAPEv2ItemDesc

Informationen über ein 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;

Felder:

ItemType

Der Itemtyp

Flags

Die Flags aus dem APEv2-Itemheader.

KeySize

Die Größe des ASCII-kodierten Schüsselwertes in Bytes (ohne abschließende 0).

ValueSize

Die Größe des UTF8-kodierten Itemwertes in Bytes. Enthält ein Item mehrere Werte, steht hier die Gesamtgröße.

ValueNum

Die Anzahl der Werte, die dem Schüssel zugeordnet sind. Kann nur bei Textitems größer 1 sein.

type TtakAPEv2TagDesc

Informationen über ein 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;

Felder:

Version

Tag-Version aus dem APEv2-Tag-Header.

Flags

Flags aus dem APEv2-Tag-Header.

StreamPos

Die Streamposition, an der das Tag beginnt, oder -1, wenn diese unbekannt ist.

TotSize

Die Gesamtgröße des Tags in Bytes.

Konstanten

const tak_apev2_Version = 2000

Die Bibliothek erzeugt Tags mit dieser Versionsnummer und liest Tags mit dieser und ggfs. einer höheren Versionsnummer (falls kompatibel).

const tak_apev2_ItemNumMax = 100

Die Bibliothek unterstützt Tags mit maximal so vielen Items.

const tak_apev2_TagSizeMax = 16 * 1024 * 1024

Die Bibliothek unterstützt Tags mit dieser Maximalgröße in Bytes.

const tak_res_ape_xxx

APEv2-Tag-spezifische Fehler und Warnungen.

Hierachisch: Gößere Werte = schlimmer.

Warnungen:

tak_res_ape_NotAvail

Die angeforderte Information (z.B. ein Item mit einem bestimmten Schüssel) ist nicht im Tag anthalten.

tak_res_ape_InvalidType

Die gewünschte Operation kann auf diesen Itemtyp nicht angewendet werden.

tak_res_ape_BufferTooSmall

Ein als Parameter übergebener Puffer ist zu klein um die gewünschten Daten vollständig aufnehmen zu können.

Fatale Fehler:

tak_res_ape_None

Der Stream enthält kein APEv2-Tag.

tak_res_ape_Incompatible

Das im Stream enthaltene Tag ist inkompatibel zu dieser Bibliotheksversion.

tak_res_ape_Invalid

Die Struktur des Tags enthält Fehler.

tak_res_ape_IoErr

Beim Streamzugriff ist ein IO-Fehler aufgetreten.

tak_res_ape_FatalErrorFirst

Codes >= diesem Wert sind fatale Fehler.