diff --git a/docs/doc-pld.txt b/docs/doc-pld.txt new file mode 100644 index 0000000..0e53808 --- /dev/null +++ b/docs/doc-pld.txt @@ -0,0 +1,56 @@ + +devil1pld.h / devil1pld.c + Handles .pld files. + +File Format + PLDs are simple packages of different files, and do not contain a table + of contents. The header consists only of the number of files packaged + and the offsets from the beginning of the .pld that marks the starting + location of the file. + +Functions + All functions are static but exposed by a function pointer in a constant + struct called DEVIL1PLD. For example, clients call functions using + DEVIL1PLD.getheader(..., ...); + + bool getheader(struct PldHeader*, const char*); + Places file header into the struct pointed at by the first parameter + from the information given in by the second parameter. + + inputs: pointer to a struct, pointer to file data + Neither parameter should be NULL. + + output: true or false, whether or not operation succeeds or fails. + Will return false if one or both of the parameters are NULL + pointers. + Will return false if the attribute numOffset is less than 0- + i.e file is not valid. + + int sizeofsector(struct PldHeader*, unsigned int i, unsigned int max); + Returns the size of the i-th file packed in the pld. + + inputs: pointer to a struct, i-th element in pld, file size + + output: (-1), [0, maximum value of int) + -1 indicates an invalid input. + + void printheader(struct PldHeader*); + Shows contents of a PLD header in standard output. + + inputs: pointer of a struct + +Example logic to iterate through a .pld + { + ... + // Get information about the file + struct PldHeader h; + DEVIL1PLD.getheader(&h, data); + + unsigned int i; + for (i = 0; i < h.numOffset; i++) { + const char *currentfile = filedata + h.offset[i]; + ... + } + ... + + }