Copyright: Copyright © 1997, 2001 Michael Newcomb and Frank Pilhofer.
Citation: Copyright © 1997, 2001 Michael Newcomb and Frank Pilhofer.


Contents

Welcome to Uud32acx, the UUDeview ActiveX control.

Overview

Common Procedures

Decoding

Encoding

Quick Decoding

X Files

Properties

Methods

Events

Return Codes

Constants

Contacting the Authors

Revision History

Warning: 	This ActiveX control is supplied “as-is” without any warranties of any kind whatsoever, including the implied warranties of merchantability and fitness for a particular purpose. By using this control, you assume ALL RISKS associated with its operation.

Copyrights

This Help file is Copyright © 1997, 2001, 2002 Michael Newcomb and Frank Pilhofer.

The UUDeview ActiveX control is Copyright © 1997, 2001, 2002 Michael Newcomb and Frank Pilhofer.

The UUDeview ActiveX control is freely available for non-commercial use under the GNU General Public License. Source code is available on request, again for non-commercial use. For commercial licensing, contact the control’s authors.

The GNU General Public License

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

Last Revised: 23 June, 2002


GNU General Public License

TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION

0.	This License applies to any program or other work which contains a notice placed by the copyright holder saying it may be distributed under the terms of this General Public License. The "Program", below, refers to any such program or work, and a "work based on the Program" means either the Program or any derivative work under copyright law: that is to say, a work containing the Program or a portion of it, either verbatim or with modifications and/or translated into another language. (Hereinafter, translation is included without limitation in the term "modification".) Each licensee is addressed as "you".

Activities other than copying, distribution and modification are not covered by this License; they are outside its scope. The act of running the Program is not restricted, and the output from the Program is covered only if its contents constitute a work based on the Program (independent of having been made by running the Program). Whether that is true depends on what the Program does.

1.	You may copy and distribute verbatim copies of the Program's source code as you receive it, in any medium, provided that you conspicuously and appropriately publish on each copy an appropriate copyright notice and disclaimer of warranty; keep intact all the notices that refer to this License and to the absence of any warranty; and give any other recipients of the Program a copy of this License along with the Program.

You may charge a fee for the physical act of transferring a copy, and you may at your option offer warranty protection in exchange for a fee.

2.	You may modify your copy or copies of the Program or any portion of it, thus forming a work based on the Program, and copy and distribute such modifications or work under the terms of Section 1 above, provided that you also meet all of these conditions:

a)	You must cause the modified files to carry prominent notices stating that you changed the files and the date of any change.

b)	You must cause any work that you distribute or publish, that in whole or in part contains or is derived from the Program or any part thereof, to be licensed as a whole at no charge to all third parties under the terms of this License.

c)	If the modified program normally reads commands interactively when run, you must cause it, when started running for such interactive use in the most ordinary way, to print or display an announcement including an appropriate copyright notice and a notice that there is no warranty (or else, saying that you provide a warranty) and that users may redistribute the program under these conditions, and telling the user how to view a copy of this License. (Exception: if the Program itself is interactive but does not normally print such an announcement, your work based on the Program is not required to print an announcement.)

These requirements apply to the modified work as a whole. If identifiable sections of that work are not derived from the Program, and can be reasonably considered independent and separate works in themselves, then this License, and its terms, do not apply to those sections when you distribute them as separate works. But when you distribute the same sections as part of a whole which is a work based on the Program, the distribution of the whole must be on the terms of this License, whose permissions for other licensees extend to the entire whole, and thus to each and every part regardless of who wrote it.

Thus, it is not the intent of this section to claim rights or contest your rights to work written entirely by you; rather, the intent is to exercise the right to control the distribution of derivative or collective works based on the Program.

In addition, mere aggregation of another work not based on the Program with the Program (or with a work based on the Program) on a volume of a storage or distribution medium does not bring the other work under the scope of this License.

3.	You may copy and distribute the Program (or a work based on it, under Section 2) in object code or executable form under the terms of Sections 1 and 2 above provided that you also do one of the following:

a)	Accompany it with the complete corresponding machine-readable source code, which must be distributed under the terms of Sections 1 and 2 above on a medium customarily used for software interchange; or,

b)	Accompany it with a written offer, valid for at least three years, to give any third party, for a charge no more than your cost of physically performing source distribution, a complete machine-readable copy of the corresponding source code, to be distributed under the terms of Sections 1 and 2 above on a medium customarily used for software interchange; or,

c)	Accompany it with the information you received as to the offer to distribute corresponding source code. (This alternative is allowed only for noncommercial distribution and only if you received the program in object code or executable form with such an offer, in accord with Subsection b above.)

The source code for a work means the preferred form of the work for making modifications to it. For an executable work, complete source code means all the source code for all modules it contains, plus any associated interface definition files, plus the scripts used to control compilation and installation of the executable. However, as a special exception, the source code distributed need not include anything that is normally distributed (in either source or binary form) with the major components (compiler, kernel, and so on) of the operating system on which the executable runs, unless that component itself accompanies the executable.

If distribution of executable or object code is made by offering access to copy from a designated place, then offering equivalent access to copy the source code from the same place counts as distribution of the source code, even though third parties are not compelled to copy the source along with the object code.

4.	You may not copy, modify, sublicense, or distribute the Program except as expressly provided under this License. Any attempt otherwise to copy, modify, sublicense or distribute the Program is void, and will automatically terminate your rights under this License. However, parties who have received copies, or rights, from you under this License will not have their licenses terminated so long as such parties remain in full compliance.

5.	You are not required to accept this License, since you have not signed it. However, nothing else grants you permission to modify or distribute the Program or its derivative works. These actions are prohibited by law if you do not accept this License. Therefore, by modifying or distributing the Program (or any work based on the Program), you indicate your acceptance of this License to do so, and all its terms and conditions for copying, distributing or modifying the Program or works based on it.

6.	Each time you redistribute the Program (or any work based on the Program), the recipient automatically receives a license from the original licensor to copy, distribute or modify the Program subject to these terms and conditions. You may not impose any further restrictions on the recipients' exercise of the rights granted herein.

You are not responsible for enforcing compliance by third parties to this License.

7.	If, as a consequence of a court judgment or allegation of patent infringement or for any other reason (not limited to patent issues), conditions are imposed on you (whether by court order, agreement or otherwise) that contradict the conditions of this License, they do not excuse you from the conditions of this License. If you cannot distribute so as to satisfy simultaneously your obligations under this License and any other pertinent obligations, then as a consequence you may not distribute the Program at all. For example, if a patent license would not permit royalty-free redistribution of the Program by all those who receive copies directly or indirectly through you, then the only way you could satisfy both it and this License would be to refrain entirely from distribution of the Program.

If any portion of this section is held invalid or unenforceable under any particular circumstance, the balance of the section is intended to apply and the section as a whole is intended to apply in other circumstances.

It is not the purpose of this section to induce you to infringe any patents or other property right claims or to contest validity of any such claims; this section has the sole purpose of protecting the integrity of the free software distribution system, which is implemented by public license practices. Many people have made generous contributions to the wide range of software distributed through that system in reliance on consistent application of that system; it is up to the author/donor to decide if he or she is willing to distribute software through any other system and a licensee cannot impose that choice.

This section is intended to make thoroughly clear what is believed to be a consequence of the rest of this License.

8.	If the distribution and/or use of the Program is restricted in certain countries either by patents or by copyrighted interfaces, the original copyright holder who places the Program under this License may add an explicit geographical distribution limitation excluding those countries, so that distribution is permitted only in or among countries not thus excluded. In such case, this License incorporates the limitation as if written in the body of this License.

9.	The Free Software Foundation may publish revised and/or new versions of the General Public License from time to time. Such new versions will be similar in spirit to the present version, but may differ in detail to address new problems or concerns.

Each version is given a distinguishing version number. If the Program specifies a version number of this License which applies to it and "any later version", you have the option of following the terms and conditions either of that version or of any later version published by the Free Software Foundation. If the Program does not specify a version number of this License, you may choose any version ever published by the Free Software Foundation.

10.	If you wish to incorporate parts of the Program into other free programs whose distribution conditions are different, write to the author to ask for permission. For software which is copyrighted by the Free Software Foundation, write to the Free Software Foundation; we sometimes make exceptions for this. Our decision will be guided by the two goals of preserving the free status of all derivatives of our free software and of promoting the sharing and reuse of software generally.

NO WARRANTY

11.	BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION.

12.	IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.

 Back to Contents


Overview

