Adding upstream version 1.0.2.

Signed-off-by: Daniel Baumann <daniel@debian.org>

src/pplib/docs/formate/PFPVersion3.dox

@@ -0,0 +1,113 @@
+/*!
+\page PFPFileVersion3 Format PFP-Files Version 3
+
+Ein PFP-File in der Version 3 ist in mehrere aufeinanderfolgende Abschnitte aufgeteilt:
+- 24 Byte langer Header
+- optionaler 8-Byte langer Komprimierungsheader
+- Chunks
+
+Alle 4-Byte Größenangaben sind im LittleEndian-Format!
+
+\par Header
+
+Der Header einer Version 3 Datei sieht so aus:
+\code
+Byte  0: String "PFP-File"                             8 Bytes
+Byte  8: PFP-File-Version (3)                          1 Byte
+Byte  9: Länge des PFP-Header (24)                     1 Byte
+Byte 10: File-ID, 4 Byte-String                        4 Byte
+Byte 14: Unterversion                                  1 Byte
+Byte 15: Hauptversion                                  1 Byte
+Byte 16: Komprimierung                                 1 Byte
+         0=unkomprimiert
+         1=Zlib
+         2=Bzip2
+Byte 17: reserviert                                    3 Byte
+Byte 20: Timestamp der Erstellung (UTC)                4 Byte
+\endcode
+
+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:
+
+\par Komprimierungsheader
+
+\code
+Byte 0: Größe der Nutzdaten unkomprimiert in Byte      4 Byte
+Byte 4: Größe der Nutzdaten komprimiert in Byte        4 Byte
+\endcode
+
+\par Chunks
+
+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.
+
+\code
+Byte 0: Chunkname, 4 Byte-String in Grossbuchstaben    4 Byte
+Byte 4: Größe des Chunks einschließlich 8-Byte Header  4 Byte
+Byte 8: Nutzdaten des Chunks
+\endcode
+
+\par Vordefinierte Chunks
+
+Die nachfolgenden Chunks sind vordefiniert, aber optional
+<ul>
+<li>\b Author
+
+\code
+Byte 0: AUTH
+Byte 4: Länge des nachfolgenden Strings
+Byte 8: Name des Authors mit schließendem 0-Byte
+\endcode
+Der Name des Authors kann mit der Funktion PFPFile::SetAuthor gesetzt werden.
+</li>
+
+<li>\b Name
+
+\code
+Byte 0: NAME
+Byte 4: Länge des nachfolgenden Strings
+Byte 8: Name der Datei oder Beschreibung des Inhalts mit schließendem 0-Byte
+\endcode
+Der Name des Files kann mit der Funktion PFPFile::SetName gesetzt werden.
+</li>
+
+<li>\b Description
+
+\code
+Byte 0: DESC
+Byte 4: Länge des nachfolgenden Strings
+Byte 8: Nähere Beschreibung mit schließendem 0-Byte
+\endcode
+Die Description kann mit der Funktion PFPFile::SetDescription gesetzt werden.
+</li>
+
+<li>\b Copyright
+
+\code
+Byte 0: COPY
+Byte 4: Länge des nachfolgenden Strings
+Byte 8: Copyright-String mit schließendem 0-Byte
+\endcode
+Der Copyright-String kann mit der Funktion PFPFile::SetCopyright gesetzt werden.
+</li>
+</ul>
+
+\par End of File
+
+Dieser Chunk ist immer der letzte in der Datei und kennzeichnet das
+Ende der Nutzdaten.
+\code
+Byte 0: ENDF
+Byte 4: 0
+\endcode
+
+\par Nutzung
+Um das Lesen und Schreiben solcher Dateien zu vereinfachen, kann die Klasse PFPFile in
+Kombination mit PFPChunk verwendet werden.
+
+*/