TABLE OF CONTENTS xpkmaster.library/--general-- xpkmaster.library/XpkAllocObject xpkmaster.library/XpkClose xpkmaster.library/XpkExamine xpkmaster.library/XpkFault xpkmaster.library/XpkFreeObject xpkmaster.library/XpkOpen xpkmaster.library/XpkPack xpkmaster.library/XpkPassRequest xpkmaster.library/XpkPrintFault xpkmaster.library/XpkQuery xpkmaster.library/XpkRead xpkmaster.library/XpkSeek xpkmaster.library/XpkUnpack xpkmaster.library/XpkWrite xpkmaster.library/--tags-- xpkmaster.library/--progress-- xpkmaster.library/--data hooks-- xpkmaster.library/--general-- xpkmaster.library/--general-- xpkmaster.library is designed to work under minimum systems. So you may use it in games with disabled multitasking as well. It needs access to system libraries: utilities.library, exec.library, gadtools.library, intuition.library and dos.library. XPK supports locale.library to localize internal strings. When locale.library is installed, the first access to this library causes an access to ENV: assign, so this assign must exist when locale.library is installed. xpkmaster.library/XpkAllocObject xpkmaster.library/XpkAllocObject NAME XpkAllocObject - Allocate memory for xpk related structures (V4) SYNOPSIS ptr = XpkAllocObject(type, tags) D0 D0 A0 APTR XpkAllocObject(ULONG , struct TagItem *) ptr = XpkAllocObjectTags(type, firsttag, ...) APTR XpkAllocObjectTags(ULONG, Tag, ...) FUNCTION This function allocates the memory of a needed xpk related structure and initializes it. It should help to bring better upwards compatibility in next versions. Use it always in newer code. INPUT type - in xpk/xpk.h defined XPKOBJ_... types. for example XPKOBJ_FIB alloctes XpkFib structure tags - Pointer to an array of struct TagItem. No tags defined at the moment. RESULT ptr - Pointer to allocated memory of needed size or 0 when an error occured. SEE ALSO xpk/xpk.h, XpkFreeObject() xpkmaster.library/XpkClose xpkmaster.library/XpkClose NAME XpkClose - Close an XPK-File SYNOPSIS err = XpkClose(fib) D0 A0 LONG XpkClose(struct XpkFib *) FUNCTION Frees all resources associated with packing or unpacking an XPK-File. Note that this may well fail, especially on packing, since additional writes have to be made here. INPUT fib - The Struct XpkFib obtained from XpkOpen() RESULT err - Global Xpk error code SEE ALSO XpkOpen(), XpkRead(), XpkWrite() xpkmaster.library/XpkExamine xpkmaster.library/XpkExamine NAME XpkExamine - Get information about a compressed file SYNOPSIS err = XpkExamine(fib, tags) D0 A0 A1 LONG XpkExamine(struct XpkFib *, struct TagItem *) err = XpkExamineTags(fib, firsttag, ...) LONG XpkExamineTags(struct XpkFib *, Tag, ...) FUNCTION Returns information about compressed data. The output is written to the XpkFib structure whose address is passed with the mandatory XPK_FileExamine tag. You also have to specify an XPK_In* tag. Note that the file position of the in hook will not be altered. XPK_GetError is supported. A tag field has to end with TAG_DONE. INPUT tags - Pointer to an array of struct TagItem. You may use either a XPK_InBuf, a XPK_InName, XPK_InFH or XPK_InHook tag. RESULT err - Global Xpk error code SEE ALSO xpk/xpk.h xpkmaster.library/XpkFault xpkmaster.library/XpkFault NAME XpkFault - Returns the text associated with a Xpk error code (V4) SYNOPSIS len = XpkFault(code, header, buffer, bufsize) D0 D0 A0 A1 D1 LONG XpkFault(LONG, STRPTR, STRPTR, LONG) FUNCTION This routine obtains the error message text for the given error code. The header is prepended to the text of the error message, followed by a colon. Puts a null-terminated string for the error message into the buffer. At most len bytes are written to buffer. INPUTS code - Error code (negative value or 0) header - header to output before error text buffer - Buffer to receive error message. bufsize - Length of the buffer. RESULT len - number of characters put into buffer (may be 0) SEE ALSO XpkPrintFault() xpkmaster.library/XpkFreeObject xpkmaster.library/XpkFreeObject NAME XpkFreeObject - Frees memory allocated with XpkAllocObject() (V4) SYNOPSIS XpkFreeObject(type, object) D0 A0 void XpkFreeObject(ULONG , APTR) FUNCTION Frees object allocated by XpkAllocObject(). Do not call for objects allocated in any other way. INPUTS type - type passed to XpkAllocObject() object - pointer returned by XpkAllocObject() SEE ALSO xpk/xpk.h, XpkAllocObject() xpkmaster.library/XpkOpen xpkmaster.library/XpkOpen NAME XpkOpen - Open a compressed file for partial reading SYNOPSIS err = XpkOpen(fib, tags) D0 A0 A1 LONG XpkOpen(struct XpkFib **, struct TagItem *) FUNCTION Using XpkOpen you can read or write an XPK file without ever having all of the file present in RAM. On reading, you cannot pick the size of the chunks. They are given by the file to be decompressed and may be up to the whole size of the file. XPK_GetError is supported. You must supply XPK_NeedSeek, when you wnat to seek in the xpk file. INPUT fib - Address of a pointer to struct XpkFib tags - Specifying XPK_PackMethod will chose packing mode for this filehandle. Only In-tags are permitted in case of unpacking, and only Out-tags are in case of packing. Anything else will yield undefined results. Progress reports not supported. When packing, you must supply XPK_InLen as well. RESULT fib - The filehandle. Consists of an XpkFib and some private information. The NLen field in the XpkFib indicates the length of the next chunk. err - Global Xpk error code. If nonzero, no XpkFib was allocated. SEE ALSO XpkRead(), XpkWrite(), XpkClose(), xpkmaster.library/--tags-- xpkmaster.library/XpkPack xpkmaster.library/XpkPack NAME XpkPack - Compress a data stream SYNOPSIS err = XpkPack(tags) D0 A0 LONG XpkPack(struct TagItem *) err = XpkPackTags(firsttag, ...) LONG XpkPackTags(Tag, ...) FUNCTION Compresses a file or a memory area to a different file or memory area. You need to specify at least one XPK_In... tag, at least one XPK_Out... tag, plus XPK_PackMethod. XPK_GetError is supported. A tag field has to end with TAG_DONE. INPUT tags - Pointer to an array of struct TagItem. RESULT err - Global Xpk error code. SEE ALSO xpkmaster.library/--tags--, xpk/xpk.h xpkmaster.library/XpkPassRequest xpkmaster.library/XpkPassRequest NAME XpkPassRequest - opens a password Requester (V4) SYNOPSIS err = XpkPassRequest(tags) D0 A0 LONG XpkPassRequest(struct TagItem *) err = XpkPassRequestTags(firsttag, ...) LONG XpkPassRequestTags(Tag, ...) FUNCTION Opens a requester to ask the user for a password. The requester can ask for a password or a 16/32 bit key. It has a tunable timeout to allow batch work. This function needs at least 2 free signal bits for message ports. INPUT tags - Pointer to an array of struct TagItem. Either XPK_Preferences or one of the following: TAGS XPK_PassChars (ULONG) Tell the requester which characters are allowed in the password. Use XPKPASSFLG_... and XPKPASSFF_... defines. XPK_PasswordBuf (STRPTR) Pointer to memory area, where the password should be stored. Requires XPK_PassBuffSize tag. XPK_PassBufSize (ULONG) Size of the buffer passed with XPK_PasswordBuf. XPK_Key16BitPtr (UWORD *) Ask for an 16 bit key instead of a password. Data is a pointer to a 16 bit (UWORD) variable. XPK_PassChars is ignored here, as input is always hexadecimal. XPK_Key32BitPtr (ULONG *) Ask for an 32 bit key. Data points to a 32 bit (ULONG) variable. XPK_PassChars is ignored here, as input is always hexadecimal. XPK_PubScreen (struct Screen *) Pointer of type struct Screen of the public screen, the requester should open on. If not given, the requester opens on default public screen. The screen must by locked by use of LockPubScreen or garanted not to be closed during request! XPK_PassTitle (STRPTR) Is the text, which is shown in the title line of the window. If not given, the internal defaults are used. XPK_TimeOut (ULONG) Time after which the requester should close automatically, when no user action happend. 0 means no timeout. XPK_PassVerify (BOOL) (V4 REV25) When this tag is specified, the user needs to enter the password or passkey twice for verification. This option should be used when password is needed for packing. XPK_PassWinLeft (UWORD) (V4 REV25) This specifies the distance from left screen border to left border of password requester. When not given, the window is centered on screen. XPK_PassWinTop (UWORD) (V4 REV25) This specifies the distance from top screen border to top border of password requester. When not given, the window is centered on screen. XPK_PassWinWidth (UWORD) (V4 REV25) This specifies the width of the password requester. It must be large enough (50 + borders) or the internal defaults are used. XPK_PassWinHeight (UWORD) (V4 REV25) This specifies the height of the password requester. It must be large enough (inner height a bit larger than font height) or the internal defaults are used. XPK_PassCenter (BOOL) (V4 REV25) When this is given, the above XPK_PassWinLeft and XPK_PassWinTop are are interpreted as the center of the requester and not as its upper left edge. RESULT err - Global Xpk error code. SEE ALSO xpk/xpk.h xpkmaster.library/XpkPrintFault xpkmaster.library/XpkPrintFault NAME XpkPrintFault - Prints the text associated with a Xpk error code (V4) SYNOPSIS success = XpkPrintFault(code, header) D0 D0 A0 BOOL XpkPrintFault(LONG, STRPTR) FUNCTION This routine obtains and prints the error message text for the given error code. This is similar to the XpkFault() function, except that the output is written to the default output channel with buffered output. INPUTS code - Error code (negative value or 0) header - header to output before error text RESULT success - Success/failure code. Return of 0 means failure. SEE ALSO XpkFault() xpkmaster.library/XpkQuery xpkmaster.library/XpkQuery NAME XpkQuery - Gain information about packers SYNOPSIS err = XpkQuery(tags) D0 A0 LONG XpkQuery(struct TagItem *) err = XpkQueryTags(firsttag, ...) LONG XpkQueryTags(Tag, ... ) FUNCTION Finds out a list of available packers or various parameters of a packer. When using the tag XPK_PackersQuery, you must supply a XpkPackerList structure and will receive a list of available packers. The second possibility, XPK_PackerQuery, expects a pointer to a XpkPackerInfo structure which will be filled in with information about a packer, and XPK_ModeQuery fills in a XpkMode structure with information about some mode (or the default mode) of a packer. XPK_PackMethod must be present when using the latter two queries, and XPK_PackMode can be for ModeQuery. XPK_GetError is supported. Every call only one query is allowed! The flag XPKIF_MODES does not mean, the library supports different mode settings (as ALL libraries do that), but means there are different XpkMode structures! So when XPKIF_MODES is not set, the user still needs to be able to select all 100 modes! Pass {XPK_Preferences, FALSE} as tags to disable the dummy packer USER, which implements the preferences packing. Then handle the preferences mode internally, as the statistics passed with XPK_ModeQuery and XPK_PackerQuery are not very useful. RESULT err - Global Xpk error code. SEE ALSO xpk/xpk.h xpkmaster.library/XpkRead xpkmaster.library/XpkRead NAME XpkRead - Unpack one part of an XPK-File SYNOPSIS read = XpkRead(fib, buf, len ) D0 A0 A1 D0 LONG XpkRead(struct XpkFib *, UBYTE *, LONG) FUNCTION Reads one chunk from an XPK-file and decompresses it to the memory area indicated. INPUT fib - The XpkFib obtained from XpkOpen(). It must be a read- handle, ie. there was no XPK_PackMethod tag among the tags passed to XpkOpen(). buf - The memory area to write the destination to len - The number uncompressed bytes to output. Note that you cannot choose these freely but must take them from the xf_NLen field in the XpkFib. RESULT read - The number of bytes read. 0 indicates EOF, negative numbers are global error codes. Long error messages written to buffer passed through XPK_GetError in XpkOpen(). This number of bytes read will usually be smaller than the number requested! SEE ALSO XpkOpen(), XpkWrite(), XpkClose(), examples/ xpkmaster.library/XpkSeek xpkmaster.library/XpkSeek NAME XpkSeek - Seek in an compressed file (V5) SYNOPSIS res = XpkSeek(fib, dist, mode) D0 A0 D0 D1 LONG XpkSeek(struct XpkFib *, LONG, LONG); FUNCTION This functions seeks in xpk compressed files! It can be used, when the file is manually handled using XpkOpen and XpkRead. You need to use XPK_NeedSeek flag on XpkOpen to turn seekability on. Like normal DOS function Seek(), you seek into an file by specifying an offset and the mode (BEGINNING, CURRENT, END). Unlike DOS Seek() function the result is not the file position, but an global error code and the file position DOES NOT MATCH the wanted position. The XpkSeek() function always seeks to the start of the chunk, which contains the wanted position! If the return value is positive, the offset from chunk start is returned. An example: There is an file with chunksize 512 bytes and you already read 2 chunks (xfib->xf_UCur is 1024). You call XpkSeek with XPKSEEK_CURRENT and +3: The seek is done with 0 bytes, as you are already at that position, but return value is 3. XPKSEEK_CURRENT and -3 brings you to the chunk before (xfib->xf_UCur is 512) and return value is 509. Note that the chunks need not to have equal length! A call to XpkSeek corrects the entries in XpkFib. The Seek function works for unpacked and xpk packed input streams. XFD crunched data is not supported (as this is really useless). As The XPKIF_NOSEEK flag is new for V5, not all libraries may have it and thus there may be libraries not supporting seeking without that flag. INPUT fib - The XpkFib obtained from XpkOpen(). It must be a read- handle, ie. there was no XPK_PackMethod tag among the tags passed to XpkOpen(). dist - The positive a negative distance to seek in uncompressed data stream. mode - Either XPKSEEK_BEGINNING, when dist is an offset from file start, XPKSEEK_END, when dist is an offset from file end or XPKSEEK_CURRENT, when dist is an offset to current pos. RESULT res - Global XPK error code (<0) or seek offset addition SEE ALSO XpkOpen(), XpkRead(), xpkmaster.library/--tags--, xpk/xpk.h xpkmaster.library/XpkUnpack xpkmaster.library/XpkUnpack NAME XpkUnpack - Decompress a data stream SYNOPSIS err = XpkUnpack(tags) D0 A0 LONG XpkUnpack(struct TagItem *) err = XpkUnpackTags(firsttag, ...) LONG XpkUnpackTags(Tag, ...) FUNCTION Decompresses a file or a memory area to a different file or memory area. You need to specify at least one XPK_In... tag, at least one XPK_Out... tag. A tag field has to end with TAG_DONE. XPK_GetError is supported. INPUT tags - Pointer to an array of struct TagItem. RESULT err - Global Xpk error code. SEE ALSO xpkmaster.library/--tags-- xpkmaster.library/XpkWrite xpkmaster.library/XpkWrite NAME XpkWrite - Pack one part of an XPK-File SYNOPSIS err = XpkWrite(fib, buf, len) D0 A0 A1 D0 LONG XpkWrite(struct XpkFib *, UBYTE *, LONG) FUNCTION Compresses the memory area indicated and writes it to an XPK-File. INPUT fib - The XpkFib obtained from XpkOpen(). Must be a write- handle, ie. XPK_PackMethod must have been among the tags passed to XpkOpen(). buf - The memory area to compress len - The number bytes to compress. Note you may not choose them freely, you must always deliver as many bytes as the NLen field of the XpkFib indicates. You may try to influence it by passing XPK_ChunkLen to XpkOpen(). Important: The first chunk written *must* be the biggest! RESULT err - global error codes. Error messages are written to buffer passed through XPK_GetError in XpkOpen(). SEE ALSO XpkOpen(), XpkRead(), XpkClose(), examples/ xpkmaster.library/--tags-- xpkmaster.library/--tags-- THE TAGS FOR XpkPack() AND XpkUnpack() THE INPUT TAGS. One of the four must be present. XPK_InName (STRPTR) Name of file to (de)compress. On packing, XPK_InLen can be specified in order to pack only the first N bytes. On de- compression, only one file will be decompressed, even if there is additional data at the end. XPK_InFH (BPTR) File handle to (de)compress from. It is not necessary that the handle is at the beginning of the file. Otherwise same rules as in XPK_InName apply. XPK_InBuf (APTR) Memory block to (de)compress. If you use this one, you have to specify InLen as well. XPK_InHook (struct Hook *) Hookfunc to deliver data for (de)compression. See special chapter on I/O hook functions. Must also supply XPK_InLen, else the hook itself is asked for input filelength. IN ADDITION XPK_InLen (LONG) Specifies the number of bytes to read when compressing. ignored on decompression of normal xpk files. It should be supplied for decompression to allow decrunching of non xpk files. THE OUTPUT TAGS. One of the five must be present. XPK_OutName (STRPTR) Name of file write (de)compressed data to. XPK_OutFH (BPTR) File handle to append (de)compressed data to. This filehandle must be writable, so MODE_OLDFILE filehandles may fail, as these open a file in shared mode. XPK_OutBuf (APTR) The memory block to write (de)compressed data to. Must also supply XPK_OutBufLen. On packing, its size must be at least inlen+inlen/32+2*XPK_MARGIN. On unpacking, it needs only be outlen+XPK_MARGIN. Use XpkExamine() to find out outlen. Note that this buffer must be word aligned. XPK_GetOutBuf (APTR *) Allocates a block of appropriate size and stores a pointer to it in the variable pointed to by ti_Data. Must also supply XPK_GetOutBufLen plus XPK_GetOutLen and can XPK_OutMemType. XPK_OutHook (struct Hook *) Hookfunc to accept (de)compressed data. See special chapter on I/O hook functions. IN ADDITION XPK_OutBufLen (LONG) The length of the output buffer you supply using XPK_OutBuf. For decompression, must be decompressed size (see XpkExamine()) plus XPK_MARGIN. For compression, inlen+inlen/32+2*XPK_MARGIN. XPK_GetOutLen (LONG *) Stores the total length of the (de)compressed data in the variable pointed to by ti_Data. XPK_GetOutBufLen (LONG *) Stores the length of the buffer allocated for the data in the variable pointed to by ti_Data. FreeMem() the buffer you get from XPK_GetOutBuf with the length you get from XPK_GetOutBufLen. Note: For the number of bytes written, refer to XPK_GetOutLen! XPK_OutMemType (LONG) The type of memory to use for the output buffer. You have to specify different input and output streams always. So it produces wrong results, when you supply same buffer for XPK_InBuf and XPK_OutBuf or same filehandle for XPK_InFH and XPK_OutFH. PACKING TAGS XPK_PackMethod (STRPTR) Use indicated method for packing. This would be a four letter string of uppercase characters and numbers. XPK_PackMode (LONG) Packing mode for sublib to use. Range is 0...100, where 100 is most efficient. XPK_StepDown (BOOL) Reduce packing efficiency to save mem if necessary. XPK_ChunkSize (LONG) Chunk size to try to pack with. May be altered by the master library. XPK_LossyOK (BOOL) Some packers, like MPEG, reduce the file size by deleting some information. These information cannot be restored. This tag tells xpkmaster.library if it is ok for you, that some information is deleted. It is FALSE by default. Use it with care! Should be used only with sound or picture files. QUERY TAGS XPK_PackersQuery (struct XpkPackerList *) Returns an array of available packers names in the XpkPackerList structure whose address is stored in the ti_Data field of this tag. XPK_PackerQuery (struct XpkPackerInfo *) Returns information about one single packer in the XpkPackerInfo structure whose address is stored in the ti_Data field of this tag. See xpk/xpk.h for the meaning of the fields therein. You must also supply XPK_PackMode. XPK_ModeQuery (struct XpkMode *) Returns information about one single packer mode in the XpkMode structure whose address is stored in the ti_Data field of this tag. See xpk/xpk.h for the meaning of the fields therein. The data of xm_Next field is illegal and must not be used. You must also supply XPK_PackMethod and optionally XPK_PackMode, otherwise the default mode will be used. OTHER TAGS XPK_GetError (STRPTR) Write error msg to the buffer passed. The buffer must be of size XPKERRMSGSIZE. This tag calls XpkFault internally. It is not recommended to use this tag any longer. XPK_Password (STRPTR) Use password for en- or decoding. Passing a NULL pointer or zero length string is equivalent to omitting this tag. XPK_Key16 (UWORD) (V4 REV25) Supply a 16 bit key for decrunching of encrypted data. This is only for decrunching of alien formats. XPK does not support crunching with keys. Only know usage: crypted RNC files. XPK_Key32 (ULONG) (V4 REV25) Supply a 32 bit key for decrunching of encrypted data. This is only for decrunching of alien formats. XPK does not support crunching with keys. Currently no know usage. XPK_ChunkHook (struct Hook *) Hook function to call between chunks. Can print a progress report, and if it returns a nonzero value, the (de)compression will be aborted. See special chapter on chunk functions. XPK_PassThru (BOOL) If true, data will just be handed trough on decompression if they were not packed. Otherwise you get XPKERR_NOTPACKED. XPK_TaskPri (UBYTE) The task priority to use during the (de)crunching. Use -1 for background decompression. XPK_FileName (STRPTR) The name to print in the progress report. If none is given, the InName will be used when packing and the OutName when unpacking. XPK_NeedSeek (BOOL) (V5) If true (in XpkOpen), the XpkSeek function can be used. PREFERENCES RELATED TAGS XPK_UseXfdMaster (BOOL) (V4) If TRUE, xfdmaster.library will be used for checking unknown files. Useable with XpkUnpack() and XpkExamine(). Is FALSE by default, but depends on preference settings. XPK_UseExternals (BOOL) (V4) If TRUE, xex libraries in LIBS:compressors/extern will be used to check for crunched files. Useable with XpkUnpack() and XpkExamine(). Default value is TRUE (depends on prefs!) XPK_PassRequest (BOOL) (V4) If this is set a requester will be used to query the user for a password, if none is given. Useable with XpkPack(). This is disabled by default, but can be overridden using preferences settings. XPK_Preferences (BOOL) (V4) Tell xpkmaster.library whether to use its preferences system, or not. This is enabled by default. XPK_ChunkReport (BOOL) (V4) If this tag is set, xpkmaster.library brings an automatic chunk report request (when the preferences semaphore has a valid function for that). This is disabled by default. xpkmaster.library/--progress-- xpkmaster.library/--progress-- THE PROGRESS REPORT HOOK The progress report function is a standard hook function that will be called after every chunk (de)compressed. This will be about every 30K, or just twice if the file format is not split in chunks. If the field h_Entry in the hook is set, it will be called with the hook itself in A0 and the progress report structure in A1. If the progress report function returns a nonzero value, (de)compression aborts. NOTE: Because hooks are not called in program environment, they cannot be used in small data model of some compilers, as register A4 is not passed through. So the hook either has to be compiled in large data model or should use __saveds keyword of some compilers. xpkmaster.library/--data hooks-- xpkmaster.library/--data hooks-- GENERAL You have four methods of passing data to xpkmaster.library: file- names, filehandles, memory areas and hooks. The hooks are described here. The hook field h_Entry has to be standard hook functions and gets called with the hook itself in A0 and a pointer to a XpkIOMsg in A1. Commands are stored in xiom_Type field, data in the other fields. Return values are 0 or any of the XPKERR codes. Commands XIO_FREE and XIO_ABORT may be ignored. Whenever an error occurs, you have to return an XPKERR code and stop work. You get a XIO_ABORT call in this case later. When no error occured, return 0. You may store private data in the free fields of XpkIOMsg structure. You are always called with XIO_FREE or XIO_ABORT, so you can free private stuff there. Buffers can be freed, when next time a buffer allocation is required. NOTE: Because hooks are not called in program environment, they cannot be used in small data model of some compilers, as register A4 is not passed through. So the hook either has to be compiled in large data model or should use __saveds keyword of some compilers. BUFFERS Your hooks must be able to allocate buffers for read/write or pass pointers to them, when they are already allocated. There are some ways you have to handle this. First there is XIO_GETBUF. When getting this command you have to pass a memory pointer pointing to a region of at least xmm_Size size. For in hook there is another additionally method. When XIO_READ is wanted and xiom_Ptr is zero, then you have to pass (and allocate) a buf pointer and to fill it! The buffers must be valid until you are next time asked to allocate a buffer (either with XIO_GETBUF or XIO_READ). Then you may return old buffer pointer (when memory is large enough) or allocate a new buffer and free the old buffer. When XIO_ABORT or XIO_FREE is send all your buffers should be freed. NOTE: Your hooks do not get called only with your own buffers, but also with xpkmaster internally buffers! When your input data is already in memory, you may pass pointers to your memory regions and need not to allocate new memory for XIO_READ when pointer is zero. When xiom_Ptr is not zero for XIO_READ, you have to copy the data. Never expect, that you are called next time with buffer you allocated. There may be write cycles of headers and other stuff between XIO_GETBUF and XIO_WRITE. On reading it is equal. COMMANDS XIO_READ (in hooks only) This command is called all time xpkmaster.library needs some data. You have to fill the supplied memory area with input data of needed size (not more!) When the input memory pointer is zero, you have to allocate your own buffer and fill it. When you allocated a buffer before (either by XIO_GETBUF or XIO_READ) you can free it when pointer is zero. Input: xiom_Size size of required data xiom_Ptr already allocated buffer or zero Output: xiom_Ptr pointer to memory area of xiom_Size XIO_WRITE (out hooks only) This function is called, when some data was compressed and should be stored now. Copy the contents of buffer to your data storing system. Input: xiom_Size size of data xiom_Ptr pointer to memory area of xiom_Size Output: none XIO_FREE (both) You get this when work is finished, free all your stuff now. Input: none Output: none XIO_ABORT (both) You get this when work was aborted, because an error occured. Free all your stuff now. Input: none Output: none XIO_GETBUF (both) Asks you to pass a needed buffer. This buffer is not freed by xpkmaster.library. Do this when getting XIO_FREE, XIO_ABORT or the next XIO_GETBUF. Input buffers may be freed too, when XIO_READ is called with no pointer. Input: xiom_Size size of necessary buffer Output: xiom_Ptr pointer to the buffer XIO_SEEK (both) Change the current position in your data (like dos.library Seek command). When you are not able to handle seek, all better functions will fail. Pass XPKERR_NOFUNC in this case as return value. The offset you have to seek is always relative to current position. It can be negative too. Return value (xiom_Size) is same as for dos.library Seek command. Input: xiom_Size offset you have to seek Output: xiom_Size buffer position before seek XIO_TOTSIZE (both) You either have to tell the total input data size (in hook) or get told the total output data size (out hook). OUT HOOK: XIO_TOTSIZE may be ignored here. It tells you the maximum size of output file (the real size may be shorter). This is for example needed in memory hooks. This is only to inform you. This command never needs to return an error code. Input: xiom_Size total size of output data Output: none IN HOOK: XIO_TOTSIZE cannot be ignored here. When your hook cannot determine the total filesize, return any of the XPKERR values. XIO_TOTSIZE is called only, when xpkmaster library really needs filesize. Normal XPK files have size information in header and XPK_InLen flags supplies information for input. In these cases XIO_TOTSIZE is not used. But when returning an XPKERR, your hook will not work in other cases, when size is required. XIO_TOSIZE is used for following cases (when no XPK_InLen is supplied!): - decrunching of all non-xpk files - crunching of files NOTE: Only the size of the part, which should be processed, is wanted. Most time this is from current position to end of file (memory), but it may be shorter. But generally you have to calculate size starting at current position. Input: none Output: xiom_Size total size of input data