Enigma Amiga Life 113

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

/ Enigma Amiga Life 113 / EnigmaAmiga113CD.iso / software / varie / xad / developer / include / autodocs / xadmaster.doc next >

Wrap

Text File | 2000-06-25 | 50.8 KB | 1,317 lines

TABLE OF CONTENTS xadmaster.library/--general-- xadmaster.library/xadAllocObject xadmaster.library/xadAllocVec xadmaster.library/xadCalcCRC16 xadmaster.library/xadCalcCRC32 xadmaster.library/xadConvertDates xadmaster.library/xadConvertProtection xadmaster.library/xadCopyMem xadmaster.library/xadDiskUnArc xadmaster.library/xadDiskFileUnArc xadmaster.library/xadFileUnArc xadmaster.library/xadFreeInfo xadmaster.library/xadFreeObject xadmaster.library/xadGetClientInfo xadmaster.library/xadGetDiskInfo xadmaster.library/xadGetErrorText xadmaster.library/xadGetInfo xadmaster.library/xadHookAccess xadmaster.library/xadHookTagAccess xadmaster.library/xadRecogFile xadmaster.library/--tags-- xadmaster.library/--data hooks-- xadmaster.library/--progress hooks-- VERSION $VER: xadmaster.doc 7.0 (04.06.2000) 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! 2a)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 input stream methods. 2b)Call xadGetDiskInfo() to find out if input data is filesystem data. Goto step 5 if step 2 returns error code! 3) For every file in a file archive or every disk call xadFileUnArc() or xadDiskUnArc() (or xadDiskFileUnArc() if you did step 2b) with one tag XAD_ENTRYNUMBER set to wanted entry. One of the output tags must be specified here. Passwords and other stuff is additionally allowed and sometimes required. 4) Call xadFreeInfo() to free the stuff allocated with xadGetInfo() or xadGetDiskInfo(). 5) Use xadFreeObjectA() to free the xadArchiveInfo structure. If using xadGetDiskInfo(), there maybe multiple filesystems on one disk. If one is detected, do another run and use XAD_STARTCLIENT in step 2b). If you detected disk archives, it maybe useful to scan them for file- systems as well. 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. They 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. The structures are initialized, which means filled with zero in nearly all cases. Fields allocated with XAD_OBJxxx are filled with corresponding pointers and are cleared also. It is NOT necessary to leave these pointers intact when calling xadFreeObject(). 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 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 possible to choose the calculation method by parameter id. 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 possible to choose the calculation method by parameter id. 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 xadConvertDatesA(struct TagItem *) result = xadConvertDates(tag1, ...) LONG xadConvertDates(Tag, ...) FUNCTION This function can be used to transform 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_MAKEGMTDATE, XAD_MAKELOCALDATE RESULT result - any of the XADERR codes or zero when all is ok. SEE ALSO libraries/xadmaster.h, tags section xadmaster.library/xadConvertProtection xadmaster.library/xadConvertProtection NAME xadConvertProtection - convert between different protection bits (V4) SYNOPSIS result = xadConvertProtectionA(tags) D0 A0 LONG xadConvertProtectionA(struct TagItem *) result = xadConvertProtection(tag1, ...) LONG xadConvertProtection(Tag, ...) FUNCTION This function can be used to transform protection bits of different operating systems. The protection values are initialised with the Amiga standard values "rwed". These bits are modified by specified XAD_PROTxxx tags, but only the bits supported by that format (e.g. most systems do not support "s" or "p"). You may specify multiple XAD_PROTxxx tags, if a program stores them in different formats. As Amiga supports all bits, it is necessary to specify XAD_PROTAMIGA as first argument in such cases. The taglist must contain at least one of the XAD_GETPROTxxx tags. Currently only XAD_GETPROTAMIGA is supported. The stored result is not affected by the position of the XAD_GETPROTxxx tag in the list of tags! The result are always the bits, which are computed of all input tags. INPUT ai - the master communication structure tags - Pointer to an array of struct TagItem. Recognized tags: XAD_PROTAMIGA, XAD_PROTUNIX, XAD_PROTMSDOS, XAD_GETPROTAMIGA 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 (V2) SYNOPSIS xadCopyMem(src, dest, size) A0 A1 D0 void xadCopyMem(APTR, APTR, ULONG) FUNCTION xadCopyMem is a general purpose memory copy function. It can deal 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 xadDiskUnArcA(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 successful 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, XAD_NOKILLPARTIAL, XAD_FORMAT, XAD_MAKEDIRECTORY RESULT result - any of the XADERR codes or zero when all is ok. SEE ALSO libraries/xadmaster.h, xadFileUnArc(), xadGetInfo(), tags section xadmaster.library/xadDiskFileUnArc xadmaster.library/xadDiskFileUnArc NAME xadDiskFileUnArc - for unarchiving files from disk image (V4) SYNOPSIS result = xadDiskFileUnArcA(ai, tags) D0 A0 A1 LONG xadDiskFileUnArcA(struct xadArchiveInfo *, struct TagItem *) result = xadDiskFileUnArc(ai, tag1, ...) LONG xadDiskFileUnArc(struct xadArchiveInfo *, Tag, ...) FUNCTION This function extracts a file from disk images. It can be called after a succesful call to xadGetDiskInfo(). 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. 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_NOKILLPARTIAL, XAD_MAKEDIRECTORY RESULT result - any of the XADERR codes or zero when all is ok. SEE ALSO libraries/xadmaster.h, xadGetDiskInfo(), 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 xadFileUnArcA(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, XAD_NOKILLPARTIAL, XAD_MAKEDIRECTORY 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() or xadGetDiskInfo(). 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(), xadGetDiskInfo() 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 xadAllocVec(). 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/xadGetDiskInfo xadmaster.library/xadGetDiskInfo NAME xadGetDiskInfo - get information about files from disk image (V4) SYNOPSIS result = xadGetDiskInfoA(ai, tags) D0 A0 A1 LONG xadGetDiskInfoA(struct xadArchiveInfo *, struct TagItem *) result = xadGetDiskInfo(ai, tag1, ...) LONG xadGetDiskInfo(struct xadArchiveInfo *, Tag, ...) FUNCTION This function returns all useful information about a specified disk image filesytem structure. The information about files, directories and links are stored in xai_FileInfo list. You may call xadDiskFileUnArc() to extract files from the disk image. The data must be freed by a call to xadFreeInfo(). After that the xadArchiveInfo structure must be freed and NEVER be used again! The supplied input stream is used and must be valid and unmodified until xadFreeInfo() is called. Only the master functions are 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_INSPLITTED, XAD_INDISKARCHIVE, XAD_STARTCLIENT RESULT result - any of the XADERR codes or zero when all is ok. SEE ALSO libraries/xadmaster.h, xadFreeInfo(), xadDiskFileUnArc(), xadGetInfo(), tags section 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 xadGetInfoA(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 with XAD_PASSWORD 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_INSPLITTED, 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. See also xadHookTagAccess() function, which allows to pass tags for deeper control, which is necessary sometimes. INPUT command - one of the XADAC commands 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, xadHookTagAccess() xadmaster.library/xadHookTagAccess xadmaster.library/xadHookTagAccess NAME xadHookTagAccess - a client only function to get/store data (V3) SYNOPSIS result = xadHookTagAccessA(command, data, buffer, ai, tags) D0 D0 D1 A0 A1 A2 LONG xadHookTagAccessA(ULONG, LONG, APTR, struct xadArchiveInfo *, struct TagItem *) result = xadHookTagAccess(command, data, buffer, ai, tag1, ...) LONG xadHookTagAccess(ULONG, LONG, APTR, struct xadArchiveInfo *, Tag, ...) FUNCTION This function equals xadHookAccess() but allows to use tags to get better control. This includes CRC creation and use of xadSkipInfo system. INPUT command - one of the XADAC commands 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 tags - Pointer to an array of struct TagItem. Recognized tags: XAD_CRC16ID, XAD_CRC32ID, XAD_GETCRC16, XAD_GETCRC32, XAD_USESKIPINFO RESULT result - any of the XADERR codes or zero when all is ok. SEE ALSO libraries/xadmaster.h, xadHookAccess(), tags section 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 = xadRecogFile(size, memory, tag1, ...) struct xadClient *xadRecogFile(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() and xadGetDiskInfo() 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 *) (V2) 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 xadGetDiskInfo() XAD_INDISKARCHIVE (struct TagItem *) (V4) This hook allows to supply a disk archive as input source for file extraction from disk image files. You need to pass a pointer to a tagitem list (finished with TAG_DONE!) as data. This list is passed to xadGetInfo(). It may contain any of the tags supported by that function and must contain any of the input hook tags! Additionally it may contain XAD_ENTRYNUMBER to specify the entry, which should be used! If not, the first entry is used! XAD_STARTCLIENT (struct xadClient *) (V7) As there may be multiple filesystems on one disk image file (e.g. standard AmigaOS filesystem hiding an other one), it is useful to rescan the file. If you call xadGetDiskInfo() with this tagitem set to the client which comes after the one found in previous run (ai->xai_Client->xc_Next), you may detect such double systems also. 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_NOKILLPARTIAL (BOOL) (V3.3) If this is set to true, partial or corrupted files get not deleted. This has effect only for file output hook and only if the filename was passed (and not the FileHandle pointer). 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. XAD_FORMAT (BOOL) (V5) Turns on formating of output device. 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) (V2) 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 *) (V2) 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 add 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 xadHookTagAccess() (V3) XAD_CRC16ID (UWORD) This tag specifies the CRC-ID, which should be used for CRC16 calculation. The default value is XADCRC16_ID1. XAD_CRC32ID (ULONG) This tag specifies the CRC-ID, which should be used for CRC32 calculation. The default value is XADCRC32_ID1. XAD_GETCRC16 (UWORD *) A pointer to a UWORD variable holding the CRC start value and after calling xadHookTagAccess() the final CRC value. CRC checks are done for XADAC_COPY, XADAC_READ and XADAC_WRITE. XAD_GETCRC32 (ULONG *) Like XAD_GETCRC16, but for 32 bit checksums. XAD_USESKIPINFO (BOOL) The field xadSkipInfo of xadArchiveInfo structure is used to skip parts of the input stream for read, copy and input seek operations. Whenever this tag is used, then the contents of the xai_SkipInfo field is interpreted. The data parts specified in the list are skipped for read and seek operations, so that you get always continous data blocks. It does not ignore them totally, so file sizes and file position are not changed. So if you read 500 bytes and there is a 8 byte skip block in between, then file position increases by 508 byte, but you get 500 byte data without the skipped data. xadSkipInfo information only affects operations in input stream! The entries of xadSkipInfo list must not overlap and there must be at least one byte between entries! TAGS FOR xadConvertProtection() (V4) XAD_GETPROTAMIGA (ULONG *) This tag is used to get the computed protection bits in Amiga format including the multiuser bits. These can be store in xadFileInfo structure. XAD_PROTAMIGA (ULONG) Input bits of Amiga style. This tag is useful together with other tags only. Archives containing Amiga protection without multiuser bits and Unix bits may be converted this way: "XAD_PROTAMIGA, amigabits, XAD_PROTUNIX, unixbits, XAD_GETPROTAMIGA, &amigabits". Now the multiuser bits are inluded. Specifying this tag always resets calculation! It may be used to reset the default bits as well. Specifying and XAD_PROTxxx tags in front of this one is really useless. XAD_PROTMSDOS (ULONG) Input bits of MSDOS style: 0 = read only, 1 = hidden, 2 = system, 3 = volumename, 4 = directory, 5 = archived Only "r,w,a,d" bits of Amiga style are affected. XAD_PROTUNIX (ULONG) Input bits of UNIX style: 0 = other execute, 1 = other write, 2 = other read, 3 = group execute, 4 = group write, 5 = group read, 6 = execute, 7 = write, 8 = read This affects the "r,w,e" and the multiuser bits of Amiga style. 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, if 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 XADHC_IMAGEINFO (input hooks only) (V4) The hook should return information about disk image file. Normally hooks return XADERR_NOTSUPPORTED for this, like for all unsupported commands. Only the internal disk archive hook is able to return useful data. Input: xhp_CommandData contains pointer to xadImageInfo structure, which should be filled Output: xadImageInfo structure in xhp_CommandData is filled with data 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.