home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Amiga Format CD 28
/
amigaformatcd28.iso
/
-seriously_amiga-
/
archivers
/
xpk
/
xpk_develop
/
autodocs
/
xpksub.doc
< prev
Wrap
Text File
|
1998-04-27
|
8KB
|
251 lines
TABLE OF CONTENTS
xpksub.library/XpksPackerInfo
xpksub.library/XpksPackChunk
xpksub.library/XpksPackFree
xpksub.library/XpksPackReset
xpksub.library/XpksUnpackChunk
xpksub.library/XpksUnpackFree
xpksub.library/--sublibs--
xpksub.library/XpksPackerInfo
NAME
XpksPackerInfo - Get information about a packer sub-library
SYNOPSIS
info = XpkPackerInfo()
D0
struct XpkInfo *XpkPackerInfo(void);
FUNCTION
Returns all information about a packer sub-library for use
by the master library.
RESULT
info - pointer to struct XpkPackerInfo. see xpk/xpksub.h
for the meaning of all the fields.
SEE ALSO
XpksPackChunk()
xpksub.library/XpksPackChunk
NAME
XpksPackChunk - Pack a chunk of data
SYNOPSIS
err = XpksPackChunk( param )
D0 A0
LONG XpksPackChunk(struct XpkSubParams *);
FUNCTION
Packs one chunk of data from memory to memory. The size of the
chunk will not surpass the MaxPkInChunk field of the packer info
structure. Chunks are numbered in case a library writes various
dictionaries at special places.
INPUTS
struct XpkSubParams, where the fields mean:
InBuf Pointer to the data to be compressed
InLen The number of bytes to pack
OutBuf Pointer to the memory area to write packed data to
OutBufLen Size of above memory area
OutLen Will be set to compressed length by sublib
Number The number of this chunk
Mode The sub-mode to be used
Password The password to be used for encryption
Sub[4] Here the sub library stores its private data
RESULTS
err - global xpk error code
OutLen - Number of bytes written
SEE ALSO
XpksPackReset(), XpksPackFree()
xpksub.library/XpksPackFree
NAME
XpksPackFree - Free buffers associated with packing process
SYNOPSIS
XpksPackFree( param )
A0
void XpksPackFree(struct XpkSubParams *)
FUNCTION
Frees all buffers the sub-library has allocated privately
while doing some packing
INPUTS
param - The XpkSubParams used for packing
SEE ALSO
XpksPackChunk(), XpksPackReset()
xpksub.library/XpksPackReset
NAME
XpksPackReset - Clears all state information
SYNOPSIS
XpksPackReset( param )
A0
LONG XpksPackReset(struct XpkSubParams *)
FUNCTION
Clears all internal tables and any other state information of the
packer. This has the effect, to guarantee independent unpacking
of the chunk to come. The packers call this function automatically
before returning XPKERR_EXPANSION (data could not be compressed).
Note: packers have to store all of their state relevant to packing
in XpkSubParams to ensure reentrantness.
INPUTS
param - The XpkSubParams used for packing
SEE ALSO
XpksPackChunk(), XpksPackFree()
xpksub.library/XpksUnpackChunk
NAME
XpksUnpackChunk - Uncompress a chunk of data
SYNOPSIS
err = XpksUnpackChunk( param )
A0
LONG XpksUnpackChunk(struct XpkSubParams *)
FUNCTION
Decompresses one chunk of data.
INPUTS
param - The XpkSubParams used for unpacking
xsp_InBuf Pointer to the data to be uncompressed
xsp_InLen The number of bytes to unpack
xsp_OutBuf Pointer to the memory area to write unpacked data to
xsp_OutBufLen Size of above memory area
xsp_OutLen Must contain the decompressed size of the data
xsp_Number The number of this chunk
xsp_Password The password to be used for decryption
xsp_Sub[4] Here the sub library stores its private data
RESULT
err - global xpk error code
SEE ALSO
XpksUnpackFree()
xpksub.library/XpksUnpackFree
NAME
XpksUnpackFree - Free all private data the sublib has allocated
SYNOPSIS
XpksUnpackFree( param )
A0
LONG XpksUnpackFree( struct XpkSubParams * )
FUNCTION
Will free all memory the sub-library has allocated during the
decompression.
INPUTS
param - The XpkSubParams used for unpacking
SEE ALSO
XpksUnpackChunk()
xpksub.library/--sublibs--
Some remarks for sublib writers
-------------------------------
First of all, Read the documentation. If you have got any further questions
writing xpksublibraries, either contact one of the XPK maintainers.
The name of a sub library is xpkXXXX.library, where XXXX is a combination
of uppercase characters ('A' to 'Z') and numbers ('0' - '9').
The first character must not be a 'X' (xpkXTRA.library is not allowed), as
this letter is reserved for xex libraries.
How XpkPackChunk works:
- Check xpar->xsp_Sub[0]. If it is 0, this is the first call. Allocate your
tables and store pointers to them in xsp_Sub[0] .. xsp_Sub[3].
- Read xpar->xsp_InLen bytes from xpar->xsp_InBuf and pack them to
xpar->xsp_OutBuf. Do not exceed xpar->xsp_OutBufLen. Store packed len in
xpar->xsp_OutLen.
How XpkUnpackChunk works:
- Check xpar->xsp_Sub[0]. If it is 0, this is the first call. Allocate your
tables and store pointers to them in xsp_Sub[0] .. xsp_Sub[3].
- Read xpar->xsp_InLen bytes from xpar->xsp_InBuf and unpack them to
xpar->xsp_OutBuf. Do noot exceed xpar->xsp_OutBufLen. Maybe compare
uncompressed len with xpar->xsp_OutLen.
Other notes:
- Your library should, of course, be re-entrant. This means no PC-relative
addressing of writeable data. Whatever you have, store a pointer to it
somewhere in the XpkSubMessage. In short: All state information of the
sublib is in the XpkSubMessage. You can detect the first chunk of a file
by the fact that this pointer is still NULL. In case your lib is not
re-entrant, return XPKERR_LIBINUSE when required.
- There will be no larger chunks on (de)compression than the first one.
- On compression, you may expand the data by XPK_MARGIN bytes maximum. This
means the output buffer is as large as the input buffer plus XPK_MARGIN.
Compression libs would, of course, already return XPKERR_EXPANSION if
they exceed the input buffer.
- You must supply a function XpkPackReset, which clears all tables so
that the next chunk will be able to be unpacked independently. You also
have to reinitialize all state information [calling your XpkPackReset]
before returning XPKERR_EXPANSION!
- On decompression, you will also have a XPK_MARGIN byte saftey margin for
runaway unpacking.
- Fill in one XpkInfo structure. See xpk/xpksub.h for the meanings of
the fields therein.
- If your packer has only one packing mode, fill in one XpkMode structure
(see xpk.h). Set the 'xm_Upto' field to 100, this means this struct
handles all modes up to (and including) 100, which is the max packing
mode. Place a pointer to this struct in the XpkInfo structure.
- There must be at least one XpkMode structure, and the last XpkMode
structure must have the xm_Upto set to 100. It must!
- If your packer has several modes, create several XpkMode structures and
sort them by efficiency in ascending order. Place a pointer to them
in XpkInfo. Set the XPKIF_MODES flag in the xi_Flags field of XpkInfo.
- Your packer will get the 0..100 number and is responsible of mapping
it to its own packing modes.
- Set the xi_DefMode field to some 0...100 number.
- If XSF_STEPDOWN is set in the xsp_Flags field of the SubParams structure,
you are allowed to reduce packing efficiency in order to save mem.
- Encryption libraries should compute a cryptographic hash [that is a
checksum] while or after decryption and compare it with one stored in the
encrypted data. If the hash of the decrypted text does not match the
stored checksum, return XPKERR_WRONGPW. Note, that this hash inevitably
discloses information applicable to breaking the code. Try to keep this
information small, e.g. by using a 16bit hash. Take care, that one has to
decrypt the whole chunk before it is possible to compute the hash of the
decrypted data.