home *** CD-ROM | disk | FTP | other *** search
/ ARM Club 3 / TheARMClub_PDCD3.iso / programs / filing / shrink / !Help
Text File  |  1998-01-29  |  9KB  |  439 lines
  1.                             ShrinkWrap
  2.                             ==========
  3.  
  4.  
  5. *************************************************************************
  6.  
  7.                             Disclaimer
  8.                             ----------
  9. David Pilling accepts no responsibility for any loss of data
  10. which occurs as a result of using this program, whether as a
  11. result of correct or incorrect operation. You use ShrinkWrap
  12. at your own risk.
  13.  
  14. *************************************************************************
  15.  
  16.  
  17.  
  18. This is a module which intercepts filing system vectors in such a way that
  19. compressed files appear to applications to act like uncompressed files. The
  20. compression is transparent in other words.
  21.  
  22.  
  23. Particular filetypes are recognised as being compressed and of interest to
  24. the module, within the compressed files are the compressed data and the file
  25. attributes of the file which has been compressed.
  26.  
  27.  
  28. The main ShrinkWrap module uses GnuZip files. An extra tag defines RISC OS file
  29. attributes. Each GZip file maps to a single  RISC OS file. Only GZip files
  30. with the correct filetype and which contain the special RISC OS tag are
  31. handled by the module. Other GZips are ignored.
  32.  
  33.  
  34. Sub modules can register with the ShrinkWrap module to handle other
  35. filetypes. Currently two modules are available to support Acorn Squash files
  36. and Computer Concepts CFS files.
  37.  
  38.  
  39. The module only pays attention to files which are in certain places called
  40. 'zones' (given to the module via SWI and  CLI calls) where the left section
  41. of a full file path name matches one of the given places. Places can include
  42. a whole file system (e.g. one might say "SCSI" and any file held on any SCSI
  43. disc would be a possibility for compression/decompression) or a part of a
  44. file system (e.g. one might say  "ADFS::HardDisc4.Scrap"). 
  45.  
  46.  
  47. Compressed files are created by just saving in the normal way. 
  48.  
  49. However the following special process allows a compressed file to be created
  50. (subject to the filename restriction) for output:
  51.  
  52. - create a file with the compressed type (maybe of zero length, maybe not)
  53.  
  54. - change the file's type to any type at any later time
  55.  
  56. - open the file for update or writing to enable writing data which is
  57. compressed
  58.  
  59. - complete file write (OS_File) to enable writing compressed data.
  60.  
  61.  
  62.  
  63.  
  64. *Commands
  65. =========
  66.  
  67. *ShrinkWrapAddZone Adds an area to the ShrinkWrap zone
  68. Syntax: *ShrinkWrapAddZone <path> [all|none|some]
  69.  
  70. If the 'all' parameter is added, all files will be compressed.
  71. i.e. the file type control will not be used.
  72. If the 'none' parameter is added, no files will be compressed,
  73. other than those which already are compressed.
  74. If the 'some' parameter is added, then file types are used.
  75. The default setting i.e. if there is no final parameter is 'some'.
  76.  
  77.  
  78. *ShrinkWrapRemZone Removes an area from the ShrinkWrap zone
  79. Syntax: *ShrinkWrapRemZone <path>
  80.  
  81. *ShrinkWrapShowZone List ShrinkWrap zones
  82. Syntax: *ShrinkWrapShowZone
  83.  
  84. *ShrinkWrapAddType Adds a filetype for ShrinkWrap compression
  85. Syntax: *ShrinkWrapAddType <filetype>
  86.  
  87. *ShrinkWrapRemType Removes a filetype for ShrinkWrap compression
  88. Syntax: *ShrinkWrapRemType <filetype>
  89.  
  90. *ShrinkWrapShowType List ShrinkWrap compression filetypes
  91. Syntax: *ShrinkWrapShowType
  92.  
  93. *ShrinkWrapMemory sets memory slot sizes.
  94. Syntax: *ShrinkWrapMemory <min>[K] <max>[K]
  95.  
  96. Always uses at least <min> and never more than <max>
  97.  
  98. *ShrinkWrapStrength sets how hard ShrinkWrap tries to compress files.
  99. Syntax: *ShrinkWrapStrength <1..9>
  100.  
  101. Default 9 - max compression.
  102.  
  103. *ShrinkWrapZipCompress makes a GZip file.
  104. Syntax: *ShrinkWrapZipCompress <source> <destination>
  105.  
  106. *ShrinkWrapZipUncompress expands a GZip file.
  107. Syntax: *ShrinkWrapZipUncompress <source> <destination>
  108.  
  109.  
  110. *ShrinkWrapOn enables shrink wrapping.
  111. Syntax: *ShrinkWrapOn
  112.  
  113. *ShrinkWrapOff disables shrink wrapping.
  114. Syntax: *ShrinkWrapOff
  115.  
  116. These commands remove and add the module to the file switch vectors.
  117.  
  118.  
  119. *ShrinkWrapShowLink display linked ShrinkWrap filetypes.
  120. Syntax: *ShrinkWrapShowLink
  121.  
  122. Sample output
  123.  
  124. ShrinkWrapShowLink
  125. GZip             (&f89) *
  126. Squash           (&fca)  
  127. CFS              (&d96)  
  128.  
  129. The asterisk indicates which filetype is currently being used for compressing
  130. files.
  131.  
  132. *ShrinkWrapSetLink set filetype to be used for compression.
  133. Syntax: *ShrinkWrapSetLink <type name>
  134.  
  135.  
  136.  
  137.  
  138. System Variables
  139. ================
  140.  
  141. ShrinkWrap$Scrap
  142. Sets where scrap files are put. Defaults to <Wimp$ScrapDir>
  143.  
  144.  
  145. Allocations
  146. ===========
  147. Module name - ShrinkWrap
  148. SWI prefix  - ShrinkWrap
  149. SWI chunk     &4EA00
  150. Error block   &00811400
  151. Filetype      &F89 - GnuZip
  152.  
  153.  
  154. Swis
  155. ====
  156.  
  157. ShrinkWrap_Memory (&4EA00 + 0)
  158. ------------------------------
  159.  
  160. r0=0 control memory allocations
  161.  
  162. Entry r0=0
  163.       r1=min
  164.       r2=max
  165.  
  166. Exit  r1=min
  167.       r2=max
  168.       r3=current
  169.       r4=total memory in machine
  170.  
  171.  
  172. ShrinkWrap_Zip    (&4EA00 + 1)
  173. ------------------------------
  174.  
  175. r0=0  Make a GZip file
  176.  
  177. Entry r0=0
  178.       r1->source      filename
  179.       r2->destination filename
  180.  
  181. Exit  -
  182.  
  183.  
  184. r0=1  Expand a GZip file
  185.  
  186. Entry r0=0
  187.       r1->source      filename
  188.       r2->destination filename
  189.  
  190. Exit  -
  191.  
  192.  
  193. ShrinkWrap_Control (&4EA00 + 2)
  194. -------------------------------
  195.  
  196. r0=0  Add zones
  197.  
  198. Entry r0=0
  199.       r1->path to add
  200.       r2=0 zone uses file types, r2=1 all files are compressed
  201.                                  r2=2 no files are compressed
  202.       r3=0
  203.  
  204. Exit  -
  205.  
  206.  
  207. r0=1  Rem zones
  208.  
  209. Entry r0=1
  210.       r1->path to add
  211.  
  212. Exit  -
  213.  
  214.  
  215. r0=2  Add type
  216.  
  217. Entry r0=2
  218.       r1=type
  219.  
  220. Exit  -
  221.  
  222.  
  223. r0=3  Rem type
  224.  
  225. Entry r0=3
  226.       r1=type
  227.  
  228. Exit  -
  229.  
  230.  
  231. r0=4  Set strength
  232.  
  233. Entry r0=4
  234.       r1=strength
  235.  
  236. Exit  -
  237.  
  238.  
  239. r0=5  On/off
  240.  
  241. Entry r0=5
  242.       r1=0 off, r1=1 on, r1=2 no effect
  243.  
  244. Exit  r1=state
  245.  
  246.  
  247.  
  248. ShrinkWrap_Link (&4EA00 + 3)
  249. ----------------------------
  250. This swi allows modules to link to ShrinkWrap
  251.  
  252.  
  253. r0=0  Add link
  254.  
  255. Entry r0=0
  256.       r1->link block
  257.       r2=linked modules private word
  258.       r3=compatability level
  259.  
  260. Exit  -
  261.  
  262.  
  263. r0=1  Remove link
  264.  
  265. Entry r0=0
  266.       r1->link block
  267.  
  268. Exit  -
  269.  
  270.  
  271.  
  272.  
  273.  
  274. ShrinkWrap_Util (&4EA00 + 4)
  275. ----------------------------
  276. This swi makes available ShrinkWrap resources to the outside world.
  277.  
  278.  
  279. r0=0  Create a scrap file
  280.  
  281. Entry r0=0
  282.       r1->scrap handle
  283.  
  284. Exit  -
  285.  
  286.  
  287.  
  288. r0=1  Remove a scrap file
  289.  
  290.  
  291. Entry r0=1
  292.       r1==scrap handle
  293.       r2==previous error pointer
  294.  
  295. Exit  -
  296.  
  297.  
  298.  
  299. r0=2  Return an error block pointer
  300.  
  301.  
  302. Entry r0=2
  303.       r1==error number
  304.  
  305.  
  306. Exit  -
  307.  
  308.  
  309.  
  310. r0=3  Fill source buffer
  311.  
  312.  
  313. Entry r0=3
  314.       r1->buffer
  315.  
  316.  
  317. Exit  -
  318.  
  319.  
  320.  
  321. r0=4  Dump destination buffer
  322.  
  323.  
  324. Entry r0=4
  325.       r1->buffer
  326.  
  327.  
  328. Exit  -
  329.  
  330.  
  331.  
  332.  
  333. r0=5  CRC32 block
  334.  
  335.  
  336. Entry r0=5
  337.       r1->crc
  338.       r2->data
  339.       r3=length
  340.  
  341.  
  342. Exit  -
  343.  
  344.  
  345.  
  346.  
  347.  
  348.  
  349.  
  350. Service Calls
  351. =============
  352.  
  353. Service_ShrinkWrapStarting 0x80181
  354.  
  355. Issued when ShrinkWrap starts up - chance for modules to register.
  356.  
  357.  
  358.  
  359.  
  360.  
  361.  
  362. GZip &F89 file format
  363. =====================
  364.  
  365. The GNUZip file format - see below.
  366.  
  367. With an extension
  368.  
  369. Word 0 ='A'+(((int)'C')<<8)+((4*7)<<16);
  370. Word 1 =load address
  371. Word 2 =exec address
  372. Word 3 =file access bits
  373. Word 4 =file length
  374. Word 5 =0
  375. Word 6 =0
  376. Word 7 =0
  377.  
  378. GZip file format
  379.  
  380. The pkzip format imposes a lot of overhead in various headers, which are
  381. useful for an archiver but not  necessary when only one file is compressed.
  382. gzip uses a much simpler structure. Numbers are in little  endian format, and
  383. bit 0 is the least significant bit.
  384.  
  385. A gzip file is a sequence of compressed members. Each member has the
  386. following structure:
  387.  
  388. 2 bytes magic header 0x1f, 0x8b (\037 \213)
  389. 1 byte compression method (0..7 reserved, 8 = deflate)
  390. 1 byte flags
  391. bit 0 set: file probably ascii text
  392. bit 1 set: continuation of multi-part gzip file
  393. bit 2 set: extra field present
  394. bit 3 set: original file name present
  395. bit 4 set: file comment present
  396. bit 5 set: file is encrypted
  397. bit 6,7: reserved
  398. 4 bytes file modification time in Unix format
  399. 1 byte extra flags (depend on compression method)
  400. 1 byte operating system on which compression took place
  401.  
  402. 2 bytes optional part number (second part=1)
  403. 2 bytes optional extra field length
  404. ? bytes optional extra field
  405. ? bytes optional original file name, zero terminated
  406. ? bytes optional file comment, zero terminated
  407. 12 bytes optional encryption header
  408. ? bytes compressed data
  409. 4 bytes crc32
  410. 4 bytes uncompressed input size modulo 2^32
  411.  
  412. The extra field, if present, must consist of one or more subfields, each with
  413. the following format:
  414.  
  415. subfield id : 2 bytes
  416. subfield size : 2 bytes (little-endian format)
  417. subfield data
  418.  
  419. The subfield id can consist of two letters with some mnemonic value.
  420.  
  421. Ids with a zero second byte are reserved for future use. The following ids
  422. are defined: Ap (0x41, 0x70) : Apollo file type information The subfield
  423. size is the size of the subfield data and does not include the id and the
  424. size itself. The field  'extra field length' is the total size of the extra
  425. field, including subfield ids and sizes.
  426.  
  427.  
  428.  
  429.  
  430. (c) David Pilling 1997
  431.  
  432. --
  433. email: david@pilling.demon.co.uk
  434.   web: http://www.netlink.co.uk/users/pilling
  435.   web: http://www.pilling.demon.co.uk
  436.  post: David Pilling, P.O. Box 22, Thornton Cleveleys, Blackpool. FY5 1LR. UK.
  437.  
  438.  
  439.