About the source code:
======================

(turn on word wrap to read this)

Revision History:

Date		Version	Remarks
==========	=======	=======
2007-05-26	0.0.7	Rewrote app to use IStream objects instead of VB's file handling
			functions. Added cStreamCopy and updated dialogs.
			Will now require the OLELIB type library from Eduardo Morcillo
			(details below) as well as implicit support from Internet Explorer.
			Added multicolor progress bar effect (for cosmetics)
			Added SetStatus, some warnings, and a quick check for garbled AVIs.
			Added credits, accessible from the About dialog.
			Added debug.bas (courtesy of Bruce McKinney) for debugging purposes.
2007-05-18	0.0.6	Fixed bug where cManifest was confused by unknown key/value pairs.
			It threw an exception in good order, but the handler which caught
			it didn't do squat, including telling the user. Sloppy! Sheesh!
2007-05-12	0.0.5   Initial release. 

NEW:
-------
  UnZixWin now supports files larger than 2GB in size (it uses IStream objects from shlwapi.dll). But a type library is required in order to run or compile the VB code.
  The type library can be found at http://www.mvps.org/emorcillo. Look for the OLELIB.TLB in the VB6 code section. It's a gem!

IN THE PIPELINE:
----------------
  I'm considering using DHTML for the user interface. This would require the WebBrowser control which is installed by default with Internet Explorer. Since UnZixWin is already dependent on SHLWAPI.DLL, expecting IE to be on the system may not be such a stretch.
  Using DHTML would provide me with the freedom to present the UI in a more feature-rich way, to
make up for the lack of Common Controls and other modern UI elements. Thoughts?
  As an added bonus, I can use XML/XSLT as the format for data structure and presentation engine,
which would be beneficial

  Also, I'm considering adding decryption/degarbling support to the app, if and when I figure out
what exactly the garbage in some crippled 'AVI's is. If anyone manages to unscramble one of these,
let me know what the scrambling method was. Wouldn't it be cool if you beat me to it?

OVERVIEW:
=========
  Apologies for the crudity of the source code; it was a rush job, and it shows.
The plainness of the user interface is partly intentional, however. I wrote this utility to be runnable out-of-the-box, without a setup program or other installation package. I figured that by running the wretched WinZix setup program, users might be wary of running another such program for some time to come. Therefore, this app cannot contain any externally loadable user controls, such as Common Controls or even the Common Dialog Control. The one, inescapable dependancy is the VB6 runtimes.

In order to reduce dependencies on any external DLL's or OCXs, the following limitations apply:
* Could not use ListView, TreeView, StatusBar, ToolBar or any other Common Control. Any such functionality has been implemented using intrinsic controls or API code.
  True, the Common Controls can be instantiated and used without the OCX, using  raw API calls, but this requires a fair chunk of programmatic effort and subclassing, and I have yet to see a stable and reliable VB implementation of this. 
* Could not use the Common Dialog control. Instead, I used the replacement code provided by Steve McMahon (http://vbaccelerator.com). cMemory.cls, cCommonDialog.cls, GCommonDialog.cls, mDialogHook.bas and m_Objects.bas are his creations, and he retains full copyright on them. For an explanation of how they work, go tho his site and check out the VB section.

The only really awful visual limitation is the use of a standard list box instead of a listview. Man, it looks crappy! The absence of icons and column headers makes it look sooo 1992!

The most confusing piece of code has got to be the cManifest class, which is used to parse torrent files and the content list of ZIX archives. It uses recursive functions which call themselves with various context parameters, so the code will know from the context where it is and what kind of data to expect, and what to do with it. To understand this code, you have to know how the internals of torrent files are organized, be familiar with recursive functions, and so on.
One thing that you shold know is that the GetString function is sometimes used intentionally to read past the end-of-list and end-of dictionary markers, in order to line the file up for whatever function is to be called next. It looks like a programming error, but actually works quite well.

I already regret writing it like this. If I do it again, I'll probably write code to turn the metadata into XML, then use XPath and XSLT to probe for the information I want. I would have done so now, but this would have generated a dependancy on MSXML, and I don't know which (if any) version of that might be installed on a user's system. Since I didn't want to produce a full setup package, that wasn't an option.

The cStreamReader class
=======================
Using VB has a few limitations, all of which can be worked around. VB's own file handling functions are limited to files of about 2 gigs in size, which is why UnZixWin uses IStreams obtained from the
system instead. But these operate with ULARGE_INTEGER, a data type VB can't handle natively.
UnZixWin (actually, the OLELIB type library) works around these by casting these as Currency, a VB data type large enough to hold the bits. But once a ULARGE_INTEGER has been cast into a Currency variable, we have to shift it to get out of the fractional domain of the data. Hence, to get an integral value, we have to multiply by 10000. Similarly, in any call to a function which expects a ULARGE_INTEGER (and to which we pass a Currency variable instead), the argument must be divided by 10000 so that the receiver gets the bits in the right format.
  To add to the complexity, IStream objects will happily seek past the end of a file (legal in streams), yielding unpredictable results of read operations (you should be getting an error, but don't). Which is why you have to monitor your position in the stream yourself and watch for EOF.
To handle these chores, the cStreamReader class was written. It does all of the above, plus maintains a Push/Pop stack so you can store and restore your position in a stream.

I advise against using this source code elsewhere, for a couple of reasons:
  * It hasn't been completely tested yet, and the error handling code isn't bullet-proof.
  * (OBSOLETED as of version 0.0.7) The torrent/manifest parsing code has no provisions for handling future extensions to either the ZIX or BitTorrent formats. Encountering unknown dictionary entries will probably cause an error message.
  * VB6 is on death row. We have probably seen the last service pack for this language. Everything is Java or .Net nowadays. I intend to get with the program pretty soon, and you might want to  as well. 

That being said, have fun!

Regards,
//Kenneth
