ANews 1

home *** CD-ROM | disk | FTP | other *** search

/ ANews 1 / AnewsCD01.iso / Indispensables / Compression / xad / Developer / Include / Autodocs / xadmaster.doc next >

Wrap

Text File | 1999-08-09 | 36.0 KB | 1,026 lines

TABLE OF CONTENTS xadmaster.library/--general-- xadmaster.library/xadAllocObject xadmaster.library/xadAllocVec xadmaster.library/xadCalcCRC16 xadmaster.library/xadCalcCRC32 xadmaster.library/xadConvertDates xadmaster.library/xadCopyMem xadmaster.library/xadDiskUnArc xadmaster.library/xadFileUnArc xadmaster.library/xadFreeInfo xadmaster.library/xadFreeObject xadmaster.library/xadGetClientInfo xadmaster.library/xadGetErrorText xadmaster.library/xadGetInfo xadmaster.library/xadHookAccess xadmaster.library/xadRecogFile xadmaster.library/--tags-- xadmaster.library/--data hooks-- xadmaster.library/--progress hooks-- VERSION $VER: xadmaster.doc 2.0 (21.06.1999) by SDI xadmaster.library/--general-- xadmaster.library/--general-- This library gives you an interface to extract data from file or disk archives. When unachiving a archive you need to do following steps always 1) Allocate a "struct xadArchiveInfo" with a call to xadAllocObjectA(XADOBJ_ARCHIVEINFO, 0). This structure is the master interface and must not by modified in any way. Nearly all other functions you may use need to get the pointer this this structure. All data is passed with tags! 1) Call xadGetInfo() to find out if the input data is archived. If it is, the xadArchiveInfo structure is filled with lots of information (but the structure may contain empty lists!). See xadGetInfo() description to see what you may read and what stuff not. One of the input tags must be specified here to specify one of the allowed 4 input stream methods. 2) For every file in a file archive or every disk call xadFileUnArc() or xadDiskUnArc() with one tag XAD_ENTRYNUMBER set to wanted entry. One of the output tags must be specified here. For xadFileUnArc() there are 4 streams methods like for input. The xadDiskUnArc() function allows a fifth method called XAD_OUTDEVICE. This one writes directly to disks like all the disk archivers do. It allows 2 ways to specify the destination device. Passwords and other stuff is additionally allowed and sometimes required. 3) Call xadFreeInfo() to free the stuff allocated with xadGetInfo. 4) Use xadFreeObjectA() to free the xadArchiveInfo structure. Do not use one xadArchiveInfo file structure for multiple input files! ANY needed structure must be allocated with xadAllocObject! None of the xadmaster structures can be allocated any other way! There exist lots of tags, which can be passed to the functions of this library. Some of these are repeated in the xadArchiveInfo communication structure. Do NEVER set this flags or values directly, but always use the corresponding tags. The handling of these elements possibly will change, but the tags will stay valid always! I know there are lots of flags which have long and strange names. The method is not so complicated as you may think. The always follow following guideline: XADxxY_zzzzz xx - short name of their structure (AI - xadArchiveInfo, DI - xadDiskInfo, C - xadClient, ...) Y - F for flag or B for bit value zz - The flag name itself So XADPIF_OVERWRITE is a flag for xadProgressInfo, which is called OVERWRITE and XADAIB_OVERWRITE is a bit value for xadArchiveInfo structure. Also all the structure elements cover a short prefix indicating the name of the master structure (xfi for xadFileInfo, xc for xadClient, ...). So you can always check if your code is valid by comparing the prefixes. xadmaster.library/xadAllocObject xadmaster.library/xadAllocObject NAME xadAllocObject - Allocate memory for all xad related structures SYNOPSIS ptr = xadAllocObjectA(type, tags) D0 D0 A0 APTR xadAllocObjectA(ULONG, struct TagItem *) ptr = xadAllocObject(type, tag1, ...) APTR xadAllocObject(ULONG, Tag, ...) FUNCTION This function allocates the memory of a needed xad related structure and initializes it. You need to use this function to allocate the structures. Any other way of allocating is not allowed. INPUT type - in libraries/xadmaster.h defined XADOBJ_... types. For example XADOBJ_FILEINFO allocates xadFileInfo structure. tags - Pointer to an array of struct TagItem. Recognized tags: XAD_OBJNAMESIZE, XAD_OBJCOMMENTSIZE, XAD_OBJBLOCKENTRIES, XAD_OBJPRIVINFOSIZE RESULT ptr - Pointer to required structure or 0 when an error occured. SEE ALSO libraries/xadmaster.h, xadFreeObject(), tags section xadmaster.library/xadAllocVec xadmaster.library/xadAllocVec NAME xadAllocVec - Allocate memory for xad related stuff (V2) SYNOPSIS ptr = xadAllocVec(size, flags) D0 D0 D1 APTR xadAllocVec(ULONG, ULONG) FUNCTION This function allocates memory for a stuff related to xad. It is like exec.library AllocVec() function, but uses xadFreeObject() to free stuff and reduces the need for SysBase in clients. It's the prefered method to allocate memory in clients. INPUT size - The size in bytes. flags - Normal MEMF_... flags defined in exec/types.h RESULT ptr - Pointer to required memory or 0 when an error occured. SEE ALSO libraries/xadmaster.h, exec/types.h, exec.doc/AllocMem(), xadFreeObject(), xadmaster.library/xadCalcCRC16 xadmaster.library/xadCalcCRC16 NAME xadCalcCRC16 - calculate a 16 bit CRC SYNOPSIS crc16 = xadCalcCRC16(id, init, size, buffer) D0 D0 D1 D2 A0 UWORD xadCalcCRC16(UWORD, UWORD, ULONG, STRPTR) FUNCTION This function calculates a 16 bit CRC. It is possibly to choose the calculation method by parameter mode. The CRC calculation uses a table built with following function: void MakeCRC16(UWORD *buf, ULONG ID) { UWORD i, j, k; for(i = 0; i < 256; ++i) { k = i; for(j = 0; j < 8; ++j) { if(k & 1) k = (k >> 1) ^ ID; else k >>= 1; } buf[i] = k; } } The used calculation routine is like that: crc = init; while(size--) crc = tab[(crc ^ *buffer++) & 0xFF] ^ (crc >> 8); ID's defined in xadmaster.h use a default table. All others build the table on the fly. XADCRC16_ID1: (0xA001) - Used by DMS, Arc, ... INPUT id - The table creation ID (maybe XADCR16_ID value) init - The initial value for CRC calculation. size - The input buffer size. buffer - A pointer to the input buffer. RESULT crc16 - The calculated CRC value. SEE ALSO libraries/xadmaster.h, xadCalcCRC32 xadmaster.library/xadCalcCRC32 xadmaster.library/xadCalcCRC32 NAME xadCalcCRC32 - calculate a 32 bit CRC SYNOPSIS crc32 = xadCalcCRC32(id, init, size, buffer) D0 D0 D1 D2 A0 ULONG xadCalcCRC32(ULONG, ULONG, ULONG, STRPTR) FUNCTION This function calculates a 32 bit CRC. It is possibly to choose the calculation method by parameter mode. The CRC calculation uses a table built with following function: void MakeCRC32(ULONG *buf, ULONG ID) { ULONG i, j, k; for(i = 0; i < 256; ++i) { k = i; for(j = 0; j < 8; ++j) { if(k & 1) k = (k >> 1) ^ ID; else k >>= 1; } buf[i] = k; } } The used calculation routine is like that: crc = init; while(size--) crc = tab[(crc ^ *buffer++) & 0xFF] ^ (crc >> 8); ID's defined in xadmaster.h use a default table. All others build the table on the fly. XADCRC32_ID2: (0xEDB88320) - Used by Zoom, Zip, LZX, ... INPUT id - The table creation ID (maybe XADCR32_ID value) init - The initial value for CRC calculation. size - The input buffer size. buffer - A pointer to the input buffer. RESULT crc32 - The calculated CRC value. SEE ALSO libraries/xadmaster.h, xadCalcCRC16 xadmaster.library/xadConvertDates xadmaster.library/xadConvertDates NAME xadConvertDates - convert between date storage methods SYNOPSIS result = xadConvertDatesA(tags) D0 A0 LONG xadConvertDates(struct TagItem *) result = xadConvertDates(tag1, ...) LONG xadConvertDates(Tag, ...) FUNCTION This function can be used to transfrom date and time between different storage systems. One of the input tags must be specified. Output tags may be specified multiple. The date information is based on Gregorian calendar. Some systems can store a wider range of dates than others. If a date produces an overflow or an underflow for a special date, the highest/lowest valid date is used (e.g. for timevalues 0x00000000 or 0xFFFFFFFF). The XAD_MAKEGMTDATE and XAD_MAKELOCALDATE tags need locale.library to get the offset to local time. If locale.library cannot be opened the offset is set to 0. XAD_DATECURRENTTIME can be used to get the current system date and time. WeekDay information is ignored for input and always recalculated. The calculation routines use full range of available variable space, so f.e. a Unix date 1.1.1970 00:00:00 (value 0x00000000) with a UTC offset of -30 min produces 31.12.1968 23:30:00 (which cannot be stored as UNIX time value, but only as xadDate structure)!. INPUT ai - the master communication structure tags - Pointer to an array of struct TagItem. Recognized tags: XAD_DATEUNIX, XAD_DATEAMIGA, XAD_DATEDATESTAMP, XAD_DATEXADDATE, XAD_DATECLOCKDATA, XAD_DATECURRENTTIME, XAD_DATEMSDOS, XAD_GETDATEUNIX, XAD_GETDATEAMIGA, XAD_GETDATEDATESTAMP, XAD_GETDATEXADDATE, XAD_GETDATECLOCKDATA, XAD_GETDATEMSDOS, XAD_MAKEGMTDATA, XAD_MAKELOCALDATE RESULT result - any of the XADERR codes or zero when all is ok. SEE ALSO libraries/xadmaster.h, tags section xadmaster.library/xadCopyMem xadmaster.library/xadCopyMem NAME xadCopyMem - copies one data block to another position SYNOPSIS xadCopyMem(src, dest, size) A0 A1 D0 void xadCopyMem(APTR, APTR, ULONG) FUNCTION CopyMem is a general purpose memory copy function. It can deal with any length and its pointers on any alignment. It tries to optimize the copy operation, when alignment and size allow longword copies. Overlapping copies are supported in both directions. The internal implementation of this function will change from system to system and version to version. This copy function is not highly optimized, but should fit any needs around xadmaster.library! INPUT src - the source buffer dest - the destination buffer size - the size to copy RESULT none SEE ALSO libraries/xadmaster.h, exec.library/CopyMem() xadmaster.library/xadDiskUnArc xadmaster.library/xadDiskUnArc NAME xadDiskUnArc - the master function for unarchiving disks SYNOPSIS result = xadDiskUnArcA(ai, tags) D0 A0 A1 LONG xadDiskUnArc(struct xadArchiveInfo *, struct TagItem *) result = xadDiskUnArc(ai, tag1, ...) LONG xadDiskUnArc(struct xadArchiveInfo *, Tag, ...) FUNCTION This function dearchives a disk archive. It can be called after a succesful call to xadGetInfo. At least the tag XAD_ENTRYNUMBER and one of the output tags needs to be supplied. When a progress hook is supplied, this can be used for questioning for overwriting and ignoring of drive geometry and for status displays. Normally disk archivers will have only one entry, but there may be multiple disk archives. When this function returns, the supplied output data streams may be used in any way (files, memory). The library does not even know that they exist! The xadmaster.library cannot be used to rename, protect, comment or delete that stuff! INPUT ai - the master communication structure tags - Pointer to an array of struct TagItem. Recognized tags: XAD_ENTRYNUMBER, XAD_OUTFILEHANDLE, XAD_OUTFILENAME, XAD_OUTHOOK, XAD_OUTMEMORY, XAD_OUTSIZE, XAD_OVERWRITE, XAD_PROGRESSHOOK, XAD_IGNOREGEOMETRY, XAD_HIGHCYLINDER, XAD_LOWCYLINDER, XAD_OUTDEVICE, XAD_VERIFY, XAD_PASSWORD RESULT result - any of the XADERR codes or zero when all is ok. SEE ALSO libraries/xadmaster.h, xadFileUnArc(), xadGetInfo(), tags section xadmaster.library/xadFileUnArc xadmaster.library/xadFileUnArc NAME xadFileUnArc - the master function for unarchiving disks SYNOPSIS result = xadFileUnArcA(ai, tags) D0 A0 A1 LONG xadFileUnArc(struct xadArchiveInfo *, struct TagItem *) result = xadFileUnArc(ai, tag1, ...) LONG xadFileUnArc(struct xadArchiveInfo *, Tag, ...) FUNCTION This function dearchives a file archive entry. It can be called after a succesful call to xadGetInfo. At least the tag XAD_ENTRYNUMBER and one of the output tags needs to be supplied. When a progress hook is supplied, this can be used for questioning for overwriting and for status displays. This function needs to be called for every file, which should be unarchived. Best is to do unarchiving in direction giving by info structure, because some archivers crunch multiple files in one pass and the unarchiver needs to compress and buffer the whole pass to get one file. When this function returns, the supplied output data streams may be used in any way (files, memory). The library does not even know that they exist! The xadmaster.library cannot be used to rename, protect, comment or delete that stuff! INPUT ai - the master communication structure tags - Pointer to an array of struct TagItem. Recognized tags: XAD_ENTRYNUMBER, XAD_OUTFILEHANDLE, XAD_OUTFILENAME, XAD_OUTHOOK, XAD_OUTMEMORY, XAD_OUTSIZE, XAD_OVERWRITE, XAD_PROGRESSHOOK, XAD_PASSWORD RESULT result - any of the XADERR codes or zero when all is ok. SEE ALSO libraries/xadmaster.h, xadDiskUnArc(), xadGetInfo(), tags section xadmaster.library/xadFreeInfo xadmaster.library/xadFreeInfo NAME xadFreeInfo - free stuff built and allocated with xadGetInfo() SYNOPSIS xadFreeInfo(ai) A0 void xadFreeInfo(struct xadArchiveInfo *) FUNCTION Frees all the stuff built and allocated by a call to xadGetInfo(). You always need to call this after your work with a certain input file is finished. INPUTS ai - the master communication structure SEE ALSO libraries/xadmaster.h, xadGetInfo(), tags section xadmaster.library/xadFreeObject xadmaster.library/xadFreeObject NAME xadFreeObject - Frees structures allocated with xadAllocObject() or xadAllocVec() SYNOPSIS xadFreeObjectA(object, tags) A0 A1 void xadFreeObjectA(APTR, struct TagItem *) xadFreeObject(object, tag1, ...) void xadFreeObject(APTR, Tag, ...) FUNCTION Frees object allocated by xadAllocObject() or AllocVec(). Do not call for objects allocated in any other way. This function frees ALL memory which was allocated by xadAllocObject(), but only this memory. This means all name buffers and other related structures are freed, but if you replace pointers, your replacements get not freed. This function does not need the original pointers to be in the related positions, as the buffer size is stored elsewhere. INPUTS object - object allocated with xadAllocObject() or xadAllocVec() tags - Pointer to an array of struct TagItem. Recognized tags: currently none SEE ALSO libraries/xadmaster.h, xadAllocObject(), xadAllocVec(), tags section xadmaster.library/xadGetClientInfo xadmaster.library/xadGetClientInfo NAME xadGetClientInfo - Get list of active clients SYNOPSIS ptr = xadGetClientInfo() D0 struct xadClient *xadGetClientInfo(void) FUNCTION This function returns a list of all active clients. It can be used to show information about the library. The list is read only and cannot be modified! RESULT ptr - Pointer to first client in the list. SEE ALSO libraries/xadmaster.h xadmaster.library/xadGetErrorText xadmaster.library/xadGetErrorText NAME xadGetErrorText - Get error string from an error number SYNOPSIS ptr = xadGetErrorText(errnum) D0 D0 STRPTR xadGetErrorText(ULONG) FUNCTION This function returns the error string related to the supplied error number. This string is valid as long as xadmaster.library is opened, so when needed any longer time it must be copied. INPUT errnum - in libraries/xadmaster.h defined XADERR_... numbers. RESULT ptr - Pointer to required string. SEE ALSO libraries/xadmaster.h xadmaster.library/xadGetInfo xadmaster.library/xadGetInfo NAME xadGetInfo - get information about an archive SYNOPSIS result = xadGetInfoA(ai, tags) D0 A0 A1 LONG xadGetInfo(struct xadArchiveInfo *, struct TagItem *) result = xadGetInfo(ai, tag1, ...) LONG xadGetInfo(struct xadArchiveInfo *, Tag, ...) FUNCTION This function returns all useful information about a specified archive. It opens the archive for working. You may call xadFileUnArc() or xadDiskUnArc() for the included entries after a successful call to xadGetInfo. The data must be freed by a call to xadFreeInfo(). After that the xadArchiveInfo structure must be freed and NEVER be used again! For archives encrypting the information parts as well, you need to specify XAD_PASSWORD. This password can be used for all calls to a unarchiving function, but is overwritten by XAD_PASSWORD tag argument (only for the entry XAD_PASSWORD is specified). Check and parse the elements xai_FileInfo and xai_DiskInfo. You may expect both lists to have valid entries or also both to be empty. Parsing the lists is the normal way to do anything. The supplied input stream is used and must be valid and unmodified until xadFreeInfo() is called. Only the current client is allowed to access the stream, but it is guaranteed to be unmodified! INPUT ai - the master communication structure tags - Pointer to an array of struct TagItem. Recognized tags: XAD_INSIZE, XAD_INFILENAME, XAD_INFILEHANDLE, XAD_INMEMORY, XAD_INHOOK, XAD_PASSWORD RESULT result - any of the XADERR codes or zero when all is ok. SEE ALSO libraries/xadmaster.h, xadFreeInfo(), xadDiskUnArc(), xadFileUnArc(), tags section xadmaster.library/xadHookAccess xadmaster.library/xadHookAccess NAME xadHookAccess - a client only function to get/store data SYNOPSIS result = xadHookAccess(command, data, buffer, ai) D0 D0 D1 A0 A1 LONG xadHookAccess(ULONG, LONG, APTR, struct xadArchiveInfo *) FUNCTION This function is for external clients only. It is needed to get data, store results and seek in input or output. There are 5 commands XADAC_READ, XADAC_WRITE, XADAC_COPY, XADAC_INPUTSEEK, XADAC_OUTPUTSEEK to do that. This function updates the xai_InPos, xai_OutPos and xai_OutSize fields in xadArchiveInfo structure. The seek commands and the copy command should set buffer parameter to zero. Seek's and reads should not exceed the file borders! The client knows position and size, so checks are possible before doing wrong commands. INPUT command - one of the XADAC command to control hook data - the required data, mostly a size value buffer - the input/output buffer for read and write ai - the master communication structure RESULT result - any of the XADERR codes or zero when all is ok. SEE ALSO libraries/xadmaster.h xadmaster.library/xadRecogFile xadmaster.library/xadRecogFile NAME xadRecogFile - check if a file is an archive file or not SYNOPSIS client = xadRecogFileA(size, memory, tags) D0 D0 A0 A1 struct xadClient *xadRecogFileA(ULONG, APTR, struct TagItem *) client = xadRecogFileA(size, memory, tag1, ...) struct xadClient *xadRecogFileA(ULONG, APTR, Tag, ...) FUNCTION This function can be used to check if a file is a archive or not. It has only limited abilities! You need to pass a pointer to memory of recogsize. The recogsize value can be found in xadMasterBase. If the file is shorter, use the complete file as buffer. Longer buffers are allowed as well. When the file is archived, you get back a pointer to the client which detected the file. If not, the return is zero. The only usable information should be the name of the client. To get more information and all archive related data you have to use xadGetInfo, which calls xadRecogFile internal itself. Normally this function is not needed by application programs. It is used in xadList utility. This function is useful for tools only detecting and displaying the archiver type. INPUT size - size of the memory region memory - pointer to the memory holding the file tags - Pointer to an array of struct TagItem. Recognized tags: XAD_NOEXTERN RESULT client - pointer to client structure or zero when no archive SEE ALSO libraries/xadmaster.h, xadGetInfo(), tags section xadmaster.library/--tags-- xadmaster.library/--tags-- TAGS FOR xadAllocObject XAD_OBJBLOCKENTRIES (ULONG) Can be specified together with XADOBJ_DISKINFO. This allocates memory for xdi_BlockInfo. Data field of tag item contains number of required blocks. Memory gets freed automatically, when object is freed. XAD_OBJCOMMENTSIZE (ULONG) Like XAD_OBJNAMESIZE, but allocates memory for xfi_Comment entry. XAD_OBJNAMESIZE (ULONG) Can be specified together with XADOBJ_FILEINFO. This allocates memory for storing file name. The required size has to be stored in data field of tag item. The allocated memory pointer is stored in xfi_FileName field of returned structure. Memory gets freed automatically, when object is freed. XAD_OBJPRIVINFOSIZE (ULONG) Can be specified together with XADOBJ_FILEINFO and XADOBJ_DISKINFO. This allocates longword aligned client private buffer, which is stored in xfi_PrivateInfo or xdi_PrivateInfo field. The required size has to be stored in data field of tag item. Memory gets freed automatically, when object is freed. TAGS FOR xadGetInfo XAD_INFILEHANDLE (BPTR) FileHandle to get data from. It is not necessary that the handle is at the beginning of the file. XAD_INFILENAME (STRPTR) Name of the input file. XAD_INHOOK (struct Hook *) This enables any other way of data delivering. See special chapter on I/O hook functions. XAD_INMEMORY (STRPTR) Pointer to a memory buffer holding the input data. You need to specify XAD_INSIZE when using this. XAD_INSIZE (ULONG) Specify the size of input data. Must be used together with XAD_INMEMORY. Can be used together with other hooks. XAD_INSPLITTED (struct xadSplitFile *) For multivolume archives it is necessary to supply multiple files. This tag allows to pass multiple input streams of any type in a linked list of xadSplitFile structures. The clients see that as one single continous stream (except that ai->xai_MultiVolume contains a field with size information for every part). Each entry must contain one of the other input types and the corresponding data. Also the size can be or must be (XAD_INMEMORY) passed in xadSplitFile structure. Clients could expect the parts in it correct order, but should be able to handle missing or corrupted part. TAGS FOR xadFileUnArc and xadDiskUnArc XAD_ENTRYNUMBER (ULONG) This flag specifies the wanted entry. You must not specify more or less than one of that flag every call. Normally this flag equals the element xdi_EntryNumber for currently parsed xadDiskInfo structure and xfi_EntryNumber for currently parsed xadFileInfo structure. XAD_MAKEDIRECTORY (BOOL) Create missing directory tree when necessary. If not set the progress hook may get asked if directory should be created or not (if there is one). XAD_OUTFILEHANDLE (BPTR) FileHandle to send data to. It is not necessary that the handle is at the beginning of the file. XAD_OUTFILENAME (STRPTR) Name of the output file. XAD_OUTHOOK (struct Hook *) This enables any other way of data storing. See special chapter on I/O hook functions. XAD_OUTMEMORY (STRPTR) Pointer to a memory buffer to store data in. You need to specify XAD_OUTSIZE when using this. XAD_OUTSIZE (ULONG) Specify the maximum size of output data. Must be used together with XAD_OUTMEMORY. XAD_OVERWRITE (BOOL) This forces the file hook to overwrite existing destination files. If not set the progress hook may get asked if files should be overwritten or not (if there is one). XAD_PROGRESSHOOK (struct Hook *) The progress hook for status displays. See special progress hook chapter for more information. TAGS FOR xadDiskUnArc XAD_IGNOREGEOMETRY (BOOL) This forces the device hook to use devices with different drive geometry than the one on disk archive. Most time this will produce useless disks. If not set the progress hook may get asked if geometry should be ignored or not (if there is one). XAD_HIGHCYLINDER (ULONG) It specifies the highest cylinder which should be unarchived. XAD_LOWCYLINDER (ULONG) It specifies the lowest cylinder which should be unarchived. XAD_OUTDEVICE (struct xadDeviceInfo *) For disk archives it is useful to store data directly on a disk. Use this tag to specify the device where data should be stored. In xdi_DOSName the DOS device must be stored, which must not be terminated with a ':' character. Alternatively in fields xdi_DeviceName and xdi_Unit the wanted device must be specified. The device must support TD_GETGEOMETRY command, even if XAD_IGNOREGEOMETRY is turned on, as the hook needs at least the blocksize for internal buffering. NOTE: When xdi_DeviceName and xdi_Unit is used, the hook cannot perform an Inhibit operation and thus it cannot prevent other tasks from accessing the device. Also a DOS device is not updated, so a DiskChange becomes necessary. I suggest always using xdi_DOSName field! XAD_VERIFY (BOOL) Turns on verify for device output. This is turned off by default. TAGS FOR xadConvertDates XAD_DATEUNIX (ULONG) Input is an UNIX date value (seconds starting with 01.01.1970). XAD_DATEAMIGA (ULONG) Input as an Amiga date value (seconds starting with 01.01.1978). XAD_DATEDATESTAMP (struct DateStamp *) Input is a pointer to an Amiga DateStamp structure. XAD_DATEXADDATE (struct xadDate *) Input is a pointer to a xadmaster date structure. XAD_DATECLOCKDATA (struct ClockData *) Input is a pointer to a ClockData structure. XAD_DATECURRENTTIME (void) Current system time value should be used as input. XAD_DATEMSDOS (ULONG) Input is an 32 bit packed date format used by MS-DOS. This means: Bit 0..4 is half second (25 = second 49 or 50), 5..10 is minute, 11..15 is hour, 16..20 is day, 21..24 is month (1 = january) and 25..31 is year (0 = year 1980). This format is used for archivers like RAR or Zip. XAD_GETDATEUNIX (ULONG *) An UNIX time value should be stored in the ULONG variable, the supplied pointer points to. XAD_GETDATEAMIGA (ULONG *) An Amiga time value should be stored in the ULONG variable, the supplied pointer points to. XAD_GETDATEDATESTAMP (struct DateStamp *) The date should be stored in DateStamp structure the supplied pointer points to. XAD_GETDATEXADDATE (struct xadDate *) The date should be stored in xadmaster date structure the supplied pointer points to. XAD_GETDATECLOCKDATA (struct ClockData *) The date should be stored in ClockData structure the supplied pointer points to. XAD_GETDATEMSDOS (ULONG *) An MS-DOS packed date value should be stored in the ULONG variable, the supplied pointer points to. XAD_MAKEGMTDATE (BOOL) This forces the function to subtract the GMT offset supplied by locale.library to convert a local date to GMT date. Opening locale.library is required for that. When it cannot be openend or the offset would cause a overrun or underrun in the xd_Year field, no offset will be used. XAD_MAKELOCALDATE (BOOL) This forces the function to ad the GMT offset supplied by locale.library to convert a GMT date to a local date. Opening locale.library is required for that. When it cannot be openend or the offset would cause a overrun or underrun in the xd_Year field, no offset will be used. TAGS FOR different functions XAD_NOEXTERN (BOOL) When this is specified for xadGetInfo or xadRecogFile, the library skips any external clients. Normally this should not be necessary. Some of the main clients are external as well (for legal reasons). XAD_PASSWORD (STRPTR) You may supply a password for xadGetInfo, xadFileUnArc and xadDiskUnArc functions. xadmaster.library/-- data hooks-- xadmaster.library/--data hooks-- GENERAL You have four methods of passing data to xadmaster.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 xadHookParam in A1. Commands are stored in xhp_Command field, data in the other fields. Return values are 0 or any of the XADERR codes. Unsupported commands are returned with XADERR_NOTSUPPORTED. You may store a pointer to private data in the field xhp_PrivatePtr. You always get a XADHC_FREE after work to enable you freeing your resources. Whenever an error occured, the hook gets called with XADHC_ABORT. Use this to delete partial file, free useless memory or whatever you used. You must not do cleanup stuff on XADHC_ABORT call, as XADHC_FREE call follows after it. 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. COMMANDS XADHC_READ (input hooks only) This command is called all time xadmaster.library needs some data. Fill the supplied memory area with input data of needed size. Input: xhp_BufferSize size of required data xhp_BufferPtr buffer to fill Output: xhp_DataPos buffer position after read XADHC_WRITE (output hooks only) This function is called, when some data should be stored. Copy the contents of buffer to your data storing system. Input: xhp_BufferSize size of data xhp_BufferPtr pointer to memory area Output: xhp_DataPos buffer position after write XADHC_SEEK (both) Change the current position in your data (like dos.library Seek command). The offset you have to seek is always relative to current position. It can be negative too. Seek's with size 0 can be used to get current file position. Input: xhp_CommandData offset you have to seek Output: xhp_DataPos buffer position after seek XADHC_INIT (both) The work starts. Allocate needed structures and initialize your stuff. Clear xhp_BufferPos. Input: none Output: none XADHC_FREE (both) You get this when work is finished, free all your stuff now. You need to clear all pointers you use for checking, as it may happen that you get multiple XADHC_FREE commands. Input: none Output: none XADHC_ABORT (output hooks only) You get this when work was aborted, because an error occured. Free all work stuff. Buffers must be freed by later XADHC_FREE call. Be prepared to get multiple XADHC_ABORT commands. Input: none Output: none XADHC_FULLSIZE (input hooks only) The hook should return complete size of input data which should be processed. Input: none Output: xhp_CommandData size of input file xadmaster.library/-- progress hooks-- xadmaster.library/--progress hooks-- GENERAL This hook can be used to do display completion reports or ask the user. It gets a pointer to a xadProgressInfo structure. The hook returns a combination of XADPIF flags. A return value without XADPIF_OK (mostly 0) means a break command. Normally a hook should check for <CTRL>-<C> presses (or any other break condition) and add a XADPIF_OK to return value when no break condition exists. A progress hook must not support all possibilities! For example hooks from file unarchiving utilities never need an XADPIF_IGNOREGEOMETRY check. Also they need not support renaming or any other stuff. But the more they support, the better the user can work with the tool! MODES XADPMODE_ASK The master library has some problems, which need user interaction. The implementation of the user interaction depends on the application. The xpi_Status holds information what question needs to be answered. When XADPIF_OVERWRITE is set, the hook must determine if the file should be overwritten, renamed or not. The return flags must be set corresponding to this decision. Same is for XADPIF_IGNORGEGEOMETRY and XADPIF_MAKEDIRECTORY flag. XADPIF_IGNOREGEOEMTRY The hook either returns XADPIK_OK|XADPIF_IGNOREGEOMETRY or only XADPIF_OK, when user doesn't think geometry can be ignored. XADPIF_MAKEDIRECTORY The hook either returns XADPIK_OK|XADPIF_MAKEDIRECTORY or only XADPIF_OK, when user doesn't want to make directory. XADPIF_OVERWRITE The destination file already exists. The user should get 6 chances now (named with some standard letters). N - Do not do anything. The hook returns XADPIF_OK. Y - Turn overwrite on. The hook returns XADPIF_OK|XADPIF_OVERWRITE. A - Turn overwrite on for all files. The hook stores this information and returns XADPIF_OK|XADPIF_OVERWRITE. All following XADPIF_OVERWRITE requests are automatically answered with this return. S - Skip that file. The hook returns XADPIF_OK|XADPIF_SKIP. Q - Quit the program. The hook returns XADPIF_OK and the program quits before next call. R - The user wants to rename the file. The hook calls xadAllocVec() to get some memory for the name and passes this in xpi_NewName. This memory is freed by xadmaster.library afterwards! The return value is XADPIF_OK|XADPIF_RENAME. XADPMODE_END This is the last progress display with final results. XADPMODE_ERROR An error occured. The error value is in xpi_Error field. XADPMODE_PROGRESS Normal progress display. Depending on data type (disk/file), some progress information can be displayed. RETURN VALUES 0 or anything without XADPIF_OK The work should be aborted. The master library returns XADERR_BREAK. XADPIF_OK No break condition occured. The normal return value for progress display. Also used when user choosed to answer NO to XADPMODE_ASK questions. XADPIF_OK|XADPIF_IGNOREGEOMETRY User choosed that drive geometry can be ignored. XADPIF_OK|XADPIF_MAKEDIRECTORY User choosed that directory should be created. XADPIK_OK|XADPIF_OVERWRITE User choosed that file should be overwritten. XADPIF_OK|XADPIF_RENAME User choosed that file should be renamed. The field xpi_NewName must contain a memory block allocated with xadAllocVec() which holds a new file name. This block is freed by xadmaster.library afterwards! XADPIF_OK|XADPIF_SKIP User choosed to skip that file. The master library returns XADERR_SKIP in that case.