The Uud32acx control is a self-contained component designed to provide ASCII encoding and decoding services for binary files. That is, it translates between binary and the text formats used by Internet e-mail and newsreader programs.

The control is designed to make these encoding tasks as painless as possible. For example, in Decoding mode, there’s no need to sort the parts of a file into the correct order; the control will do that. The Encoding function can create multi-part files in a wide variety of styles with a single call.

To use the Uud32acx control, you’ll need to begin by creating an instance of the control in your program. In Visual Basic 5, for example, you would open the Project / Components… dialog box, then browse to find uud32acx.ocx.

Once the component is added to the list, you’ll see the name “uud32acx ActiveX Control module.” That’s the name the control lives under. In VB, you would check the box next to this legend to add the control to your toolbox.

The Uud32acx control looks like this in the toolbox:

To use the control in Visual Basic, you’ll need to draw an instance of it on a form and give it a name.

You can use the VB property list to set the control’s “persistent” properties, which are mostly flags that alter how the control operates.

When your program is running, you would use the control’s methods and properties to carry out the operations you require. For example, if you had named your control “UD” and you wanted to decode all the files in c:\narf.uue and write them to the path c:\poit, you would use the command:

UD.QuickDecode "c:\narf.uue", "c:\poit", False

Most Uud32acx methods return a code that indicates how the requested operation went. To retrieve this code, you would use the “function” form of the method:

rc = UD.QuickDecode("c:\narf.uue", "c:\poit", False)

The Return Codes section of this file describes what these codes mean.

Some Uud32acx methods, especially those that may take some time to complete, also fire events as they execute. The control uses these events to inform you of what the control is doing and how far it has progressed through the operation. The Events section describes how these features work.

 Back to Contents


Decoding

Decoding files retrieved from Internet e-mail or news is Uud32acx’s marquee function. The control can decode dozens of different encoding formats. It also understands UU encoding, XX encoding, MIME, and BinHex.

Uud32acx provides two basic ways to decode files. If you just want to decode all the files in a particular input file, you’ll probably find it simpler to use the Quick Decode method. This method takes care of loading the input file and writing out the anything encoded in it in one step.

The procedure described in this section gives you much more control over the decoding process. For example, you can load multiple encoded files, read the names of the files found during the scanning process, rename them before they are decoded, and so on.

Please note that this section intends only to describe the general technique used for decoding. Be sure to consult the documentation for the individual properties and methods used below before using them in your application.

The first step in this decoding process is reset the control, then to load the encoded input file or files using the DLoad method. The loading step parses the input files to find out what encoded data is included in them.

For example, to load all the UUE files in the directory c:\poit, you might do something like this (assuming the Uud32acx control is named “UD”):

Dim f as String, rc as Integer

' Reset the control before each decoding session

UD.Reset

f = Dir$("c:\poit\*.uue")

While f <> ""

