![]() | Patrick's Programming Library Version 6.4.21 - Dokumentation |
Klasse zum Lesen und schreiben von PFP-Files Version 3. Mehr ...
Öffentliche Methoden | |
PFPFile () | |
Konstruktor der Klasse. Mehr ... | |
virtual | ~PFPFile () |
Destruktor der Klasse. Mehr ... | |
int | AddChunk (PFPChunk *chunk) |
Chunk hinzufügen. Mehr ... | |
void | Clear () |
Inhalt der Klasse löschen. Mehr ... | |
int | DeleteChunk (PFPChunk *chunk) |
Bestimmten Chunk löschen. Mehr ... | |
int | DeleteChunk (const char *chunkname) |
Chunk nach Namen löschen. Mehr ... | |
PFPChunk * | FindFirstChunk (const char *chunkname) |
Ersten Chunk mit einem bestimmten Namen finden. Mehr ... | |
PFPChunk * | FindNextChunk (const char *chunkname=NULL) |
Nächsten Chunk mit einem bestimmten Namen finden. Mehr ... | |
const char * | GetAuthor () |
Pointer auf den Author holen. Mehr ... | |
CCompression::Algorithm | GetCompression () |
Kompressionsverfahren auslesen. Mehr ... | |
const char * | GetCopyright () |
Pointer auf den Copyright-String holen. Mehr ... | |
const char * | GetDescription () |
Pointer auf die Description holen. Mehr ... | |
PFPChunk * | GetFirst () |
Pointer auf ersten Chunk holen. Mehr ... | |
const char * | GetID () |
ID auslesen. Mehr ... | |
int | GetMainVersion () |
Hauptversion auslesen. Mehr ... | |
const char * | GetName () |
Pointer auf den Namen holen. Mehr ... | |
PFPChunk * | GetNext () |
Pointer auf nächsten Chunk holen. Mehr ... | |
int | GetSubVersion () |
Unterversion auslesen. Mehr ... | |
void | GetVersion (int *main, int *sub) |
Version auslesen. Mehr ... | |
bool | Ident (CFileObject &ff) |
Prüfen, ob es sich um ein PFP-File handelt. Mehr ... | |
bool | Ident (const CString &file) |
Prüfen, ob es sich um ein PFP-File handelt. Mehr ... | |
virtual void | List () |
Chunks auf STDOUT auflisten. Mehr ... | |
int | Load (CFileObject *ff) |
PFP-File laden. Mehr ... | |
int | Load (const char *file) |
PFP-File laden. Mehr ... | |
virtual int | LoadRequest (const char *id, int mainversion, int subversion) |
Ladevorgang bestätigen. Mehr ... | |
void | Reset () |
Zeiger zum Durchwandern der Chunks zurücksetzen. Mehr ... | |
int | Save (const char *filename) |
PFP-File speichern. Mehr ... | |
int | SetAuthor (const char *author) |
Author setzen. Mehr ... | |
int | SetCompression (CCompression::Algorithm type) |
Kompression einstellen. Mehr ... | |
int | SetCopyright (const char *copy) |
Copyright setzen. Mehr ... | |
int | SetDescription (const char *descr) |
Description setzen. Mehr ... | |
int | SetId (const char *id) |
ID des PFP-Files setzen. Mehr ... | |
int | SetName (const char *name) |
Name. Mehr ... | |
int | SetVersion (int main=0, int sub=0) |
Version setzen. Mehr ... | |
Öffentliche Attribute | |
CMutex | Mutex |
Private Methoden | |
int | SetParam (const char *chunkname, const char *data) |
Interne Funktion zum Speichern von vordefinierten Chunks. Mehr ... | |
Private Attribute | |
CList | Chunks |
Verwaltung aller Chunks in einer Liste. Mehr ... | |
CCompression::Algorithm | comp |
Kompressions-Flag. Mehr ... | |
CString | findchunk |
Chunkname für FindFirstChunk und FindNextChunk. Mehr ... | |
char | id [5] |
enthält die ID des Chunks. Die ID ist immer 4 Byte lang, gefolgt von einem 0-Byte Mehr ... | |
ppluint8 | mainversion |
Hier wird die Hauptversion des Files gespeichert. Mehr ... | |
ppluint8 | subversion |
Hier wird die Unterversion des Files gespeichert. Mehr ... | |
Mit dieser Klasse können Dateien mit "PFP-File"-Header der Version 3 gelesen und geschrieben werden. Mit Version 3 wurde ein mehr generisches Format definiert, als in den beiden Vorgängerversionen. Jedes File, ganz gleich welchen Inhalt es hat, hat bis zum Ende den gleichen Aufbau. Wichtigste Neuerung dabei sind die sogenannten Chunks. Ein File kann aus bliebig vielen Chunks bestehen. Diese werden von der Klasse PFPChunk abgeleitet, bekommen einen Namen und einen beliebigen Inhalt. Diese können dann mit PFPFile::Add in das File hinzugefügt werden.
Ein PFP-File in der Version 3 ist in mehrere aufeinanderfolgende Abschnitte aufgeteilt:
Alle 4-Byte Größenangaben sind im LittleEndian-Format!
Der Header einer Version 3 Datei sieht so aus:
Im Anschluss an den Header folgen die Nutzdaten. Sofern keine Komprimierung verwendet wurde, geht es sofort mit dem ersten Chunk los. Ist die Datei komprimiert folgt erst der Komprimierungsheader:
In einem PFP-File können beliebig viele Chunks vorkommen. Ein Chunk besteht immer aus einem 4-Byte langen Namen, gefolgt von einem 4-Byte Integer, der die Größe des Chunks einschließlich des Headers angibt, gefolgt von den Nutzdaten. Abgesehen von den unten aufgeführten vordefinierten Chunks, können beliebig viele Chunks mit gleichem Namen vorhanden sein.
Ein Chunk muss nicht zwingend Nutzdaten enthalten.
Die nachfolgenden Chunks sind vordefiniert, aber optional
Author
Der Name des Authors kann mit der Funktion PFPFile::SetAuthor gesetzt werden.
Name
Der Name des Files kann mit der Funktion PFPFile::SetName gesetzt werden.
Description
Die Description kann mit der Funktion PFPFile::SetDescription gesetzt werden.
Copyright
Der Copyright-String kann mit der Funktion PFPFile::SetCopyright gesetzt werden.
Dieser Chunk ist immer der letzte in der Datei und kennzeichnet das Ende der Nutzdaten.
ppl6::PFPFile::PFPFile | ( | ) |
Hier werden einige interne Variablen initialisert, die ID wird auf "UNKN" gesetzt, Version auf 0 und Kompression abgeschaltet
|
virtual |
Der Destruktor sorgt dafür, dass sämtlicher von der Klasse allokierter Speicher einschließlich aller geladener Chunks freigegeben wird.
int ppl6::PFPFile::AddChunk | ( | PFPChunk * | chunk | ) |
Mit dieser Funktion wird ein neuer Chunk in die Klasse hinzugefügt. Der Chunk muss von der Anwendung mit "new" erstellt worden sein, einen Namen haben. Ist dies nicht der Fall, gibt die Funktion eine Fehlermeldung zurück.
Sobald der Chunk mit AddChunk an die PFPFile-Klasse übergeben wurde, wird er von der Klasse verwaltet und gegebenenfalls auch gelöscht. Die Anwendung braucht kein "delete" darauf zu machen.
chunk | Pointer auf den hinzuzufügenden Chunk |
void ppl6::PFPFile::Clear | ( | ) |
Mit dieser Funktion werden alle Chunks im Speicher freigegeben und die Klasse auf den Ursprungszustand zurückgesetzt, das heisst sie ist anschließend leer
int ppl6::PFPFile::DeleteChunk | ( | PFPChunk * | chunk | ) |
Mit dieser Funktion wird ein bestimmter Chunk aus der Klasse gelöscht.
chunk | Pointer auf den zu löschenden Chunk |
int ppl6::PFPFile::DeleteChunk | ( | const char * | chunkname | ) |
Mit dieser Funktion werden alle Chunks gelöscht, die den angegebenen Namen haben
chunkname | Pointer auf den Namen des Chunks |
PFPChunk * ppl6::PFPFile::FindFirstChunk | ( | const char * | chunkname | ) |
Mit dieser und der Funktion PFPFile::FindNextChunk kann man sich durch alle Chunks mit einem bestimmten Namen durchhangeln.
chunkname | Pointer auf den Namen des Chunks |
PFPChunk * ppl6::PFPFile::FindNextChunk | ( | const char * | chunkname = NULL | ) |
Mit dieser und der Funktion PFPFile::FindFirstChunk kann man sich durch alle Chunks mit einem bestimmten Namen durchhangeln.
chunkname | Optionaler Pointer auf den Namen des Chunks. Wurde zuvor bereits PFPFile::GetFirstChunk aufgerufen, muss kein Name angegeben werden. |
const char * ppl6::PFPFile::GetAuthor | ( | ) |
Diese Funktion liefert einen Pointer auf den Author zurück
CCompression::Algorithm ppl6::PFPFile::GetCompression | ( | ) |
Mit dieser Funktion wird das eingestellte Kompressionsverfahren ausgelesen.
const char * ppl6::PFPFile::GetCopyright | ( | ) |
Diese Funktion liefert einen Pointer auf den Copyright-Text des Files zurück.
const char * ppl6::PFPFile::GetDescription | ( | ) |
Diese Funktion liefert einen Pointer auf die Beschreibung zurück.
PFPChunk * ppl6::PFPFile::GetFirst | ( | ) |
Diese Funktion liefert einen Pointer auf den ersten Chunk in der Datei zurück.
const char * ppl6::PFPFile::GetID | ( | ) |
Diese Funktion liefert einen Pointer auf die ID der Datei zurück
int ppl6::PFPFile::GetMainVersion | ( | ) |
Mit dieser Funktion wird die Hauptversion der Datei ausgelesen.
const char * ppl6::PFPFile::GetName | ( | ) |
Diese Funktion liefert einen Pointer auf den Namen des Files zurück.
PFPChunk * ppl6::PFPFile::GetNext | ( | ) |
Diese Funktion liefert einen Pointer auf den nächsten Chunk in der Datei zurück.
int ppl6::PFPFile::GetSubVersion | ( | ) |
Mit dieser Funktion wird die Unterversion der Datei ausgelesen.
void ppl6::PFPFile::GetVersion | ( | int * | main, |
int * | sub | ||
) |
Mit dieser Funktion wird die Version der Datei in die beiden Parameter kopiert
[out] | main | Pointer auf eine Integer-Variable, in der die Hauptversion geschrieben werden soll |
[out] | sub | Pointer auf eine Integer-Variable, in der die Unterversion geschrieben werden soll |
bool ppl6::PFPFile::Ident | ( | CFileObject & | ff | ) |
ff
um eine Datei im Format PFP-Files Version 3 PFP-Format Version 3 handelt. Ist dies der Fall, wird deren ID und Version eingelesen.ff | Referenz auf eine geöffnete Datei |
true
zurück, wenn es sich um eine Datei im PFP-Format handelt. Deren ID kann anschließend mit PFPFile::GetID ausgelesen werden, Version mit PFPFile::GetVersion bzw. PFPFile::GetMainVersion und PFPFile::GetSubVersion. Handelt es sich nicht um eine Datei im PFP-Format, gibt die Funktion false
zurück. Es wird keine Exception geworfen. bool ppl6::PFPFile::Ident | ( | const CString & | file | ) |
file
um eine Datei im Format PFP-Files Version 3 PFP-Format Version 3 handelt. Ist dies der Fall, wird deren ID und Version eingelesen.file | Dateiname |
true
zurück, wenn es sich um eine Datei im PFP-Format handelt. Deren ID kann anschließend mit PFPFile::GetID ausgelesen werden, Version mit PFPFile::GetVersion bzw. PFPFile::GetMainVersion und PFPFile::GetSubVersion. Handelt es sich nicht um eine Datei im PFP-Format, gibt die Funktion false
zurück. Es wird keine Exception geworfen.
|
virtual |
Diese Funktion listet die Namen und Größen aller Chunks auf STDOUT aus.
int ppl6::PFPFile::Load | ( | CFileObject * | ff | ) |
Mit dieser Funktion wird ein PFP-File in die Klasse geladen. Dabei wird zuerst der Header geladen und überprüft, ob es sich um ein gültiges PFP-File handelt. Dann wird die virtuelle Funktion PFPFile::LoadRequest mit ID, Haupt- und Unterversion als Parameter aufgerufen. Liefert diese nicht true (1) zurück, wird der Ladevorgang abgebrochen. Andernfalls wird fortgeführt und geprüft, ob der Datenbereich komprimiert ist und gegebenenfalls dekomprimiert. Erst danach werden die einzelnen Chunks eingelesen. Kommt es dabei zu Fehlern durch ungültige Chunks, werden diese ignoriert und die Funktion gibt den Fehlercode 434 zurück.
ff | Pointer auf eine CFile-Klasse, mit der die einzulesende Datei geöffnet wurde. |
int ppl6::PFPFile::Load | ( | const char * | file | ) |
Mit dieser Funktion wird ein PFP-File in die Klasse geladen. Dabei wird zuerst der Header geladen und überprüft, ob es sich um ein gültiges PFP-File handelt. Anschließend wird geprüft, ob der Datenbereich komprimiert ist und gegebenenfalls dekomprimiert. Erst danach werden die einzelnen Chunks eingelesen. Kommt es dabei zu Fehlern durch ungültige Chunks, werden diese ignoriert und die Funktion gibt den Fehlercode 434 zurück.
file | Pointer auf den Namen der Datei, die geladen werden soll. |
|
virtual |
Diese Funktion wird bei jedem Ladevorgang aufgerufen. Falls die Anwendung eine Klasse definiert hat, die von PFPFile abgeleitet ist, kann sie an dieser Stelle den Ladevorgang abbrechen, wenn die Datei nicht dem unterstützten Format entspricht.
id | Pointer auf die 4-Byte-ID des PFP-Files |
mainversion | Die Hauptversion der Datei |
subversion | Die Unterversion der Datei |
void ppl6::PFPFile::Reset | ( | ) |
Mit dieser Funktion wird der Zeiger, der beim Durchwandern der Chunks mit den Funktionen FindNextChunk und GetNext verwendet wird, wieder auf den Anfang gesetzt.
int ppl6::PFPFile::Save | ( | const char * | filename | ) |
Mit dieser Funktion wird der Inhalt der PFPFile-Klasse in eine Datei geschrieben. Dabei wird der Header und sämtliche Chunks zusammengefasst, gegebenenfalls komprimiert (siehe PFPFile::SetCompression) und im Filesystem gespeichert. Der genaue Aufbau der Datei wird weiter unten beschrieben.
filename | Die Funktion bekommt als einzigen Parameter einen Pointer auf den Dateinamen. Es ist zu beachten, dass eine eventuell vorhandene gleichnamige Datei überschrieben wird. |
Ein PFP-File in der Version 3 ist in mehrere aufeinanderfolgende Abschnitte aufgeteilt:
Alle 4-Byte Größenangaben sind im LittleEndian-Format!
Der Header einer Version 3 Datei sieht so aus:
Im Anschluss an den Header folgen die Nutzdaten. Sofern keine Komprimierung verwendet wurde, geht es sofort mit dem ersten Chunk los. Ist die Datei komprimiert folgt erst der Komprimierungsheader:
In einem PFP-File können beliebig viele Chunks vorkommen. Ein Chunk besteht immer aus einem 4-Byte langen Namen, gefolgt von einem 4-Byte Integer, der die Größe des Chunks einschließlich des Headers angibt, gefolgt von den Nutzdaten. Abgesehen von den unten aufgeführten vordefinierten Chunks, können beliebig viele Chunks mit gleichem Namen vorhanden sein.
Ein Chunk muss nicht zwingend Nutzdaten enthalten.
Die nachfolgenden Chunks sind vordefiniert, aber optional
Author
Der Name des Authors kann mit der Funktion PFPFile::SetAuthor gesetzt werden.
Name
Der Name des Files kann mit der Funktion PFPFile::SetName gesetzt werden.
Description
Die Description kann mit der Funktion PFPFile::SetDescription gesetzt werden.
Copyright
Der Copyright-String kann mit der Funktion PFPFile::SetCopyright gesetzt werden.
Dieser Chunk ist immer der letzte in der Datei und kennzeichnet das Ende der Nutzdaten.
int ppl6::PFPFile::SetAuthor | ( | const char * | author | ) |
Mit dieser Funktion wird automatisch ein Author-Chunk ("AUTH") angelegt. Dabei ist sichergestellt, dass der Chunk nur ein einziges mal in der Datei vorkommt.
author | Pointer auf einen Null-terminierten String mit dem Namen des Authors |
int ppl6::PFPFile::SetCompression | ( | CCompression::Algorithm | type | ) |
Mit dieser Funktion wird festgelegt ob und welche Kompression beim Speichern verwendet werden soll.
type | Ein Wert, der die Art der Kompression angibt. Mögliche Werte sind:
|
int ppl6::PFPFile::SetCopyright | ( | const char * | copy | ) |
Mit dieser Funktion wird automatisch ein Copyright-Chunk ("COPY") angelegt. Dabei ist sichergestellt, dass der Chunk nur ein einziges mal in der Datei vorkommt.
copy | Pointer auf einen Null-terminierten String mit dem Copyright-Text |
int ppl6::PFPFile::SetDescription | ( | const char * | descr | ) |
Mit dieser Funktion wird automatisch ein Description-Chunk ("DESC") angelegt. Dabei ist sichergestellt, dass der Chunk nur ein einziges mal in der Datei vorkommt.
descr | Pointer auf einen Null-terminierten String mit der Beschreibung |
int ppl6::PFPFile::SetId | ( | const char * | id | ) |
Mit dieser Version wird die ID des PFP-Files festgelegt. Eine ID muss zwingend 4 Byte lang sein und darf nur US-ASCII-Zeichen enthalten.
id | Pointer auf einen 4-Byte langen String, der mit 0 terminiert ist. |
int ppl6::PFPFile::SetName | ( | const char * | name | ) |
Mit dieser Funktion wird automatisch ein Namens-Chunk ("NAME") angelegt. Dabei ist sichergestellt, dass der Chunk nur ein einziges mal in der Datei vorkommt.
name | Pointer auf einen Null-terminierten String mit dem Namen des Files |
|
private |
Diese Funktion wird intern verwendet, um die vordefinierten Text-Chunks zu speichern. Sie stellt sicher, dass jeder Chunk nur einmal vorkommt.
chunkname | Pointer auf den Namen des Chunks. |
data | Pointer auf den zu setzenden Text-String |
int ppl6::PFPFile::SetVersion | ( | int | main = 0 , |
int | sub = 0 |
||
) |
Mit dieser Funktion wird die Version des PFP-Files gesetzt
main | Hauptversion |
sub | Unterversion |
|
private |
|
private |
In dieser Variable wird die Art der Komprimierung gespeichert:
|
private |
|
private |
|
private |
CMutex ppl6::PFPFile::Mutex |
|
private |