rc = UD.DLoad("c:\poit\" + f)

If rc <> uudRetOK Then

MsgBox "Operation failed, return code " & _

rc, vbOkOnly, "Loading"

Exit Sub

End If

f = Dir$

Wend

Note that you can load essentially any number of files during one session, in any order. Uud32acx will parse the files and automatically rearrange multi-part files into the proper order when you begin decoding.

Once all the files have been loaded, you can check to see what encoded data the Uud32acx control found. First, you’ll need to check the DFCount property to see how many files were found. The other decode-related properties take an index from 0 to (DFCount - 1) to select the file that will be affected.

For example, if DFCount were equal to 5, then DFile(0) to DFile(4) would let you read the names of the files found during the loading operation.

Continuing the above example, you could use this code segment to print the names of all the files it found during the loading step to the “immediate” window:

Dim row as Integer, rmax as Integer

rmax = UD.DFCount - 1

For row = 0 to rmax

Debug.Print UD.DFile(row); "Status: "; UD.DFileStatus(row)

Next row

This code snippet uses the DFile property to retrieve the names of the encoded files that Uud32acx found and the DFileStatus property, which returns an English string describing the status of each file (e.g., is the file correctly formatted, are all the parts present, etc.). Obviously, it’s not much use to just print stuff on the debug window, but this should give you an idea.

Along the same lines, you can decode all the files that are decodable to the directory c:\narf by doing something like this:

Dim row as Integer, rmax as Integer, rc as Integer

rmax = UD.DFCount - 1

For row = 0 to rmax

If UD.DfileFlags(row) And uudFileOK Then

rc = UD.DFileTo(row, "c:\narf\" + UD.DFile(row))

If rc <> uudRetOK Then

MsgBox "Operation failed, return code " & _

rc, vbOkOnly, "Decoding"

Exit Sub

End If

End If

Next row

Anyway, that’s an introduction to the decoding process.

See also:

•	Options Properties

•	Decoding Methods

•	Decoding Properties

 Back to Contents


Encoding

Encoding is fairly straightforward and only involves one method. The trick is figuring out which parameter settings to use.

0	Uud32acx can create a wide variety of encoded formats, depending on what options you set. There are three basic option areas: encoding format, multi-part files, and headers.

1	The encoding format options determine which encoding scheme is used to translate your data. You can choose from UU, XX, and Base64 (MIME). UU encoding is the most popular and widely-recognized format; XX encoding is rarely used. MIME encoding is growing in popularity, but it is more complex to implement properly than the other schemes. For more information on using MIME encoding, see below.

2	Generating multi-part files is very straightforward. All you need to do is tell Uud32acx how many lines of encoded data to include in each part when you call the Encode method. If you set the number of lines to 0, Uud32acx will write all the encoded data to a single file with the name you specify in the Encode method call.

3	If you set the number of lines to something other than 0, Uud32acx will create a series of files containing the encoded data. The first file will have the extension .001, the second, .002, and so on, until all the binary data has been encoded.

4	Uud32acx supports four header styles: UUDeview (simple non-MIME headers); Simple MIME (“content-type,” etc.); MIME E-mail, and MIME News. Unless you are planning to undertake true MIME encoding, you should stick with the UUDeview header style. This style will work with nearly all decoders, and it won’t interfere with the normal operation of Internet mail programs or gateways.

5	If you want to see what the four header styles look like, just encode a test file with the four different settings.

MIME Encoding

Uud32acx can create MIME messages that are ready to send to the Internet mail or news systems, complete with the necessary MIME headers. To do this, you need to select Base64 as your encoding scheme, then select one of the MIME header styles, depending on your application.

0	There is a very important caveat to using Uud32acx to create MIME messages: the message header block. A true MIME message has information in its header block that tells the receiving mail or news program that the message is in MIME format. If you don’t place these signature lines in the header, the receiving program will ignore your MIME encoding and treat the encoded file as the message body.

1	It’s beyond the scope of this document to describe all the details of MIME encoding. For more information, consult the relevant RFCs (principally number 1521) on the Internet. Basically, if you use Uud32acx to encode a file for transmission to Internet mail or news, you need to copy the lines before the first blank line into the message header block, then put the rest of the encoded file into the message body.

2	For example, this Uud32acx call:

UD.Encode "c:\autoexec.bat", "h:\test.mim", _

0	"autoexec.bat", uudEncB64, 0, _

1	uudEncHMail, "example@foom.com", _

2	"uud@miken.com", "My Autoexec file"

produces a single output file called h:\test.mim that looks like this:

Subject: My Autoexec file (001/001) - [ autoexec.bat ]

0	From: uud@miken.com

1	To: example@foom.com

2	MIME-Version: 1.0

3	Content-Type: Application/Octet-Stream; name="autoexec.bat"

4	Content-Transfer-Encoding: Base64

5	QEVDSE8gT0ZGDQpHOlxQUk9HUkF+MVxOT1JUT05+MlxOQVZCT09ULkVYRSAvU1RBUlRVUA0KU0VU

6	IG1vdXNlPWc6XHdpbjk1XHN5c3RlbQ0KZzpcd2luOTVcc3lzdGVtXGdwb2ludC5jb20NClNFVCBN

7	U0lOUFVUPWc6XFdJTjk1DQpTRVQgVEVNUD1IOlxURU1QDQpTRVQgVE1QPUg6XFRFTVANCg==

As you can see, I used the optional destination, origin, and subject arguments to create a complete message that could be directly submitted to an Internet mail host via sendmail or SMTP. If you wanted to submit this message, you would need to ensure that the lines up to and including the Content-Transfer-Encoding description go into the message header block. The encoded data goes into the message body block. The techniques needed to ensure the proper destinations for these lines depend on the method you are using to submit to the mail or news system. You’ll need to consult the relevant documentation.

Just as an example, though, I will mention devSoft’s SMTP control. This is an ActiveX control that implements the SMTP protocol.

0	When sending a mail message with this control, you have the option of setting the OtherHeaders property to add lines to the message header block. In the above example, I would not have used the optional destination, origin, and subject arguments. This would mean that the encoded file would contain no “Subject,” “To,” or “From” lines.

1	To send this message with the devSoft SMTP control, I would have opened the text file h:\test.mim and copied lines from it into the OtherHeaders property until I hit a blank line. Then I would have copied lines into the message body property. This would ensure that the message carried the necessary MIME signature in the header block.

2	The details of these procedures are beyond the scope of this document; the information in this section is really only intended to give you an idea of the procedure.

3	 Back to Contents


Quick Decoding

The QuickDecode method is Uud32acx’s analog to a DOS command-line decoder. It’s designed to be the simplest possible way to decode an encoded binary file.

0	This method is really straightforward. All you need to do is supply the name of the file you want to decode and a directory where you want to send the results. Voilà.

1	For example, to decode a file called c:\poit\gotmail.uue and write whatever’s in there to a directory called c:\narf, you would do:

UD.QuickDecode "c:\poit\gotmail.uue", "c:\narf", False

That’s it. It’s really that simple.

The only disadvantage to using QuickDecode is that you can’t decode multiple files. All of the encoded information that you want to decode must be in a single input file. If you need to decode multiple input files, you must use the traditional DLoad and DFileTo methods.

0	See also:

•	Options Properties

 Back to Contents


X Files

My principal reason for building the Uud32acx ActiveX control was to provide decoding engine functionality for the 32-bit version of UUDeview. Accordingly, it contains a few functions that were useful for UUDeview but not directly related to decoding and encoding. The X Files series of functions is an example of this “extra” functionality.

0	The X File list holds a group of filenames that are to be deleted at some later time. Inside UUDeview, I use this list to keep track of files created by the “Decode and Launch” function.

1	Decode and Launch allows the UUDeview user to preview an encoded file. It decodes the selected files to the temporary directory and then launches the application that Windows “associates” with the file type in question. As a result, UUDeview leaves behind a number of files in the temporary directory. It’s not desirable to delete these files immediately, because they’re in use by the previewing applications.

2	The idea here is to delete these files at the end of the UUDeview session. The X Files list does just that. Any file added to the X Files list will be deleted either on command (the XFileDel method) or when the instance of the Uud32acx control is destroyed (if the XFileAuto flag is set).

3	You can add files to the X Files list with the XFileAdd method. The QuickDecode method can optionally add the files it creates to the X Files list (handy for the previewing application described above).

4	You can delete a file from the X Files list by setting its name to the empty string, like this:

UD.XFile(2) = ""

Note that this will change the indexes of all X Files above 2, so use this cautiously.

If you execute the Reset method, the X Files list will be cleared. If the XFileAuto property is True, the files on the list will be deleted before the list is cleared.

0	Important Note. You must use full path names on the X Files list.

1	The X Files functions are designed to be relatively tolerant. If a file on the list can’t be deleted, it will be skipped, but the function will only return an error indication if something serious happened. For example, if the file has already been deleted or is in use by another application, Uud32acx will move on to the next file.

2	P.S.	I’m perfectly aware that the name is tacky, but I couldn’t help myself.

3	 Back to Contents


Return Codes

Many Uud32acx methods return status codes to let you know how a particular operation went. This table lists these return codes:

ReturnCodes Constant	Value	Meaning
uudRetOK	0	Operation completed successfully.
uudRetIOErr	1	I/O Error, such as disk full or illegal filename. You can examine the GetLastError API function to find out what went wrong.
uudRetNoMem	2	Out of Memory.
uudRetIllVal	3	Illegal value or parameter.
uudRetNoData	4	Decoder did not find any data to process.
uudRetNoEnd	5	No proper ‘end’ marker was found in the encoded data.
uudRetUnsup	6	Unsupported encoding method.
uudRetExists	7	Output file exists (will only occur if Overwrite property is False).
uudRetCancel	9	Operation cancelled by user (the Cancel flag was set to True in the Progress event handler).
•	The constants listed in this table are exported by the Uud32acx control (in the ReturnCodes “enum”). In Visual Basic, you can retrieve them using the Object Browser (press <F2>, then choose library “Uud32acx”).

•	See also Constants.

 Back to Events

0	 Back to Methods

1	 Back to Properties

2	 Back to Contents


Constants

The Uud32acx control exports quite a large number of constants. These constants are designed to make it easier for you to use the control.

0	Every method or property that requires arbitrary numeric codes (e.g., the Header Styles parameter for the Encode method) has a corresponding table of exported constants. Below you’ll find a list of all the constant tables exported by the Uud32acx control.

C++ programmers

These constants are exported using the typedef enum capability of the ODL compiler. The constants are hence available from the Uud32acx type library built into the control.

VB programmers

You can access these constants using Visual Basic’s Object Browser. To open the Object Browser, press <F2>. A small window like this will open:

The example shows the user picking the uudFileDecoded constant from the DFileStatus constant set. Notice that a description of the constant appears at the bottom of the window. You can click the Help button or press <F1> to get more information on the highlighted constant set.

0	To copy the word uudFileDecoded to the clipboard, click the “Copy to Clipboard” button, which looks like this:

1	Once the constant’s name is on the clipboard, you can paste it into your application wherever it is needed. VB will load the corresponding numeric value from the control when it compiles your program. In the example, uudFileDecoded has been defined as 64, so wherever uudFileDecoded appears in your program, VB will substitute the constant integer 64.

2	Using these predefined constants instead of numbers will make your program more readable and protect you from future changes. If we are compelled for some reason to redefine the value of a constant, your program will still work as long as you used the text name. For example, uudFileDecoded is currently defined as 64, but if we change the value to 128 in some future release, your program will run fine as long as you use uudFileDecoded instead of 64.

Exported Constants

Here is a list of all the constant sets currently being exported by Uud32acx:

Constant Set	Usage
ClipFileOperations	Tells the ClipboardFile method what operation to perform.
DFileDetailItems	Defines the items that can be retrieved using the DFileDetail property.
DFileStatus	Defines the file status bits used by the DFileFlags and DFileDetail properties.
EncodeHeaders	Selects the header style for the Encode method.
EncodeModes	Selects the encoding scheme in the Encode method. Also used when checking the encoding scheme of a file using DFileDetail.
Messages	Defines the severity of messages received by the Messages event handler.
ProgressCodes	Defines the activity Uud32acx is performing when the Progress event handler is invoked.
 Back to Contents


Contacting the Authors

We welcome suggestions and comments on the Uud32acx control.

0	If you have a technical question, please take the time to read through this help file before writing for help. The authors provide support in their spare time, so any time spent answering questions that are already answered in the documentation is time that can’t be spent on making improvements.

1	For questions about the Uud32acx control itself and about developing applications with the control:

•	Michael Newcomb
E-mail: Michael Newcomb <uud@miken.com>
Web: www.miken.com/uud

For questions about encoding, decoding, and low-level engine functionality:

•	Frank Pilhofer
E-mail: Frank Pilhofer <fp@informatik.uni-frankfurt.de>
Web: http://www.uni-frankfurt.de/~fp/

 Back to Contents


Revision History

§	1.0 – Initial version

§	1.1 – July 2001

§	Added RemoveAfter property and StrictMIME property

§	Improved decoding engine

§	Added TempFolder property

§	1.2 – June 2001

§	Added StrictFilenames property

§	Improved decoding engine

§	Added support for yEnc encoding and decoding

§	Added Start, Length, and Count sub-file data to the DFileDetail so it’s possible to examine the encoded data in the source files directly.

§	Removed code that eliminated multiple dots in filenames

 Back to Contents


Properties

Here are the Uud32acx control’s properties:

 Pop up Property List

 Go to Events

 Go to Methods

 Back to Contents

Options

These flags control the way Uud32acx operates. Note that they affect the next Uud32acx operation.

Important Note. All of these options default to “False” or “Off” as appropriate.

BracketPolicy	Part numbers in brackets have precedence over part numbers in parentheses.
Desperate	Decode all available data, even if the file is incomplete or incorrectly formatted.
Dumb	Assume all parts are in the correct order.
FastMode	Tells the decoder to assume that each input file contains exactly one part of an encoded file.
IgnoreReply	Ignore files that show “RE:ply” posting.
OutputPath	Path string to be added to the name of every output file. Note that this must end with a trailing backslash.
Overwrite	Allow the decoding and encoding engines to overwrite existing files on disk.
RemoveAfter	Removes input files whose data was successfully extracted after the decode operation completes.
StrictFilenames	Tells the control to adhere strictly to the MIME standard for filename delimiters.
StrictMIME	Forces strict compliance with the MIME standard.
TempFolder	Controls where the UUDeview engine puts any temporary files it creates
UseText	Decode Plain Text and Quoted Printable file segments (MIME).
Verbose	Generate detailed progress and debugging messages.
XFileAuto	Delete files on the X Files list automatically when the Reset method is fired or just before the control is destroyed.
Decoding

These properties, which relate to decoding operations, appear only at run time.

DFCount	Count of encoded files found during loading.
DFile(row)	Get or set the name of a file found during loading.
DFileDetail(row,…)	Read detailed information about a particular file on the DFile list.
DFileFlags(row)	Get or set binary status bits for a file on the DFile list.
DFileInfo(row)	Read descriptive text (if any) found above the encoded data for a file on the DFile list.
DFileStatus(row)	Return an English string (e.g., “Ready to Decode,” “Missing Parts,” etc.) describing the status of a file on the DFile list.
X Files

These properties, which relate to X File list operations, appear only at run time.

XFile(row)	Get or set the name of a file on the X Files list. Can also be used to delete a file from the list.
XFileCount	Number of files on the X File list.
Other

These properties don’t fit any specific category.

LastMessage	The last error or informational message sent from the engine.
LibVersion	Current version of the UUDeview engine.


Bracket Policy Property

Boolean	Property	Design Time	Run Time	Read Only	Persistent
control.BracketPolicy = { True | False }

Multi-part postings on the newsgroups usually have subject lines like “You must see this! [1/3] (2/4).” Is this the second part of four in a series of three postings, or is it the first of three parts and the second in a series of four postings? The library cannot know, and simply gives numbers in parenthesis precedence over number in brackets. If this assumption fails, the parts will be grouped and ordered completely wrong.

Setting the bracket policy to True changes this precedence. If both parentheses and brackets are present, the numbers within brackets will be evaluated first.

 Back to Properties

 Back to Contents


Desperate Mode Property

Integer	Property	Design Time	Run Time	Read Only	Persistent
control.Desperate = { 0 | 1 | 2 }

By default, the library refuses to decode incomplete files and generates errors. But if switched into “desperate mode” these kinds of errors are ignored, and all available data is decoded. The usefulness of the resulting corrupt file depends on the type of the file.

Desperate mode comes in two flavors, desperate (1) and really desperate (2).

 Back to Properties

 Back to Contents


DFCount Property

Integer	Property	Design Time	Run Time	Read Only	Persistent
n = control.DFCount

After one or more DLoad operations, the DFCount property will tell you how many encoded files have been found. The “row” parameter used with decode properties and methods like DFile varies from 0 to DFCount.

 Back to Properties

 Back to Contents


DFile Property

String	Property	Design Time	Run Time	Read Only	Persistent
s = control.DFile(row)
control.DFile(row) = "string"

row	Integer	Index into list, from 0 to DFCount - 1.

Gets or sets the name of a file in the list of files found during the loading process. After one or more DLoad operations, the Uud32acx control will have built a list of the encoded files it found while scanning the input files. The names of those files are accessed through the DFile property.

This is the master list of files. Most programs that do decoding (at least those that don’t use QuickDecode) will be built around this list. The Decoding example shows how this property can be used.

Note that the names in the DFile list are unfiltered. They may contain characters that are not legal in Windows filenames and/or path information that might make it hard to write the files to disk. You can use the FileFilter method to remove unsafe characters.

Important Note: After a successful QuickDecode operation, the full path names of all decoded files can be retrieved through this property. The DFCount property reflects the total number of files successfully decoded. This is different from the normal behavior of the DFile property, which usually holds only the filenames retrieved from the original encoded data. Uud32acx does this so you can easily access the files it found during the QuickDecode operation.

 Back to Properties

 Back to Contents


DFileDetail Property

Variant	Property	Design Time	Run Time	Read Only	Persistent
v = control.DFileDetail(row, infoSelect, subIndex)

row	Integer	Index into list, from 0 to DFCount - 1.
infoSelect	Integer	Select item to retrieve (see table below)
subIndex	Integer	Index for arrays (see table)

Recommended for advanced users only. You do not need to use this property to successfully encode and decode files. It is provided for the needs of complex applications. Most developers will be able to get all the information they need using the DFileStatus and DFileFlags properties.

This property reads low-level information about a file in the DFile list. This document doesn’t attempt to explain in detail what all these parameters mean. If you are familiar with the original UUDeview library, these are members of the uulist and uufile structures.

Since the type of data returned by the property depends on the item chosen with the infoSelect parameter, DFileDetail returns a Variant. The valid infoSelect values are described in the DFileDetailItems table below.

DFileDetailItems Table

This table documents the items that can be retrieved using the DFileDetail property. The constants listed in this table are exported by the Uud32acx control (in the DFileDetailItems “enum”). In Visual Basic, you can retrieve them using the Object Browser (press <F2>, then choose library “Uud32acx”).

See also Constants.

DFileDetailItems Constant	Value	Structure member	Description
uudLDState	0	uulist.state	Describes the state of this file. Uses the DFileFlags constants.
uudLDMode	1	uulist.mode	For UU-encoded and XX-encoded files, this is the file mode found on the “begin” line. Base64 and BinHex files receive the default value of 0644.
uudLDBegin	2	uulist.begin	Part number where 'begin' was detected.
uudLDEnd	3	uulist.end	Part number where 'end' was detected.
uudLDUuDet	4	uulist.uudet	The encoding type. See the Encoding Modes table for an explanation of what these types mean.
uudLDFlags	5	uulist.flags	Status flags.
uudLDSize	6	uulist.size	The approximate size of the file when decoded. This is an estimated value and can be a few percent off the final value, so we suggest displaying the size in kilobytes only.
uudLDFileName	7	uulist.filename	The encoded filename. For UU-encoded and XX-encoded files, it is extracted from the “begin” line. The name of BinHex files is encoded in the first few data bytes. Base64 (MIME) files have the filename given in the “Content-Type” header. This field may be empty if the file is not complete.
uudLDSubF	8	uulist.subfname	A unique identifier for this group of encoded parts usually derived from the “Subject” header of each part. It is possible that two nodes with the same identifier exist in the file list: if a group of files is considered “complete,” a new node is opened up for more parts with the same ID.
uudLDMIMEID	9	uulist.mimeid	Stores the "id" field from the "Content-Type" information if available. Actually, this ID is the first choice for grouping of files. Non-MIME files do not have this information.
uudLDMIMEType	10	uulist.mimetype	Stores this part's "Content-Type" if available.
uudLDBinFile	11	uulist.binfile	After decoding, this is the name of the temporary file the data was decoded to and stored in. This will be empty during normal Uud32acx operation.
uudLDHavePart	12	uulist.haveparts[subIndex]	The part numbers found for this group of files as a zero-terminated ordered integer array. Some extra care must be taken, because a file may have a “zeroth” part as its first part. Thus if haveparts[0] is zero, it indicates a zeroth part, and the list of parts continues. A file may have at most one zeroth part, so if both haveparts[0] and haveparts[1] are zero, the zeroth part is the only part of this file.  No more than 256 parts are listed here.
uudLDMissPart	13	uulist.msparts[subIndex]	Similar to haveparts; a zero-terminated ordered integer array of missing parts, or simply 0 if no parts are missing. Since we don't mind if a file doesn't have a zeroth part, this array does not have the above problems.
uudLDUFPart	14	uulist.thisfile[subIndex] .partno	List of parts in this file
uudLDUFrSubj	15	uulist.thisfile[subIndex] .data.subject	Subject: line of component file
uudLDUFrOrg	16	uulist.thisfile[subIndex] .data.origin	From: line of component file
uudLDUFrSFN	17	uulist.thisfile[subIndex] .data.sfname	Filename from component file
UudLDUFrStart	18	uulist.thisfile[subIndex] .data	Starting position (offset into source file) of encoded data in component file
UudLDUFrLength	19	uulist.thisfile[subIndex] .data	Length of the encoded data in the source file.
UudLDUFrCount	20	uulist.thisfile[subIndex] .data	Number of “subIndex” entries that make up this file.
 Back to Properties

 Back to Contents


DFileFlags Property

Integer	Property	Design Time	Run Time	Read Only	Persistent
n = control.DFileFlags(row)
control.DFileFlags(row) = Flags

row	Integer	Index into list, from 0 to DFCount - 1.

Gets or status flags for a member of the DFile list. The actual flags are described in the DFileStatus table below.

You can test flags using your language’s “And” function, like this:

If UD.DFileFlags(row) And uudFileOK Then

MsgBox "File " + UD.DFile(row) + " is ready to decode.", _

vbOKOnly, "DFileFlags"

End If

Though the DFileFlags property lets you set a file’s flags, you should do so with caution. If you change the flags to an inappropriate value, the Uud32acx control may malfunction. When setting a new value, you can combine flags with your language’s “Or” operator, like this:

UD.DFileFlags(row) = uudFileOK Or uudFileDecoded

DFileStatus Constants

The constants listed in this table are exported by the Uud32acx control (in the DFileStatus “enum”). In Visual Basic, you can retrieve them using the Object Browser (press <F2>, then choose library “Uud32acx”).

DfileStatus Constant	Value	Description
UudFileRead	0	Read in, but not further processed.
UudFileMisPart	1	Missing Parts detected.
uudFileNoBegin	2	No 'begin' found.
uudFileNoEnd	4	No 'end' found.
uudFileNoData	8	File does not contain valid data.
uudFileOK	16	All parts found, ready to decode.
uudFileError	32	Error while decoding.
uudFileDecoded	64	Successfully decoded.
uudFileTmpFile	128	Temporary decoded file exists.
The constants listed in this table are exported by the Uud32acx control (in the DFileStatus “enum”). In Visual Basic, you can retrieve them using the Object Browser (press <F2>, then choose library “Uud32acx”).

See also Constants.

 Back to Properties

 Back to Contents


DFileInfo Property

String	Property	Design Time	Run Time	Read Only	Persistent
s = control.DFileInfo(row)

row	Integer	Index into list, from 0 to DFCount - 1.

Some encoded files contain text descriptions ahead of the encoded data. Often this is a description of the file’s contents, a note from the sender, or something else along those lines.

The DFileInfo property allows you to retrieve this information for files that have it. If an encoded file includes descriptive information, you can read it directly by reading the DFileInfo property. If a file has no descriptive information, DFileInfo will return the empty string.

For example:

Debug.Print "File " + UD.DFile(0) + ":"

Debug.Print UD.DFileInfo(0)

This sample would print the descriptive information for the first file in the DFile list.

 Back to Properties

 Back to Contents


DFileStatus Property

String	Property	Design Time	Run Time	Read Only	Persistent
s = control.DFileStatus(row)

row	Integer	Index into list, from 0 to DFCount - 1.

The DFileStatus property provides a simple way to get an English description of an encoded file’s status. For example, the command:

s = UD.DFileStatus(0)

might set the string “s” to something like:

Mime-Base64 Encoded, Ready to Decode; From: f1.uue+f2.uue

You can use the DFileStatus to get information for any file in the DFile list.

 Back to Properties

 Back to Contents


Dumb Mode Property

Boolean	Property	Design Time	Run Time	Read Only	Persistent
control.Dumb = { True | False }

To determine the part number of a file, the library evaluates information found in the part's "Subject" header line if available. The heuristics here are versatile, but cannot be guaranteed to be completely failure-proof. If Uud32acx guesses the wrong part number, the parts will be ordered and grouped wrong, resulting in incorrect decoding.

If “dumb mode” is set, the code to derive part numbers is disabled. Uud32acx will assume that all parts within a group appear in correct order. The first file is assigned number 1, and so on. However, part numbers found in MIME headers are still used (I haven't yet found a file where these were wrong). The filename is found in the first part and then passed on to the following parts.

 Back to Properties

 Back to Contents


Fast Mode Property

Boolean	Property	Design Time	Run Time	Read Only	Persistent
control.FastMode = { True | False }

If Fast mode is set, the control will assume that each input file consists of exactly one e-mail message or newsgroup posting. After finding encoded data within a file, the scanner will not continue to look for more data below. This strategy can save a lot of time but has the drawback that files also cannot be checked for completeness: since the scanner does not look for "end" lines, it won’t notice if they’re missing.

This flag does not have any effect on MIME multi-part messages, which are always scanned to the end (alas, the Epilogue will be skipped). Actually, with this flag set, the scanner becomes more MIME-compliant.

 Back to Properties

 Back to Contents


Ignore Reply Property

Boolean	Property	Design Time	Run Time	Read Only	Persistent
control.IgnoreReply = { True | False }

If set, the Uud32acx control will ignore e-mail messages and news postings which were sent as "Reply," since they are less likely to feature useful data. There's no real reason to turn on this option any more (earlier versions of the UUDeview engine got easily confused by replies).

 Back to Properties

 Back to Contents


Last Message Property

String	Property	Design Time	Run Time	Read Only	Persistent
s = control.LastMessage
control.LastMessage = "string"

When you invoke the Uud32acx control’s methods, the control may send you messages. These messages can describe error conditions or provide general status information.

You can retrieve these messages in two ways, either by using the LastMessage property or by installing a handler for the control’s Message event. The control keeps the last message even if a message event handler is installed.

The disadvantage to using the LastMessage property is, obviously, that you can only retrieve the last message sent by the control. If more than one message has been sent between the times that you check the LastMessage property, the intervening messages will be lost.

You can also set the LastMessage property, for example to communicate your program’s own error or status information from a subroutine to the main code. The most common use for this facility is probably to clear the LastMessage property in the event you’ve handled an error.

Note that setting the LastMessage property does not fire the Message event. Indeed, setting this property has no real effect on the control beyond (obviously) changing the property itself.

 Back to Properties

 Back to Contents


Library Version Property

String	Property	Design Time	Run Time	Read Only	Persistent
s = control.LibVersion

This property returns the current version and date stamp of the Uud32acx control. The version string looks something like this:

0.5pl13 Wed Apr  9 15:49:14 1997

This means that the UUDeview engine revision level is “0.5pl13” and the Uud32acx control’s date stamp is April 9, 1997, at 15:49.

 Back to Properties

 Back to Contents


Output Path Property

String	Property	Design Time	Run Time	Read Only	Persistent
control.OutputPath = "string"

This property allows you to set a path string that will be prepended to the file name of every file written by the Uud32acx control. Note that the control doesn’t examine this string; it must be correctly formatted to be put in front of a file name. For example, under Windows, you’ll probably want the OutputPath string to end with a backslash.

This is actually a fairly primitive mechanism. Instead of using the OutputPath property, it’s probably simpler to just add your desired output path to the arguments of methods like DFileTo.

 Back to Properties

 Back to Contents


Overwrite Property

Boolean	Property	Design Time	Run Time	Read Only	Persistent
control.Overwrite = { True | False }

This property determines whether or not Uud32acx can overwrite files. If the Overwrite property is False, the control will send back a return code of uudRetExists (see Return Codes) any time it wants to write over an existing file.

Important Note. This property defaults to False, so Uud32acx will not overwrite files unless you set the property to True.

 Back to Properties

 Back to Contents


RemoveAfter Property

Boolean	Property	Design Time	Run Time	Read Only	Persistent
control.RemoveAfter = { True | False }

This property is extremely dangerous, use with caution! If it is True, the UUDeview control will PERMANENTLY DELETE any file it "consumes" during the decoding process. Files that contain data that was not retrieved will not be deleted.

If you wish to delete files after a decoding operation, it is strongly recommended that you write this functionality into your code rather than using this property, which is provided simply because the underlying engine supports it.

Defaults to False.

 Back to Properties

 Back to Contents


StrictFilenames Property

Boolean	Property	Design Time	Run Time	Read Only	Persistent
control.StrictFilenames = { True | False }

Tells the control to adhere strictly to the MIME standard for filename delimiters. In particular, with this flag set, the control will expect filenames that contain “unusual” characters (such as spaces or other non-alphanumerics) to be enclosed in quotation marks.

A growing number of mail and news posting tools, especially viruses like Klez, do not follow the MIME standard when generating filenames, which can cause the control to retrieve the wrong filename.

By default, the StrictFilenames flag is not set, which causes the control to accept only a semicolon or the end of line as a delimiter for filenames in MIME documents. This will retrieve the correct filename in the document most of the time, but it is very important to filter the resulting filename if you don’t use the QuickDecode method; you are much more likely to obtain bizarre characters that may not be supported by your computer’s file system.

 Back to Properties

 Back to Contents


StrictMIME Property

Boolean	Property	Design Time	Run Time	Read Only	Persistent
control.StrictMIME = { True | False }

Forces the control to strictly obey the MIME standard. Note that this will often reduce the amount of data retrieved since one of the UUDeview engine's specialties is dealing with malformed MIME files.

 Back to Properties

 Back to Contents


TempFolder Property

String	Property	Design Time	Run Time	Read Only	Persistent
control.TempFolder = "c:\temp2"

Determines where the control will create temporary files if it needs to. If this property is left blank (the default), the control will use the Windows temporary directory reported by the operating system.

 Back to Properties

 Back to Contents


UseText Property

Boolean	Property	Design Time	Run Time	Read Only	Persistent
control.UseText = { True | False }

Tells the Uud32acx control to extract “Plain Text” and “Quoted Printable” segments from MIME-format encoded files. These segments are normally ignored.

If UseText is True, text segments that are explicitly named will be written to the filenames supplied in the encoded file. Unnamed text segments will be given sequential names starting with 0001.txt. For typical e-mail messages, there will be at least one such segment, the “message body” that accompanies any encoded file.

This property defaults to False, which will be fine in most cases. You’ll only need to set the UseText property to True if you know there are plain text segments in your encoded file. Since the Plain Text and Quoted Printable modes are very rarely used for attached files, this shouldn’t happen often. Most encoders will “encode” files that are nominally “text” to Base64 in MIME mode.

 Back to Properties

 Back to Contents


Verbose Property

Boolean	Property	Design Time	Run Time	Read Only	Persistent
control.Verbose = { True | False }

The Verbose property tells the Uud32acx control to report detailed debugging information. This information can be useful if you’re having trouble decoding a file.

If you turn on the Verbose property, you’ll more or less be obligated to implement a handler for the Message event. During a typical decoding step in Verbose mode, the control will send back several messages per file. There’s no way to catch all of these messages with the LastMessage property, because your program will not get control back from Uud32acx until the current loading or decoding step has completed.

The messages sent back from Uud32acx in Verbose mode tend to be very cryptic. They’re really only intended to help advanced users debug the decoding process.

 Back to Properties

 Back to Contents


XFileAuto Property

Boolean	Property	Design Time	Run Time	Read Only	Persistent
control.XFileAuto = { True | False }

The X File list keeps track of a set of filenames that are to be deleted on command or when the Uud32acx control is destroyed. If the XFileAuto property is False (the default), the X File list will be deleted only when you invoke the XFileDel method.

If you set the XFileAuto method to True, the Uud32acx control will automatically delete the files on the X File list when the Reset method is invoked or when the control is destroyed (for example, when the form hosting it is unloaded). Note that once the delete operation is completed, the X File list will be emptied.

Important Note. For the X File list to do something useful, you must either invoke the XFileDel method or you must set XFileAuto to True. Otherwise, the X File list will never do anything.

 Back to Properties

 Back to Contents


XFile Property

String	Property	Design Time	Run Time	Read Only	Persistent
s = control.XFile(row)
control.XFile(row) = "filename"

row	Integer	Index into X File list, from 0 to XFileCount - 1.

Gets or sets the name of a file on the X File list. You can read the names of the files currently on the list by stepping through the list from 0 to XFileCount - 1. You can delete a file from the X File list by setting its name to the empty string, like this:

UD.XFile(2) = ""

Note that the indexes of all the filenames on the X File list after the item you delete will change if you delete an item from the list.

To add a filename to the X File list, use the XFileAdd method.

 Back to Properties

 Back to Contents


XFileCount Property

Integer	Property	Design Time	Run Time	Read Only	Persistent
n = control.XFileCount

Returns the number of files currently on the X File list. The “row” index used with properties like XFile varies from 0 to XFileCount - 1.

 Back to Properties

 Back to Contents


Property Return Type
This is the property's return type. It is also the type used to set new values for the property if that is allowed. Note: "Integer" means "16-bit Integer!"


Design Time Property
This property is available at design time.


Run Time Property
This property is available at runtime.


Persistent Property
The state of this property is stored with the control, so if you change it, the new value will be "remembered" each time that the control is loaded.


Read Only Property
This property only returns a value. You cannot assign a new value to it.


Property List

BracketPolicy

Desperate

DFCount

DFile(row)

DFileDetail(row,…)

DFileFlags(row)

DFileInfo(row)

DFileStatus(row)

Dumb

FastMode

IgnoreReply

LastMessage

LibVersion

OutputPath

Overwrite

RemoveAfter

StrictFilenames

StrictMIME

TempFolder

UseText

Verbose

XFile(row)

XFileAuto

XFileCount

See also:

Contents

Events

Methods

Return Codes


Methods

Here are Uud32acx’s methods:

 Pop up Method List.

 Go to Events

 Go to Properties

 Back to Contents

Decoding

These methods relate to decoding operations.

DFileTo(row,…)	Decode a particular file to a specific file name.
DLoad	Load and parse a file for later decoding.
DRemove(row)	Remove a file from the DFile list.
FileFilter	Remove unsafe characters from a filename.
QuickDecode	Automatically decode an input file and write the results to a specified directory.
Encoding

This method does Uud32acx’s encoding.

Encode	Encode a file.
X Files

These methods relate to the X Files list.

XFileAdd	Add a file to the X Files list.
XFileDel	Delete the files currently on the X Files list and empty the list.
Other

These methods don’t fit any specific category.

ClipboardFile	Transfer the Windows Clipboard to or from a file on disk.
CRC32	Calculate a file’s CRC32.
GetLastError	Return the last error reported to the operating system.
Reset	Restore the control to its original state, ready for another decoding session. If the XFileAuto flag is True, delete the files on the X Files list and empty the list. Does not change any currently selected Options Properties.


ClipboardFile Method

Boolean	Method
control.ClipboardFile hWnd, Filename, CFMode

hWnd	Long Integer	Owner window handle.
Filename	String	File to write to or from.
CFMode	Integer	Direction of transfer.

This method allows you to efficiently transfer the text contents of the Windows Clipboard to or from a disk file. This function only processes text!

The ClipboardFile method was originally added to Uud32acx so that UUDeview could decode the clipboard contents and encode to the clipboard. The method is exposed so other people can add the same kind of functionality to their programs if they so desire.

The hWnd parameter should be set to the window handle of your application’s main window. The filename parameter tells Uud32acx where to read or write the clipboard text. The CFMode constants are listed in the ClipFileOperations table below.

Returns True if the operation completed successfully, False otherwise. You use the GetLastError API function to retrieve information about what went wrong.

“Load Clipboard” copies the entire contents of a text file onto the clipboard. “Write Clipboard” writes the text content of the clipboard to a new file. If there is an existing file with the name specified in the method call, it will be overwritten.

“Append Clipboard” appends the current text content of the clipboard to the specified file; if the file doesn’t exist, it will be created.

ClipFileOperations Constants

These constants control what the ClipboardFile method does.

ClipFileOperations Constants	Value	Function
uudCFcff	0	Load Clipboard from file
uudCFc2nf	1	Write Clipboard to new file
uudCFac2f	2	Append Clipboard to file
•	The constants listed in this table are exported by the Uud32acx control (in the ClipFileOperations “enum”). In Visual Basic, you can retrieve them using the Object Browser (press <F2>, then choose library “Uud32acx”).

•	See also Constants.

 Back to Methods

0	 Back to Contents


CRC32 Method

Boolean	Method
control.CRC32 Filename, crc

Filename	String	File to examine.
crc	Long Integer	Calculated CRC [modified].

Calculates a file’s CRC32. This is a highly accurate checksum often used in data communications. If you know a transmitted file’s original CRC32 and length, you can calculate the same values for the received file. If the values are both equal, it is virtually certain that the file arrived successfully.

0	Returns True if the CRC was calculated successfully, False otherwise. If the function succeeded, the CRC32 will be returned in the crc parameter.

1	 Back to Methods

2	 Back to Contents


DFileTo Method

Integer	Method
control.DFileTo row, target

row	Integer	File to decode. Varies from 0 to DFCount - 1.
target	String	Path to write decoded file to.

This is the method that actually decodes files. The row parameter selects the file that will be decoded from the DFile list.

0	The target parameter tells Uud32acx where to write the decoded file. This should be a complete path and file name. You can build the target parameter from the DFile property, like this:

rc = UD.DFileTo(0, "c:\decode\" + UD.FileFilter(UD.DFile(0)))

This code snippet will decode the first file in the DFile list to the directory c:\decode\ and store the result return code in the variable rc. Passing the filename through the FileFilter method makes sure that no unsafe characters get written into the output filename.

•	The Message and Progress events will fire during processing if you have set up handlers for these events.

•	See also: Return Codes

 Back to Methods

0	 Back to Contents


DLoad Method

Integer	Method
control.DLoad efile

efile	String	File to load.

The DLoad method readies an encoded file for decoding by scanning it for encoded data. Unless you use the QuickDecode method, decoding files consists of two steps: loading the files with DLoad and decoding them with DFileTo.

0	Each time you load a file with DLoad, the DFile list and the DFCount property will be updated to reflect any new encoded files that have been found.

1	Returns an integer that describes how the operation went. See the Return Codes table for a description of what these integers mean.

•	The Message and Progress events will fire during processing if you have set up handlers for these events.

 Back to Methods

0	 Back to Contents


DRemove Method

(no return)	Method
control.DRemove row

row	Integer	File to remove. Varies from 0 to DFCount - 1.

Deletes a file from the DFile list. This does not delete any files, just the references to encoded files in the DFile list.

0	This method isn’t strictly necessary; you can just decide not to decode a file on the DFile list. Note that the “row” index of every file following the row that’s deleted will be changed.

1	 Back to Methods

2	 Back to Contents


Encode Method

Integer	Method
control.Encode inFile, outFile, nameInFile, encodeMode, _
linePerFile, Headers, DestAddr, FromAddr, Subject

inFile	String	File to encode.
outFile	String	File to write encoded data to.
nameInFile	String	Filename to write in encoded file.
encodeMode	Integer	Encoding scheme to use (see below).
linePerFile	Long Integer	Number of lines to write in each file (multipart).
Headers	Integer	Header style.
DestAddr	String	[Optional] Text for “To:” string.
FromAddr	String	[Optional] Text for “From:” string.
Subject	String	[Optional] Text for “Subject:” string

This one method provides all of Uud32acx’s encoding functionality. Depending on which parameters you set, you can use the Encode method to create a wide variety of different encoded files. To begin, you may want to look at the Encoding Example.

0	The inFile parameter selects the file to be encoded, and the outFile parameter tells Uud32acx where to write the encoded data. For single-part files, outFile is the filename that all the encoded data will be written to. For multi-part files (see below), outFile gives only the “base” filename; the extension will be an incrementing number. For example, if outFile were “c:\poit\narf,” and there was enough data to fill three files, the filenames would be c:\poit\narf.001, c:\poit\narf.002, and c:\poit\narf.003.

1	The nameInFile parameter allows you to tell Uud32acx what name to write into the output file(s). This is the name that will be used by the recipient’s decoding program. If you pass the empty string for nameInFile, Uud32acx will create the name by removing any path information from inFile. It’s generally not a good idea to include path information with nameInFile; the recipient will likely have a different directory structure (or even file system, if he isn’t running DOS/Windows) than you.

2	The encodeMode parameter selects the type of encoding to use, e.g., UU or Base64. See below for a list of the available modes.

3	The linePerFile argument controls multi-part encoding. If linePerFile is zero, Uud32acx will write all the encoded data to a single file with the name supplied in the outFile parameter. If linePerFile is not zero, Uud32acx will create a series of files, starting a new one every linePerFile lines. Each file will have a sequential number as its extension as described above.

4	Multi-part encoding is typically used in situations where the recipient’s system (or the succession of gateways between you and the recipient) cannot accept large files. This is rarely an issue on current systems, but the option is provided in case it’s needed.

5	The Headers argument determines what headers Uud32acx will generate for the output files. See the headers table below for details.

6	The DestAddr, FromAddr, and Subject parameters are optional. If they are supplied (and not the empty string), the relevant headers will be added to the output file(s), as long as some level of MIME headers are turned on (see below). For UUDeview-style headers, these parameters are always ignored and can be omitted.

7	Note for C++ developers. The optional parameters are internally declared as const VARIANT FAR&. They will be considered “omitted” unless the variant type is VT_BSTR. Remember that this is a reference, not a pointer.

•	The Message and Progress events will fire during processing if you have set up handlers for these events.

Encoding Modes

The Encode method uses these constants to select the encoding scheme:

EncodeModes Constants	Value	Function
uudEncUU	1	UU encoding (the most common and widely supported scheme).
uudEncB64	2	Base64 encoding. Used with MIME.
uudEncXX	3	XX encoding (rare).
uudEncBinHex	4	BinHex encoding (not yet supported for encoding).
uudEncPlainText	5	MIME Plain Text (not yet supported for encoding).
uudEncQuotedPrintable	6	MIME Quoted Printable (not yet supported for encoding).
UudEncyEnc	7	yEnc encoding
•	The constants listed in this table are exported by the Uud32acx control (in the EncodeModes “enum”). In Visual Basic, you can retrieve them using the Object Browser (press <F2>, then choose library “Uud32acx”).

•	See also Constants.

Header Styles

The Encode method’s header styles are selected using these constants:

Headers Constants	Value	Function
uudEncHUud	0	Standard UUDeview-style headers.
uudEncHSimple	1	Simple MIME headers (no addressing).
uudEncHMail	2	MIME E-mail headers.
uudEncHNews	3	MIME News headers.
•	The constants listed in this table are exported by the Uud32acx control (in the EncodeHeaders “enum”). In Visual Basic, you can retrieve them using the Object Browser (press <F2>, then choose library “Uud32acx”).

•	See also Constants.

All of the examples below are based on the following Encode method call. Only the Headers parameter was changed.

UC.Encode "c:\autoexec.bat", "h:\test.mim", "autoexec.bat", _

0	    uudEncB64, 0, (Headers), _

1	    "example@foom.com", "uud@miken.com", _

2	"My Autoexec file"

Header Examples: UUDeview Style

_=_

0	_=_ Part 001 of 001 of file autoexec.bat

1	_=_

2	QEVDSE8gT0ZGDQpHOlxQUk9HUkF+MVxOT1JUT05+MlxOQVZCT09ULkVYRSAvU1RBUlRVUA0KU0VU

3	IG1vdXNlPWc6XHdpbjk1XHN5c3RlbQ0KZzpcd2luOTVcc3lzdGVtXGdwb2ludC5jb20NClNFVCBN

4	U0lOUFVUPWc6XFdJTjk1DQpTRVQgVEVNUD1IOlxURU1QDQpTRVQgVE1QPUg6XFRFTVANCg==

Header Examples: Simple MIME Style

Content-Type: Application/Octet-Stream

0	Content-Transfer-Encoding: Base64

1	Content-Disposition: attachment; filename="autoexec.bat"

2	QEVDSE8gT0ZGDQpHOlxQUk9HUkF+MVxOT1JUT05+MlxOQVZCT09ULkVYRSAvU1RBUlRVUA0KU0VU

3	IG1vdXNlPWc6XHdpbjk1XHN5c3RlbQ0KZzpcd2luOTVcc3lzdGVtXGdwb2ludC5jb20NClNFVCBN

4	U0lOUFVUPWc6XFdJTjk1DQpTRVQgVEVNUD1IOlxURU1QDQpTRVQgVE1QPUg6XFRFTVANCg==

Header Examples: MIME E-mail Style

Subject: My Autoexec file (001/001) - [ autoexec.bat ]

0	From: uud@miken.com

1	To: example@foom.com

2	MIME-Version: 1.0

3	Content-Type: Application/Octet-Stream; name="autoexec.bat"

4	Content-Transfer-Encoding: Base64

5	QEVDSE8gT0ZGDQpHOlxQUk9HUkF+MVxOT1JUT05+MlxOQVZCT09ULkVYRSAvU1RBUlRVUA0KU0VU

6	IG1vdXNlPWc6XHdpbjk1XHN5c3RlbQ0KZzpcd2luOTVcc3lzdGVtXGdwb2ludC5jb20NClNFVCBN

7	U0lOUFVUPWc6XFdJTjk1DQpTRVQgVEVNUD1IOlxURU1QDQpTRVQgVE1QPUg6XFRFTVANCg==

Header Examples: MIME News Style

Subject: My Autoexec file (001/001) - [ autoexec.bat ]

0	From: uud@miken.com

1	Newsgroups: example@foom.com

2	MIME-Version: 1.0

3	Content-Type: Application/Octet-Stream; name="autoexec.bat"

4	Content-Transfer-Encoding: Base64

5	QEVDSE8gT0ZGDQpHOlxQUk9HUkF+MVxOT1JUT05+MlxOQVZCT09ULkVYRSAvU1RBUlRVUA0KU0VU

6	IG1vdXNlPWc6XHdpbjk1XHN5c3RlbQ0KZzpcd2luOTVcc3lzdGVtXGdwb2ludC5jb20NClNFVCBN

7	U0lOUFVUPWc6XFdJTjk1DQpTRVQgVEVNUD1IOlxURU1QDQpTRVQgVE1QPUg6XFRFTVANCg==

 Back to Methods

 Back to Contents


FileFilter Method

String	Method
S = control.FileFilter(inFile)

inFile	String	Filename to check.

This method scans a string for characters that might be “unsafe” in a DOS/Windows filename and converts them to underscores. It’s probably a good idea to run any filename you receive in an encoded file through this function before using it to name a file on disk.

0	Characters replaced by this method include: <, >, :, ", |, ?, *, ', \, and /. The method will also remove any control characters, such as tabs.

1	Note that the input string inFile will not be changed.

2	 Back to Methods

3	 Back to Contents


GetLastError Method

Boolean	Method
control.GetLastError eNumber, eString

eNumber	Long Integer	System error number [modified].
eString	String	String translation of error [modified].

This method is provided as a convenience, mostly for Visual Basic programmers. It queries the Windows GetLastError API and returns the error number, along with a string translation of the error.

0	If there was an error “waiting,” the method stores its number in the eNumber variable, translates the error code into the text string eString, and returns True. If no error was “waiting,” the method simply returns False.

1	Some Uud32acx errors can set GetLastError. However, this method is does not determine the source of the error; it merely queries the API and reports back. It’s beyond the scope of this document to explain the subtleties of the Windows error handling system. Consult the relevant API documentation to learn what the codes returned by this function mean.

2	 Back to Methods

3	 Back to Contents


QuickDecode Method

Integer	Method
control.QuickDecode inFile, outPath, XFile

inFile	String	File to decode.
outPath	String	Directory to receive decoded files.
XFile	Boolean	Add decoded filenames to X File list (default = False).

This method provides a quick and simple way to decode all the files in a single encoded input file. If you call the QuickDecode method, Uud32acx will immediately parse the specified inFile. Any decodable files found there will be written to the directory specified in the outPath parameter.

0	If the XFile parameter is True, Uud32acx will add the final path name of each file it decodes to the X File list for later automatic deletion. This may seem self-defeating: why delete files you’ve just decoded? Actually, UUDeview uses QuickDecode for its file preview operations, so it makes sense to delete the resulting files when UUDeview is closed.

1	Note: If you supply the empty string for the outPath parameter, Uud32acx will use the current Windows temporary file directory. It’s also worth noting that the Uud32acx control performs a Reset operation before beginning a QuickDecode.

2	Important Note: After a successful QuickDecode operation, the full path names of all decoded files can be retrieved through the DFile property. The DFCount property reflects the total number of files successfully decoded. This is different from the normal behavior of the DFile property, which usually holds only the filenames retrieved from the original encoded data. Uud32acx does this so you can easily access the files it found during the QuickDecode operation.

3	The QuickDecode method sends back an integer return code that describes how the operation went.

•	The Message and Progress events will fire during QuickDecode processing if you have set up handlers for these events.

 Back to Methods

 Back to Contents


Reset Method

(no return)	Method
control.Reset

This method returns the control to its initial state. The DFile and X File lists are cleared. If the XFileAuto property is True, the control will try to delete all files on the X File list before emptying it.

You should always perform a Reset call before beginning a new decoding cycle.

 Back to Methods

 Back to Contents


XFileAdd Method

Boolean	Method
control.XFileAdd Filename

Filename	String	File to delete later.

This method adds the indicated file to the X File list. Uud32acx will try to delete all the files on this list when you call the XFileDel method. If the XFileAuto property is True, the control will also try to delete these files when the Reset method is called or when the control instance is destroyed (e.g., the form it lives on is unloaded).

The method returns True if the add operation succeeded or False otherwise. This method should succeed in virtually all circumstances except extreme low memory.

 Back to Methods

 Back to Contents


XFileDel Method

Boolean	Method
control.XFileDel

Explicitly tells the Uud32acx control to delete the files on the X File list. Returns True if the operation succeeded or False otherwise. If the method returns False, you can call the GetLastError API function to see what went wrong.

 Back to Methods

 Back to Contents


Return type
This is the return type of the method. Note that "Integer" means 16-bit Integer!


Uud32acx Methods

ClipboardFile

CRC32

DFileTo(row,…)

DLoad

DRemove(row)

Encode

FileFilter

GetLastError

QuickDecode

Reset

XFileAdd

XFileDel

See also:

Contents

Events

Properties

Return Codes


Events

Uud32acx currently supports only two events:

Message	Receives informational messages from the control.
Progress	Tracks progress through lengthy operations
 Go to Methods

 Go to Properties

 Back to Contents


Message Event

Event

Private Sub control_Message(Message As String, ByVal Level As Integer)

Message	String	Informational message.
Level	Integer	Severity of message

From time to time during loading, decoding, and encoding, Uud32acx will want to send you information about what’s going on. Unless the Verbose property is set to True, these messages will typically indicate errors or problems. The Level parameter will tell you how severe the error is (see below).

In a typical application, you might use a Message event handler to display these informational messages in a status area during lengthy operations.

If the Verbose property is True, you will get many more messages than usual, because Uud32acx will use the Message event handler to pass back debugging information. These messages tell you what the control is doing as it decodes or encodes your files; this information can be especially useful to debug specific decoding problems.

Note for VB programmers: If you update controls on your form during the Message handler, you must remember to include a DoEvents statement in your handler. If you don’t, your changes will not appear until the operation has completed and control returns to the hosting application.

•	The most recent message from the control can always be retrieved using the LastMessage property.

Messages Constants

Messages Constant	Value	Meaning
uudMsgMessage	0	Just a message, nothing important
uudMsgNote	1	Something that should be noticed
uudMsgWarning	2	Important message, processing continues
uudMsgError	3	Processing has been terminated
uudMsgFatal	4	Decoder cannot process further requests
uudMsgPanic	5	Recovery impossible, app must terminate
•	The constants listed in this table are exported by the Uud32acx control (in the Messages “enum”). In Visual Basic, you can retrieve them using the Object Browser (press <F2>, then choose library “Uud32acx”).

•	See also Constants.

 Back to Events

 Back to Contents


Progress Event

Event

Private Sub control_Progress(ByVal CAction As Integer, _
    CFile As String, ByVal PartNo As Integer, _
    ByVal TotalParts As Integer, ByVal CFileSize As Long, _
    ByVal Percent As Integer, Cancel As Boolean)

CAction	Integer	What the control is currently doing (see below)
CFile	String	File currently being operated on
PartNo	Integer	Current part (for multi-part files)
CFileSize	Long Integer	Size of the current file
Percent	Integer	Percent currently completed
Cancel	Boolean	Cancel flag (see below)

This event is intended to help you show progress information to your users. It will be triggered periodically by the Uud32acx control during lengthy processing.

The CAction parameter tells you what the current activity is, and the other parameters tell you how far the operation in question has progressed. See the ProgressCodes table below for an explanation of the values you can expect.

If you want to cancel the current operation, you can set the Cancel variable to True during your Progress event handler. The control will abort the operation in progress and clean up as soon as possible.

ProgressCodes Table

Uud32acx uses these constants to tell you what’s going on:

ProgressCodes Constant	Value	Meaning
uudActIdle	0	Control is idle.
uudActScanning	1	Loading a file for decoding (DLoad or QuickDecode methods).
uudActDecoding	2	Decoding a file (DLoad or QuickDecode methods).
uudActCopying	3	Copying decoded file to target (not normally used).
uudActEncoding	4	Encoding a file (Encode method).
uudActNewStep	9	Starting new step
•	The constants listed in this table are exported by the Uud32acx control (in the ProgressCodes “enum”). In Visual Basic, you can retrieve them using the Object Browser (press <F2>, then choose library “Uud32acx”).

•	See also Constants.

The uudActNewStep code is used to signify that a new procedure is just starting. For example, it fires just before a file is loaded with DLoad and as the QuickDecode method starts decoding each file it has found. Typically, you might use this event to tell your handler that the next event will have a new file name and new total number of parts.

Note for VB programmers: If you update controls on your form during the Progress handler, you must remember to include a DoEvents statement in your handler. If you don’t, your changes will not appear until the operation has completed and control returns to the hosting application.

 Back to Events

 Back to Contents