Copyright: Copyright ©2001 Xceed Software Inc.


Features of the Xceed Zip Compression Library
Features of the Xceed Binary Encoding Library v1.0

ActiveX technology

•	A single fully self-contained COM object and ActiveX control written with ATL 3.0.

•	Requires no external DLLs, ATL, MFC or runtime libraries.

•	Both single-threaded (STA) and multi-threaded apartment (MTA) model design.

•	Instantiate the component dynamically without putting it on a form.

•	Supports multiple instances running simultaneously.

•	When running on Windows NT, 2000 or XP, the library automatically switches to native Unicode API calls for best performance.

•	ActiveX control interface has all constants, enumerations and types built-in. Code completion, property categories, help strings and context-sensitive F1-help fully supported.

•	Works with all 32-bit development environments that can use ActiveX controls, including VB, VC++, Delphi, C++ Builder, VFP, Office, Web scripting languages, ASP and DCOM projects.

Encoding and decoding

•	Fast, low memory usage algorithms.

•	Supports a variety of encoding and decoding types: UUEncode, XXEncode, Base64, Binhex, Quoted-Printable and plain Hexadecimal.

•	Encode and decode directly from one memory buffer to another.

•	Encode and decode from file to memory or from memory to file.

•	Encode and decode from one file to another.

•	All encoding and decoding modes support streaming data.

•	Compliant with RFC-2045, RFC-1741 and RFC-2045.

•	Can efficiently and automatically work together with the Xceed Streaming Compression Library and the Xceed Encryption Library to compress, decompress, encrypt or decrypt data before encoding or decoding it.

Documentation and samples

•	The complete documentation is available both as a printable MS Word document as well as a fully context-sensitive Windows .hlp file that is automatically opened to the right topic by pressing F1 on a keyword in your programming language.

•	Fully commented sample applications for various languages, including VB, Delphi, Visual C++ with ATL and MFC, C++ Builder and Active Server Pages.


About the free trial version

The free trial version of the Xceed Binary Encoding Library v1.0 includes everything the registered version does, except the license to distribute applications you create that use the library. That means you get the complete documentation, code examples, sample applications with fully commented source code and free technical support by email or telephone.

The free trial version is intended to allow you to design, code and test applications that use the Xceed Binary Encoding Library for 20 days. The 20-day trial period begins when you first install the library on your development system. After the trial period ends, any calls made to the library's methods will return a licensing error code.

Only registered users are permitted to distribute applications that use the library outside their test or development environments.

When you decide that you like the Xceed Binary Encoding Library and will use it in your projects, all you have to do after purchasing a registered copy of the product is to unlock your free trial version and recompile your application(s).

If you are instantiating the component dynamically, and are not using it from a form, you may need to call the License method in order to access the library. This applies to both free trial version users as well as registered.


Compressing and decompressing entirely in memory
Encoding and decoding entirely in memory

VB example   VC++ example  Delphi example

In the descriptions below, you can freely replace the word "encode" with "decode" in order to find out how to decode data, because encoding and decoding work exactly the same way.

Basic (non-streaming) encoding in memory

To encode data entirely in memory, from one memory buffer to another in a single pass, perform the following 4 steps. Put the Xceed Binary Encoding control on a form or instantiate it, then:

•	Specify the format for the resulting encoded data. To do this, set the EncodingFormat property.

•	Tell the library to encode. To do this, call the Encode method, passing your source memory buffer and specifying True for the bEndOfData parameter.

•	Obtain the encoded data. To do this, assign the return value of the Encode method to the variable of your choice.

•	Make sure that everything worked properly. To do this, use your language's error handling object or error handling capabilities. The Xceed Binary Encoding Library supports standard COM error handling functionality.

Streaming encoding

To encode data entirely in memory while providing the library with data to encode as it becomes available, perform the following 5 steps. Put the Xceed Binary Encoding Control on a form or instantiate it, then:

•	Specify the format for the resulting encoded data. To do this, set the EncodingFormat property.

•	Provide each block of data to the library as it becomes available. To do this, call the Encode method for each portion of data, passing the memory buffer with a portion of the data and specifying False for the bEndOfData parameter.

•	Accumulate the encoded data. To do this, append the data returned by the Encode method to a variable which contains the complete encoded memory buffer so far. You can also process the encoded data as it is returned by the library or pass it to other streaming methods.

•	Continue providing blocks of data to encode until you're done. When there is no more data to encode, call the Encode method with a final (or empty) block of data to encode and specify True for the bEndOfData parameter. Be sure to assign the Encode method's final returned encoded data to your accumulation variable or process it or pass it to other streaming methods.

•	Make sure that everything worked properly. To do this, use your language's error handling object or error handling capabilities. The Xceed Binary Encoding Library supports standard COM error handling functionality.


Installation instructions for Visual Basic 5.0

The Xceed Component Installer will copy all the necessary files into the library's installation folder (usually in \PROGRAM FILES\XCEED COMPONENTS\) and register the XCEEDBEN.DLL ActiveX / COM component in the BIN subfolder. The only thing left to do is to make the control available to your VB 5.0 projects. To do this, perform the following steps:

•	Start Visual Basic 5.0.

•	Create a new project or open an existing one.

•	Select Components… from the Project menu.

•	An entry named "Xceed Binary Encoding Library v1.0" entry should appear in the components list.

•	In the Components dialog, make sure the "Xceed Binary Encoding Library v1.0" entry is checked in the components list. This will make it available for use in your applications.

•	Click the OK button. The Xceed Binary Encoding control icon should now appear in the components toolbox.

If the control is not in the components list, perform the following steps:

•	Try reinstalling the Xceed Binary Encoding Library from its installation program. Continue only if that didn't help.

•	Click the Browse… button.

•	Find and select the XCEEDBEN.DLL file (use the one in the Windows System folder that was copied there by the installation program) then click on the OK button.

•	The "Xceed Binary Encoding Library v1.0" entry should now appear in the components list.


Installation instructions for Visual Basic 6.0

The Xceed Component Installer will copy all the necessary files into the library's installation folder (usually in \PROGRAM FILES\XCEED COMPONENTS\) and register the XCEEDBEN.DLL ActiveX / COM component in the BIN subfolder. The only thing left to do is to make the control available to your VB 6.0 projects. To do this, perform the following steps:

•	Start Visual Basic 6.0.

•	Create a new project or open an existing one.

•	Select Components… from the Project menu.

•	An entry named "Xceed Binary Encoding Library v1.0" entry should appear in the components list.

•	In the Components dialog, make sure the "Xceed Binary Encoding Library v1.0" entry is checked in the components list. This will make it available for use in your applications.

•	Click the OK button. The Xceed Binary Encoding control icon should now appear in the components toolbox.

If the control is not in the components list, perform the following steps:

•	Try reinstalling the Xceed Binary Encoding Library from its installation program. Continue only if that didn't help.

•	Click the Browse… button.

•	Click on All files in the Files of type tab

•	Find and select the XCEEDBEN.DLL file (use the one in the Windows System folder that was copied there by the installation program) then click on the OK button.

The "Xceed Binary Encoding Library v1.0" entry should now appear in the components list.


Installation instructions for Visual C++ 6.0
Installation instructions for Visual C++ 6.0 (MFC projects)

The Xceed Component Installer will copy all the necessary files into the library's installation folder (usually in \PROGRAM FILES\XCEED COMPONENTS\) and register the XCEEDBEN.DLL ActiveX / COM component in the BIN subfolder. The only thing left to do is to make the control available to your VC++ 6.0 projects. To do this, perform the following steps:

•	Start Microsoft Visual C++ 6.0

•	Open your MFC AppWizard application project, or create a new one by selecting the New... menu item from the File menu, then selecting the Projects tab and choosing the MFC AppWizard item. Follow the Wizards instructions to create the project. Be sure that you select the ActiveX Controls option for the question "What other support would you like to include?"

Next, if you want to drop the Xceed Binary Encoding control on a dialog, do this:

•	Select the Project menu

•	Select the Add to project submenu, then select Components and Controls...

•	In the Components and Controls Gallery dialog, look in the Registered ActiveX Controls folder for the "Xceed Binary Encoding Library v1.0", then select it and click on the Insert button.

•	Select the OK in response to the "Insert this component?" message box. The Confirm Classes dialog should appear.

•	Click OK to close the Confirm Classes dialog.

•	Click the Close button to close the Components and Controls Gallery dialog.

•	The XCEEDBEN.CPP and XCEEDBEN.H files should now be part of your project. You will now be able to instantiate the Xceed Binary Encoding object in your project, and see the Xceed Binary Encoding control icon available in your Controls toolbar when designing dialog boxes.

Or, if you want to use create an instance of the controls without requiring a CWnd parent, do this:

•	Open the ClassWizard.

•	Click the "Add Class" button and select the "From a type library" option.

•	Find and select the "XCEEDBEN.DLL" file. Even if your Visual C++ does not display files ending by "DLL", you can select "All files (*.*)" as the type of files, and then select the "XCEEDBEN.DLL" file.

•	Select the "IXceedBinaryEncoding" and "IXceedRawBinaryEncoding" interfaces. Visual Studio will generate two files: "XCEEDBEN.CPP" and "XCEEDBEN.H"

•	At the place you want to create your instance of XceedBinaryEncoding or XceedRawBinaryEncoding, include the "XCEEDBEN.H" file and create a variable of type "IXceedBinaryEncoding" and "IXceedRawBinaryEncoding", and call the "CreateDispatch" method on this variable to actually create the instance behind the wrapper object.

•	Finally, when you are finished with your instance, make sure to call the "ReleaseDispatch" method on it.


Installation instructions for Word 97 abd Excel 97
Installation instructions for Word 97 and Excel 97

The Xceed Component Installer will copy all the necessary files into the library's installation folder (usually in \PROGRAM FILES\XCEED COMPONENTS\) and register the XCEEDBEN.DLL ActiveX / COM component in the BIN subfolder. The only thing left to do is to make the control available to your Word 97 projects. To do this, perform the following steps:

•	Start Word 97 or Excel 97.

•	Select the Visual Basic Editor option from the Macro submenu in the Tools menu or use the Alt+F11 shortcut.

•	In the Microsoft Visual Basic window, select the References… option from the Tools Menu.

•	Make sure the "Xceed Binary Encoding Library v1.0" entry is checked and then click on the OK button.

•	In the Microsoft Visual Basic window, select the UserForm option from the Insert menu.

•	If the Toolbox window is not visible, select the ToolBox option from the View menu.

•	Select the Additional Controls… option from the Tools menu.

•	In the Additional Controls dialog, make sure "Xceed Binary Encoding Library v1.0" is checked in the Available Controls list.

•	Click the OK button.

If there is no entry for Xceed Binary Encoding Library in the references dialog's list of available references:

•	Try reinstalling the Xceed Binary Encoding Library from its installation program. Continue only if that didn't help.

•	Try reinstalling the Xceed Binary Encoding Library from its installation program. Continue only if that didn't help.

•	In the References dialog, click the Browse... button.

•	Find and select the XCEEDBEN.DLL file (preferably the one in Windows System which was placed there by the Xceed Binary Encoding Library installation program), then click on the Open button.

•	The "Xceed Binary Encoding Library v1.0" entry should now appear in the Available References listing in the References dialog.


Installation instructions for Visual FoxPro 5.0
Installation instructions for Visual FoxPro 5.0 and 6.0

The Xceed Component Installer will copy all the necessary files into the library's installation folder (usually in \PROGRAM FILES\XCEED COMPONENTS\) and register the XCEEDBEN.DLL ActiveX / COM component in the BIN subfolder. The only thing left to do is to make the control available to your VFP 5.0 and 6.0 projects. To do this, perform the following steps:

•	Start Visual FoxPro 5.0 or 6.0

•	Select Options... from the Tools menu.

•	Select the Controls tab from the Options dialog.

•	Select the ActiveX controls checkbox.

•	The Xceed Binary Encoding control should appear in the "selected:" listbox (still in the Controls tab of the Options dialog)

•	Now, to make the control available to your Visual FoxPro 5.0 projects, make sure the checkbox next to the "Xceed Binary Encoding Library v1.0" entry is selected. Click on the OK button and the Xceed Binary Encoding control icon should now appear in the list of controls you can insert - for example, when using the OLE Container Object on a form.

If the entry for the Xceed Binary Encoding Library does not appear in the list of controls:

•	Try reinstalling the Xceed Binary Encoding Library from its installation program. Continue only if that didn't help.

•	Select the Add... button from the Controls tab of the Options dialog.

•	Find and select the XCEEDBEN.DLL file (preferably the one in the Windows System folder that was placed there by the Xceed Binary Encoding Library installation program), then click on the OK button.

•	The control's entry should now appear in the list.


Installation instructions for Access 97

The Xceed Component Installer will copy all the necessary files into the library's installation folder (usually in \PROGRAM FILES\XCEED COMPONENTS\) and register the XCEEDBEN.DLL ActiveX / COM component in the BIN subfolder. The only thing left to do is to make the control available to your Access 97 projects. To do this, perform the following steps:

•	Start Access 97.

•	Select the ActiveX Controls… option from the Tools menu

•	The "Xceed Binary Encoding Library v1.0" entry should appear in the Available Controls list of the ActiveX Controls dialog.

•	Click the Close button.

If the Xceed Binary Encoding Library entry does not appear in the list:

•	Try reinstalling the Xceed Binary Encoding Library from its setup program. Continue only if that didn't help.

•	In the ActiveX Controls dialog, click the Register... button.

•	Find and select the XCEEDBEN.DLL file (use the one in the Windows System folder that was copied there by the installation program) then click on the Open button.

•	The Xceed Binary Encoding control should now be available the "Available Controls" list.


Installation instructions for Delphi 3.0

The Xceed Component Installer will copy all the necessary files into the library's installation folder (usually in \PROGRAM FILES\XCEED COMPONENTS\) and register the XCEEDBEN.DLL ActiveX / COM component in the BIN subfolder. The only thing left to do is to make the control available in your Delphi 3.0 environment by inserting the control into the toolbar. To do this, perform the following steps:

•	Start Delphi 3.0 (Delphi 3.0 Maintenance Release 2 or newer is recommended)

•	Open an existing project or create a new project

•	From the Component menu, select the Import ActiveX control item

•	Select the "Xceed Binary Encoding Library v1.0" item from the list of installed ActiveX controls (if the component is not there, we recommend that you reinstall the library on your machine instead of choosing the Add button and selecting the XCEEDBEN.DLL control from the Windows System directory)

•	Click on the Install button that's on the Import ActiveX dialog

•	The Install dialog will appear. Click on the "Into new package" tab.

•	Enter a filename and path for the new package in the "File Name" field. It should be a ".DPK" file, and you'll probably want to put it with your other package files in your Delphi installation folder.

•	Click OK in the Install dialog

•	Delphi will then ask you to confirm the rebuild – click Yes in the Confirm dialog.

•	If everything was successful, you should get a message that the package has been updated and that the new components have been registered.

•	Close the package dialog

•	Click Yes when you are prompted to confirm the changes.

You have now successfully installed the Xceed Binary Encoding Library v1.0 ActiveX control in Delphi 3. The components should appear in your component toolbar (ActiveX or Xceed tabs).


Installation instructions for Delphi 4.0
Installation instructions for Delphi 4.0 and 5.0

The Xceed Component Installer will copy all the necessary files into the library's installation folder (usually in \PROGRAM FILES\XCEED COMPONENTS\) and register the XCEEDBEN.DLL ActiveX / COM component in the BIN subfolder. The only thing left to do is to make the control available in your Delphi 4.0 or 5.0 environment by inserting the control into the toolbar. To do this, perform the following steps:

•	Start Delphi 4.0 or Delphi 5.0 (For Delphi 4.0, Update Release 3 or newer is recommended)

•	Open an existing project or create a new project

•	From the Component menu, select the Import ActiveX control item

•	Select the "Xceed Binary Encoding Library v1.0" item from the list of installed ActiveX controls (if the component is not there, we recommend that you reinstall the library on your machine instead of choosing the Add button and selecting the XCEEDBEN.DLL control from the Windows System directory)

•	Click on the Install button that's on the Import ActiveX dialog

•	The Install dialog will appear. Click on the "Into new package" tab.

•	Enter a filename and path for the new package in the "File Name" field. It should be a ".DPK" file, and you'll probably want to put it with your other package files in your Delphi installation folder.

•	Click OK in the Install dialog

•	Delphi will then ask you to confirm the rebuild – click Yes in the Confirm dialog.

•	If everything was successful, you should get a message that the package has been updated and that the new components have been registered.

•	Close the package dialog

•	Click Yes when you are prompted to confirm the changes.

You have now successfully installed the Xceed Binary Encoding Library v1.0 ActiveX control in Delphi. The components should appear in your component toolbar (ActiveX tab).


Installation instructions for C++ Builder 3.0

The Xceed Component Installer will copy all the necessary files into the library's installation folder (usually in \PROGRAM FILES\XCEED COMPONENTS\) and register the XCEEDBEN.DLL ActiveX / COM component in the BIN subfolder. The only thing left to do is to make the control available in your C++ Builder 3.0 environment by inserting the control into the toolbar. To do this, perform the following steps:

•	Start C++ Builder 3.0

•	Open an existing project or create a new project

•	From the Component menu, select the Import ActiveX control item

•	Select the "Xceed Binary Encoding Library v1.0" item from the list of installed ActiveX controls (if the component is not there, we recommend that you reinstall the library on your machine instead of choosing the Add button and selecting the XCEEDBEN.DLL control from the Windows System directory)

•	Click on the Install button that's on the Import ActiveX dialog

•	The Install dialog will appear. Click on the "Into new package" tab.

•	Enter a filename and path for the new package in the "File Name" field. It should be a ".BPK" file, and you'll probably want to put it with your other package files in your C++ Builder installation folder

•	Click OK in the install dialog

•	If everything was successful, you should get a message that the package has been updated and that the new components have been registered.

•	Close the package dialog

•	Click Yes when you are prompted to confirm the changes.

The components should now appear in the ActiveX tab of your component toolbar.


Installation instructions for C++ Builder 4.0

The Xceed Component Installer will copy all the necessary files into the library's installation folder (usually in \PROGRAM FILES\XCEED COMPONENTS\) and register the XCEEDBEN.DLL ActiveX / COM component in the BIN subfolder. The only thing left to do is to make the control available in your C++ Builder 4.0 environment by inserting the control into the toolbar. To do this, perform the following steps:

•	Start C++ Builder 4.0

•	Open an existing project or create a new project

•	From the Component menu, select the Import ActiveX control item

•	Select the "Xceed Binary Encoding Library v1.0" item from the list of installed ActiveX controls (if the component is not there, we recommend that you reinstall the library on your machine instead of choosing the Add button and selecting the XCEEDBEN.DLL control from the Windows System directory)

•	Click on the Install button that's on the Import ActiveX dialog

•	The Install dialog will appear. Click on the "Into new package" tab.

•	Enter a filename and path for the new package in the "File Name" field. It should be a ".BPK" file, and you'll probably want to put it with your other package files in your C++ Builder installation folder

•	Click OK in the install dialog

•	If everything was successful, you should get a message that the package has been updated and that the new components have been registered.

•	Close the package dialog

•	Click Yes when you are prompted to confirm the changes.

The components should now appear in the ActiveX tab of your component toolbar.


Installation instructions for other 32-bit development environments

The Xceed Component Installer will copy all the necessary files into the library's installation folder (usually in \PROGRAM FILES\XCEED COMPONENTS\) and register the XCEEDBEN.DLL ActiveX / COM component in the BIN subfolder. The Xceed Binary Encoding Library ActiveX control should be available in your development environment's list of available ActiveX controls. Your language should automatically "see" the component. If it does not, then you may need to manually register the control. Before doing this, though, we strongly suggest that you reinstall your copy of the Xceed Binary Encoding Library. This will ensure that it is licensed as well as being registered with the operating system. If that doesn't solve the problem, here's how to manually register the control:

•	From the Run option in the Windows "start" menu, or from a command prompt, run the following command to register an ActiveX control:

regsvr32 "path and filename of the xceedben.dll"

•	You will then see a message box that either displays "LoadLibrary failed" or displays "LoadLibrary succeeded". If you get the success message, then your ActiveX control is now registered on the machine and is ready for use by applications or in your development environment.


About the ActiveX component

The XCEEDBEN.DLL is a fully self-contained COM ActiveX control written entirely with ATL v3.0 and Visual C++ 6.0. There are no external dependencies required for its operation such as other DLLs.

The DLL file can be found in the \PROGRAM FILES\XCEED COMPONENTS\XCEED BINARY ENCODING LIBRARY\BIN directory.

The ActiveX control supports both the single-threaded apartment and the multi-threaded apartment models, and therefore will not work with Windows NT 3.51 because the DCOM extensions are not available for that operating system.

The control is digitally signed with Microsoft Authenticode technology, with VeriSign or Thawte as the certificate verification authority. This helps ensure that the component has not been tampered or modified by parties other than Xceed Software, and is also useful when the component is used on web pages so that browsers do not complain about security issues.

Typically, applications that use ActiveX controls are distributed with an install or setup program that will also take care of registering the controls on the machine. If you aren't using a setup program, then you will have to manually register the component on the machine.

How to manually register the ActiveX component

The registration process referred to here is not related to licensing, it refers to the process of making the control known to the operating system. If you don't use an install program with this capability built-in, you can register your controls manually. From the Run option in the Windows 95 or Windows NT start menu, or from a command prompt, run the following command to register an ActiveX control:

regsvr32.exe "path and filename of the ActiveX control's DLL file"

You will then see a message box that either displays "LoadLibrary failed" or displays "LoadLibrary succeeded". If you get the success message, then the control is now registered on the machine and is ready for use by applications or in your development environment. If you get the failure message, make sure you specified a correct path and filename, and placed it in quotes if it has spaces in it.

Registration problems

If you are unable to register a fully-self contained ActiveX control on a target machine, even after following the instructions above, Xceed is currently aware of only one possible problem that may prevent proper registration of ActiveX controls. The problem applies to systems running the original release of Windows 95 or OSR1. If these machines don't have Internet Explorer v4.0 or up, then you will need to install DCOM 95 which will update the COM support for these machines. You can download DCOM 95 from Microsoft's web site at http://www.microsoft.com/com/dcom/dcom95/dcom1_3.asp


What must be distributed

You only need to distribute the XCEEDBEN.DLL file with your applications in order for the Xceed Binary Encoding Library to work.

It is highly recommended to place the XCEEDBEN.DLL file in the Windows System folder, with an application that does version checking, so that an already existing version of the file is not overwritten by an older version. Xceed Software will ensure that as long as the file keeps the XCEEDBEN.DLL name, it will always be backwards compatible with older versions. So applications compiled to work with Xceed Binary Encoding Library v1.0 will work with a future v1.1 or more DLL.

The XCEEDBEN.DLL file is fully self-contained, which means that target machines do not need any other files (such as the MFC40.DLL, MSVCRT40.DLL or  ATL.DLL etc.) in order for the XCEEDBEN.DLL to register and work on the machine. The early releases of Windows 95 (up to OSR1) require that you install the DCOM update or Internet Explorer v4.0, so that you can use apartment threaded components.

Only registered users are licensed to deploy or distribute applications that use the Xceed Binary Encoding Library.


License, copyright and disclaimer

The use of this package indicates your understanding and acceptance of the following terms and conditions. This license shall supersede any verbal, or prior verbal or written, statement or agreement to the contrary. If you do not understand or accept these terms, or your local regulations prohibit "after sale" license agreements or limited disclaimers, you must cease and desist using this product immediately.

Copyright: This product is Copyright ©2001 Xceed Software Inc., all rights reserved. This product is protected by Canadian and United States copyright laws, international treaties and all other applicable national or international laws. This software product and documentation may not, in whole or in part, be copied, photocopied, translated, or reduced to any electronic medium or machine readable form, without prior consent in writing, from Xceed Software Inc. and according to all applicable laws. The sole owner of this product is Xceed Software Inc.

Liability disclaimer: This product and/or license is provided as is, without any representation or warranty of any kind, either express or implied, including without limitation any representations or endorsements regarding the use of, the results of, or performance of the product, its appropriateness, accuracy, reliability, or correctness. The entire risk as to the use of this product is assumed by the user and/or licensee. Xceed Software Inc. does not assume liability for the use of this program beyond the original purchase price of the software. In no event will Xceed Software Inc. be liable for additional direct or indirect damages including any lost profits, lost savings, or other incidental or consequential damages arising from any defects, or the use or inability to use these programs, even if Xceed Software Inc. has been advised of the possibility of such damages.

Restrictions: You may not use, copy, modify, translate, or transfer the programs, documentation, or any copy except as expressly defined in this agreement. You may not attempt to unlock or bypass any "copy-protection" or authentication algorithm utilized by the program. You may not remove or modify any copyright notice, nor the About dialog or the method by which it may be invoked.

Operating license: You have the non-exclusive right to use any enclosed program only by a single person, on a single computer at a time. You may physically transfer the program from one computer to another, provided that the program is used only by a single person, on a single computer at a time. In group projects where multiple persons will use the program, you must purchase an individual license for each member of the group. Use over a "local area network" (within the same locale) is permitted provided that the program is used only by a single person, on a single computer at a time. Use over a "wide area network" (outside the same locale) is strictly prohibited under any and all circumstances.

Linking and distribution license: In order to link and distribute compiled Xceed Binary Encoding Library code, including the XCEEDBEN.DLL file, in accordance to this license, you must be registered with Xceed Software Inc. as an authorized licensee. You may not reproduce or distribute copies of the complete package, any of the source, interface, code units or any license (.LIC) files, the LICENSE.TXT file, your private license key, any of the documentation, nor may you supply any means by which your users could create, modify, or incorporate the Xceed Binary Encoding Library in their own products. Violations will be prosecuted to the maximum extent possible under the law.

Back-up and transfer: You may make one copy of the program solely for "back-up" purposes, as prescribed by Canadian, United States, and international copyright laws. You must reproduce and include the copyright notice on the back-up copy. You may transfer the product to another party only if the other party agrees to the terms and conditions of this agreement, and completes and returns registration information (name, address, etc.) to Xceed Software Inc. within 30 days of the transfer. If you transfer the program you must at the same time transfer the documentation and back-up copy, or transfer the documentation and destroy the back-up copy. You may not retain any portion of the program, in any form, under any circumstance.

Terms: This license is effective until terminated. You may terminate it by destroying the program, the documentation and copies thereof. This license will also terminate if you fail to comply with any terms or conditions of this agreement. You agree upon such termination to destroy all copies of the program and of the documentation, or return them to Xceed Software Inc. for disposal.

Other rights and restrictions: All other rights and restrictions not specifically granted in this license are reserved by Xceed Software Inc.


Acknowledgments

Numega

Xceed Binary Encoding Library v1.0 was extensively checked and processed with the help of Numega's BoundsChecker, TrueCoverage, TrueTime software and of course, lots of beta testing! BoundsChecker finds memory and resource leaks, checks API calls for accuracy, and finds a host of other potential problems. TrueCoverage makes sure every single line of code was tested. TrueTime allows you to find out what the bottlenecks are in your code and helps you optimize and fine tune your code for maximum speed. These products may not come cheap, but they're worth every penny.

eHelp

This help documentation was created with RoboHelp Office. It is a very complete package that includes lots of time-saving tools, is very robust, and fully integrates with Microsoft Word.


Xceed Software's address, phones and email

You can contact us through any of the following services:

	Internet Web site	info@xceedsoft.com (general inquiries) support@xceedsoft.com (technical support) www.xceedsoft.com
	Telephone Orders Fax	(450) 442-2626 (technical support) (800) 865-2626 (sales questions & orders) (450) 442-4604
	Mail	Xceed Software Inc. 1555 Boul. Jean-Paul Vincent Suite 180 Longueuil, Québec Canada  J4N 1L6


Order form with pricing information
Xceed Software Inc. 1555 Boul. Jean-Paul Vincent Suite 180 Longueuil, Québec Canada  J4N 1L6	www.xceedsoft.com Sales: Tel: (800) 865-2626 Fax: (450) 442-4604 sales@xceedsoft.com Support: Tel: (450) 442-2626 support@xceedsoft.com	Fax Back Order Form (450) 442-4604
Please fill in the form below and send back for immediate service. Please print clearly.

Please note that your order will be charged in Canadian dollars at the current US dollar exchange rate.

All products include a 60 day satisfaction money-back guarantee, and royalty-free distribution rights.


How to order Xceed Zip
How to order Xceed Binary Encoding Library

To place an order

Contact Xceed Software directly using the (800) 865-2626 order line, fax/mail an Order Form, or use the secure online ordering system at www.xceedsoft.com. See the order form for pricing information.

If you are an established distributor or reseller and you wish to carry Xceed products, please contact us directly.

When ordering, please follow these simple guidelines

•	Print or type clearly. Do not assume we will know what city, state/province, or country you are in. This is especially important for foreign orders, where it is more difficult for us to guess what a city or state might be. For telephone or fax numbers, please include your country code, and/or make sure that the country is spelled out completely. Do not use abbreviations such as UK, DN, FR, etc. It will avoid confusion and greatly accelerate processing your order.

•	We can only accept credit cards, US or Canadian checks, and international bank drafts or money orders. Please do not send EuroChecks, Purchase Orders or request bank transfers. All checks must be drawn on a US or Canadian bank.

•	If you are sending a check or a bank draft, and this file is more than 6 months old (past September 2001), please make sure that the price has not changed before you order.

•	If you send a bank draft, please do not have the bank send it automatically. You must include an order form with the bank draft.

•	If you order by credit card, please make sure you include all the details, including the card number, the expiration date, and the complete name on the card. Do not send a fax/letter asking us to call you for the card number. Call us directly if you do not want to include the card number on your fax.

•	Although we will always do our utmost to process your order as quickly as possible, it can sometimes take up to 48 hours. Please consider this when you place a rush order.

•	Finally, please note the time before you call and check the time difference between your time zone and ours. We are located in the Eastern standard time zone.

These few guidelines will help assure that everyone will get their order processed quickly and correctly.


Upgrades

We periodically provide bug fixes and upgrades for our products. Always check our Web site at www.xceedsoft.com for the latest information on the Xceed Binary Encoding Library.

Upgrade policy

Minor changes and bug fixes are free; major revisions carry an upgrade fee. If we release a major revision within 60 days of your purchase, and it is identically priced, we will provide the upgrade free of charge. Shipping and handling are always extra. We do not automatically inform you of minor fixes, only major revisions.

Upgrade pricing and purchasing

Purchasing an upgrade entitles you to 1 year's worth of unlimited major and minor upgrades. A year's worth of major and minor upgrades for the Xceed Binary Encoding Library costs $99 US.

All upgrades can be obtained directly from Xceed Software Inc. The best place to purchase your upgrade is on our web site, in the order section, at www.xceedsoft.com. For more options, see the How to Order topic.

Upgrade prices are subject to change without any prior notice.


Technical support

Before you contact us

In order to save everyone some time, we'd like you to do a few things before you contact us. We know the urge to call is great, but we'd appreciate it if you double check this list:

•	Have you consulted the Windows Help manual?

•	Have you used the search feature of the manual?

•	Have you looked at the sample application sources?

If you got this far, it must be a tough one. It' is definetly time to tell us about your problem. Start by noting down the language you are using, the version of the Xceed Binary Encoding Library, the exact error message (if any) or error code values you are getting, the operating system you are running your project on and a brief description of what you are trying to do. It would be a good idea to also note down exactly when the problem occurs.

How to contact us

The preferred method of contacting us for technical support is on the Internet. You can send any questions or problems to our Internet address: support@xceedsoft.com.

We also offer free telephone support on an "as available" basis, Monday through Friday usually from 9 a.m. to 5 p.m. Eastern standard time.

Although there is currently no expiration date on free support, we reserve the right to restrict it to the first 60 days from the time of purchase, without any prior notice.


Help file revision

Xceed Binary Encoding Library v1.0

Windows Help File Last Revised on May 9th, 2001

Copyright ©2001 Xceed Software Inc. All rights reserved.

This document may not be reproduced in whole or in part without written authorization from Xceed Software Inc.


Contents
Contents of the Xceed Binary Encoding Library Documentation

Click on the topic you want to jump to.

Introduction • Welcome  • Features  • About the free trial version  Getting started quickly • Installation instructions  • Getting Started Quickly topics  Xceed Binary Encoding control reference • Overview  • Formless use of the control  • Running simultaneous operations  • Methods  • Properties  • Enumerations  • Error codes	Samples • About the sample applications  Deploying • What must be distributed  • About the ActiveX component  Legal information • License, copyright and disclaimer  • Acknowledgments  Contact and product information • Xceed Software's contact info  • Order form with pricing info  • How to order  • Upgrades  • Technical support  Help file revision


License method (Xceed Compression control)
License method

Description

When instantiating the component dynamically, the License method must be called to license the library for runtime use. This applies to both registered users as well as users of a time-limited free trial license.

If you do not call this method when dynamically instantiating the component in the situations described below, Xceed Binary Encoding Library method calls will not work and will immediately return the berNotLicensed error code.

When to call the License method

You must call the License method if you are instantiating the component in the following situations:

•	In VB or VB script when using the CreateObject() call.

•	In Delphi or C++Builder, if you aren't using the automatically generated ActiveX wrapper objects (they start with "TXceed"). Delphi users see important note below.

•	In C++ or any other language that uses the CoCreateInstance COM API call to instantiate the component.

The License method should be the first method you call after instantiating component, and before any methods are called.

When the component is being used on an HTML document with the <OBJECT> tag, a License Package File (LPK) should be used to provide the license key. You can obtain more information and an LPK creation kit from http://www.microsoft.com/workshop/components/activex/licensing.asp#LPKFILES or from http://www.microsoft.com/gallery/tools/lpktool/lpktool.asp.

Important note

When using automatically generated ActiveX wrappers (Delphi, C++ Builder, LPK package users for example), make sure to regenerate the wrapper if you have licensed your component using the 'License this component' item from the Start -> Programs -> Xceed Components -> Xceed Binary Encoding Library menu. Otherwise, you will find you need to call the License method.

Parameters

Parameter	Description

sLicense	Provide your license key here. Both registered users and trial version users have a license key. This key can be found by selecting the Start -> Programs -> Xceed Components -> Xceed Binary Encoding Library -> License this component menu item. Trial version keys are time-limited and will not work after the trial period has ended.

Return values

Returns True if the license key was accepted, False if the license key was invalid.

Remarks

The License method is required because instantiation methods such as CreateObject() and CoCreateInstance() do not cooperate with the licensing scheme provided by IClassFactory2.

Declaration (DXceedBinaryEncoding)

HRESULT License(
  [in] BSTR sLicense,
  [out,retval] VARIANT_BOOL* pbSucceeded
)

Declaration (IXceedBinaryEncoding)

HRESULT License(
  [in] BSTR sLicense,
  [out,retval] BOOL* pbSucceeded
)


Streaming

Streaming data means data that is readable or obtainable only in a steady stream or in portions of sequential data. For example, a file's data arriving through modem is considered streaming data because you only get access to the data in a sequential fashion, as it becomes available. A file already completely transferred is no longer streaming data – you can access the entire file in a random access fashion.


Installation instructions for Visual C++ 4.0
Installation instructions for Visual C++ 4.0 (MFC projects)

The Xceed Component Installer will copy all the necessary files into the library's installation folder (usually in \PROGRAM FILES\XCEED COMPONENTS\) and register the XCEEDBEN.DLL ActiveX / COM component in the BIN subfolder. The only thing left to do is to create a wrapper class for your MFC projects (assuming you're working with MFC) and make the control available to your VC++ 4.0 projects. To do this, perform the following steps:

•	Start Visual C++ 4.0 (developer studio)

•	Open your MFC AppWizard application project, or create a new one by selecting the New... menu item from the File menu, and choosing the Project Workspace option. Select MFC AppWizard and follow the Wizards instructions to create the project. Be sure that you select the OLE Controls option for the question What OLE support would you like to include?

Next, if you want to drop the XceedBinaryEncoding or XceedRawBinaryEncoding control on a dialog, do this:

•	Select the Component... menu item from the Insert menu.

•	Select the OLE Controls tab in the Component Gallery dialog.

•	The Xceed Binary Encoding control icon appear in the list of controls displayed in the OLE Controls tab in the Component Gallery dialog.

•	Select the Xceed Binary Encoding control icon, then click the Insert button in the Component Gallery dialog to insert the control in your project. The Confirm Classes dialog should appear.

•	Click OK to close the Confirm Classes dialog.

•	Click the Close button to close the Component Gallery dialog.

•	The XCEEDBEN.CPP and XCEEDBEN.H files should now be part of your project. You will now be able to instantiate the Xceed Binary Encoding object in your project, and see the Xceed Binary Encoding icon available in your Controls toolbar when designing dialog boxes.

Or, if you want to use create an instance of the controls without requiring a CWnd parent, do this:

•	Open the ClassWizard.

•	Click the "Add Class" button and select the "From an OLE typelib" option.

•	Find and select the "XCEEDBEN.DLL" file. Even if your Visual C++ does not display files ending by "DLL", you can select "All files (*.*)" as the type of files, and then select the "XCEEDBEN.DLL" file.

•	Select the "IXceedBinaryEncoding" and "IXceedRawBinaryEncoding" interfaces. Visual Studio will generate two files: "XCEEDBEN.CPP" and "XCEEDBEN.H"

•	At the place you want to create your instance of XceedBinaryEncoding or XceedRawBinaryEncoding, include the "XCEEDBEN.H " file and create a variable of type "IXceedBinaryEncoding" and "IXceedRawBinaryEncoding", and call the "CreateDispatch" method on this variable to actually create the instance behind the wrapper object.

•	Finally, when you are finished with your instance, make sure to call the "ReleaseDispatch" method on it.

If the Xceed Binary Encoding control icon does not appear in the list of controls displayed in the OLE Controls tab in the Component Gallery dialog:

•	Try reinstalling the Xceed Binary Encoding Library from its installation program. Continue only if that didn't help.

•	Select the Customize... button.

•	Select the OLE Controls category in the Customize Component Gallery dialog.

•	Select the Import... button in the Customize Component Gallery dialog.

•	Find and select the XCEEDBEN.DLL file (preferably the one in the Windows System folder that was copied there by the Xceed Binary Encoding Library installation program), then click on the OK button.

•	Click the OK button in the Customize Component Gallery dialog.

•	The Xceed Binary Encoding control icon should now appear in the list of controls.


Installation instructions for Visual C++ 5.0
Installation instructions for Visual C++ 5.0 (MFC projects)

The Xceed Component Installer will copy all the necessary files into the library's installation folder (usually in \PROGRAM FILES\XCEED COMPONENTS\) and register the XCEEDBEN.DLL ActiveX / COM component in the BIN subfolder. The only thing left to do is to create a wrapper class for your MFC projects (assuming you're working with MFC) and make the control available to your VC++ 5.0 projects. To do this, perform the following steps:

•	Start Microsoft Visual C++ 5.0

•	Open your MFC AppWizard application project, or create a new one by selecting the New... menu item from the File menu, then selecting the Projects tab and choosing the MFC AppWizard item. Follow the Wizards instructions to create the project. Be sure that you select the ActiveX Controls option for the question "What other support would you like to include?"

Next, if you want to drop the XceedBinaryEncoding on a dialog, do this:

•	Select the Project menu

•	Select the Add to project submenu, then select Components and Controls...

•	In the Components and Controls Gallery dialog, look in the Registered ActiveX Controls folder for the "Xceed Binary Encoding Library v1.0" entry, then select it and click on the Insert button.

•	Select the OK in response to the Insert this component? message box. The Confirm Classes dialog should appear.

•	Click OK to close the Confirm Classes dialog.

•	Click the Close button to close the Components and Controls Gallery dialog.

•	The XCEEDBEN.CPP and XCEEDBEN.H files should now be part of your project. You will now be able to instantiate the Xceed Binary Encoding object in your project, and see the Xceed Binary Encoding control icon available in your Controls toolbar when designing dialog boxes.

Or, if you want to use create an instance of the controls without requiring a CWnd parent, do this:

•	Open the ClassWizard.

•	Click the "Add Class" button and select the "From a type library" option.

•	Find and select the " XCEEDBEN.DLL" file. Even if your Visual C++ does not display files ending by "DLL", you can select "All files (*.*)" as the type of files, and then select the "XCEEDBEN.DLL" file.

•	Select the "IXceedBinaryEncoding" and "IXceedRawBinaryEncoding" interfaces. Visual Studio will generate two files: "XCEEDBEN.CPP" and "XCEEDBEN.H"

•	At the place you want to create your instance of XceedBinaryEncoding or XceedRawBinaryEncoding, include the "XCEEDBEN.H " file and create a variable of type "IXceedBinaryEncoding" and "IXceedRawBinaryEncoding", and call the "CreateDispatch" method on this variable to actually create the instance behind the wrapper object.

•	Finally, when you are finished with your instance, make sure to call the "ReleaseDispatch" method on it.


About the sample applications

The getting started quickly section has topics that tell you what you have to do to accomplish basic encoding and decoding operations. However, it often helps to just be able to open a project and check out how things work with a ready-to-use sample.

Xceed has provided you with various flavors of sample applications to help you out in a variety of development environments.

Sample Applications

These sample applications with source code provide you with interactive applications that show you how the most important features of the library are used.

Manager Sample Application

•	Go to the Manager Sample Application for VB6 topic

•	Go to the Manager Sample Application for Delphi topic

•	Go to the Manager Sample Application for C++Builder topic

Memory Encode Application

•	Go to the Memory Encode Sample Application for VB6 topic

•	Go to the Memory Encode Sample Application for Delphi topic

•	Go to the Memory Encode Sample Application for C++Builder topic

•	Go to the Memory Encode Sample Application for Visual C++ with MFC topic

Encode / Decode Sample Application

•	Go to the Encode Sample Application for Visual C++ topic

•	Go to the Decode Sample Application for Visual C++ topic


About the getting started quickly section

This section of the manual has but one goal: To show you, as fast as possible, how to use the library's major features.

If you don't see what you need here, the next step is to read the Overview of the Xceed Binary Encoding control. From there you will probably jump to the methods or properties topic. If all else fails, use the "search" feature of the manual, or browse the sample applications. Feel free to contact Xceed Software at any time if you have questions.

Getting started quickly topics

•	Encoding and decoding from file to file

•	Encoding and decoding entirely in memory

•	Encoding and decoding from memory to file

•	Encoding and decoding from file to memory


Installation instructions index

The Xceed Component Installer will copy all the necessary files into the library's installation folder (usually in \PROGRAM FILES\XCEED COMPONENTS\) and register the XCEEDBEN.DLL ActiveX / COM component in the BIN subfolder. There are some additional steps you must take to complete the installation, based on which development language you are using.

Click on one of the following links for instructions specific to your language.

•	Installation instructions for Visual Basic 5.0

•	Installation instructions for Visual Basic 6.0

•	Installation instructions for Visual C++ 4.0 (MFC)

•	Installation instructions for Visual C++ 5.0 (MFC)

•	Installation instructions for Visual C++ 6.0 (MFC)

•	Installation instructions for Word 97 and Excel 97

•	Installation instructions for Access 97

•	Installation instructions for Visual FoxPro 5.0 and 6.0

•	Installation instructions for Delphi 3.0

•	Installation instructions for Delphi 4.0 and 5.0

•	Installation instructions for C++ Builder 3.0

•	Installation instructions for C++ Builder 4.0

•	Installation instructions for other 32-bit development environments


Running multiple operations at the same time

The Xceed Binary Encoding Library v1.0 ActiveX control supports both the Single-Threaded Apartment model (STA) and the Multi-Threaded Apartment model (MTA). The entire library's code is threadsafe, can be instantiated multiple times in order to perform multiple memory or file encoding or decoding operations at the same time, and is designed to use very little memory per instance – so your machine won't run out of memory when you're running dozens of instances at the same time.

Any restrictions?

Yes: two or more instances may not write to the same destination file when using the WriteFile or ProcessFile methods. Other than that, running multiple simultaneous operations involves having multiple instances, with each instance running its own operation independently.


Formless use of the control

You can instantiate the ActiveX control without putting it on a form. To do this, make the control available in your development environment (this should already have been done if you followed the installation instructions) and simply create an instance of the object like you would any other variable. The object's type is "XceedBinaryEncoding".

Example for VB users:

' Make sure you added the Xceed Binary Encoding control to your object references. To do this, go to the Project menu and select the "References..." menu item, then checkmark the Xceed Binary Encoding Library entry in the list of components.

' Here we define the type for our variable and instantiate it

Dim XceedBinaryEncoding1 As New XceedBinaryEncoding

' And now its as if the control was put on the form.

Example for Visual FoxPro users:

&& Here we create an Xceed Zip object called xZip

XceedBinaryEncoding1 = CreateObject("XceedSoftware.XceedBinaryEncoding.1")

&& And now we can work as usual…


Overview of the Xceed Data Compression control
Overview of the Xceed Binary Encoding control

Introduction

The Xceed Binary Encoding control handles all encoding and decoding tasks. The source of the data can be memory buffers, strings, blobs, streaming data or single files. The processed data can be written to memory or to file.

The Xceed Binary Encoding control can encode and decode a variety of encoding formats, including UUEncode, XXEncode, Base64, Binhex, Hexadecimal and Quoted-Printable.

The library's programming interface offers a small number of clearly named methods and properties designed to expose the library's capabilities in an intuitive fashion.

How to use

To use the library, the first thing you must do is create an instance of the XceedBinaryEncoding object. The next thing you must do is decide if the default encoding or decoding format you want to use is UUEncode/Decode. If it is not, then you must create an instance of the appropriate Encoding Format object and assign it to the EncodingFormat property. If the default encoding format (UUEncode/Decode) was what you needed, an XceedUUEncodingFormat object is already assigned to the EncodingFormat property.

The next thing to do is to set the Encoding Format object's properties. You can access its properties by refering to the EncodingFormat property's value, which is the Encoding Format object. Example:

MyXceedBinaryEncoding.EncodingFormat.MaxLineLength = 80

Finally, you can call one of the library's methods such as Encode or Decode.

See the Getting started quickly topics listed below for examples.

Resources

•	Methods

•	Properties

•	Encoding Format objects

•	Enumeration types

•	Error codes

Getting started quickly

•	Encoding and decoding from file to file

•	Encoding and decoding entirely in memory

•	Encoding and decoding from memory to file

•	Encoding and decoding from file to memory

Other information

•	How formatting characters are decoded

•	Formless use of the control

•	Running multiple operations at the same time


About Xceed Data Compression control methods
About Xceed Binary Encoding control methods

The Xceed Binary Encoding control provides the following methods to accomplish the tasks of encoding and decoding data and files. Each method's behavior is determined by the values of various properties. The "Remarks" section in the documentation for each method explains which properties are used by that method. When executing a method, it is important to correctly set all properties that are used by that method. Unwanted side effects may occur if properties were altered for the execution of one method, but were not set to the desired values for the next execution of a method that uses those same properties.

All XceedBinaryEncoding control methods return an HRESULT return code. See the Error codes topic for details on error handling.

List of the Xceed Binary Encoding control's methods:

• Encode  • Decode  • ProcessFile  • ReadFile	• Reset  • WriteFile  • License


About Xceed Data Compression control properties
About Xceed Binary Encoding control properties

The Xceed Binary Encoding control includes only a single property that you may need to set before you use any of the library's methods. The property is named EncodingFormat. By default, the property has been assigned the XceedUUEncodingFormat object to it, so that the library is ready to perform UUEncode/Decode processing. If you need to use another encoding/decoding format, then you will create an instance of an Encoding Format object and assign it to the property. Each Encoding Format object has its own properties that you can set to determine how the library should handle encoding or decoding of that particular object's format.


About Xceed Data Compression control enumeration types
About Xceed Binary Encoding control enumeration types

The following enumerations are built into the Xceed Binary Encoding control's ActiveX interface and are used as parameter types for Xceed Binary Encoding control methods and events, and as types for some Xceed Binary Encoding control properties.

List of the Xceed Binary Encoding control's enumeration types:

• EXBEndOfLineType  • EXBFileProcessing  • EXBUnixFilePermission  • EXBError


About Xceed Data Compression control error codes
Xceed Binary Encoding control error codes

The following constants define all the possible error code values that Xceed Binary Encoding control methods can produce. The declarations for these error codes are built into the library's "Type Library" (see the EXBError enumeration) and should automatically be accessible by your code.

Visual Basic users should use the Err object in their error handling code. It provides a textual description of the error code when needed.

Delphi users can trap the EOleException exception (include “comobj" in your unit’s Uses clause) and access the any of the exception object's properties for information about the error.

Standard COM error codes

Constant	Value	Description

S_OK 	0	The method call completed successfully.

E_INVALIDARG	0x80070057	An invalid parameter was passed to a method call.

E_OUTOFMEMORY 	0x8007000E 	Not enough memory or system resources available.

E_POINTER 	0x80004003 	A NULL pointer was passed to a method's [out] parameter.

E_UNEXPECTED 	0x8000FFFF 	Unexpected condition occurred. Contact Xceed support!

Xceed Binary Encoding control error codes

Constant	Value	Description

berWarningInvalidCharacterInData	0x00044001L	Invalid character in the data.

berWarningInvalideEndOfData	0x00044002L	 Invalid end of data.

berWarningRemainingData	0x00044003L	The internal buffer as remaining data to process.

berWarningInvalidLineLengthInData	0x00044004L	The data content an invalide line length.

berWarningInvalideNumberOfCharacterOnLine

0x00044005L	The data has a line containing an invalid number of charater.

berInvalidCharacterInData	0x80044001L	Invalid character in the data.

berInvalideEndOfData	0x80044002L	Invalid end of data.

berRemainingData	0x80044003L	The internal buffer as remaining data to process.

berInvalidLineLengthInData	0x80044004L	The data content an invalide line length.

berInvalideNumberOfCharacterOnLine	0x80044005L	The data has a line containing an invalid number of charater.

berInvalidFileProcessing	0x80044006L	The file processing action is not supported for this method.

berEmptyFile	0x80044007L	The specified source file is empty.

berInvalidFileOffset	0x80044008L	The file offset is behond the end of file.

berReadFile	0x80044009L	Cannot read data from the source file.

berWriteFile	0x8004400AL	Cannot write data to the destination file.

berFileNotFound	0x8004400BL	The specified filename does not exist.

berPathNotFound	0x8004400CL	The specified path does not exist.

berAccessDenied	0x8004400DL	Access denied.

berAlreadyInUse	0x8004400EL	The file is already in use.

berInvalideFileName	0x8004400FL	The file name is invalid.

berDiskFull	0x80044010L	The disk is full.

berAlreadyExists	0x80044011L	The destination file already exist.

berAccessingDrive	0x80044012L	Error accessing the specified drive.

berOpenFileForReading	0x80044013L	Unknown error when trying to open the source file for reading.

berOpenFileForWriting	0x80044014L	Unknown error when trying to open destination file for writing.

berEmptyFileName	0x80044015L	The filename is empty.

berFileTooBig	0x80044016L	The file size is greather than 4 giga bytes.

berNotLicensed	0x80044017L	The license key required to use Xceed Binary Encoding Library was not found, is invalid, or is an expired trial license key.

berInvalidEncodingMethod	0x80044018L	Invalid encoding method.

berInvalidEndOfLineType	0x80044019L	Invalid end of line type.

berSessionOpened	0x8004401AL	A session is already underway.

berInvalidMaxLineLength	0x8004401BL	Invalid maximum line length.

berBusy	0x8000401EL	The componenent is already busy performing another operation.

berInternalError	0x80044FFFL	An unexpected error occurred. Please contact Xceed support.


Welcome to Xceed Data Compression Library
Welcome to Xceed Binary Encoding Library v1.0

The Xceed Binary Encoding Library is a library for Windows developers that allows applications to encode binary data and files into text and vice-versa. The library can encode or decode memory buffers, strings, blobs, streaming data or single files.

The library supports a variety of popular encoding methods, including UUEncode, XXEncode, Base64, Binhex and Quoted-Printable.

Like all Xceed components, this library is designed to be flexible yet extremely easy to use. In fact, it only takes one line of code to encode or decode memory or files. A single line of code can even be used to chain together multiple Xceed components like the Xceed Encryption Library and the Xceed Binary Encoding Library, so you can compress, encrypt and encode data into text just as easily as possible.

The fully self-contained ActiveX control at the core of the library is all you need to include with your projects. The component has no external dependencies such as MFC DLLs, runtime libraries or other resources. That translates to minimal hassle at distribution time. The library also supports all the available ActiveX functionality designed to make your programming job easier, such as categorized properties, built-in constants and enumerations, context-sensitive F1-help, optional parameters and built-in help strings.

The library comes with support for all 32-bit development languages that can use ActiveX controls, including Visual Basic, Visual C++, Delphi, C++Builder, Visual FoxPro, Visual Interdev, Office 97 suite products.

We invite you to download the fully functional free trial version of the library and start integrating Xceed Binary Encoding Library into one of your existing programs right away. All you really have to do is add the control to a form, set one or two properties, and off you go! Get it at www.xceedsoft.com.

All Xceed products include comprehensive online documentation, free expert technical support, royalty-free distribution and a 60-day money-back guarantee. If you're not satisfied for any reason, return the product for a full refund of the purchase price.

Xceed is devoted to the development and support of high-quality ActiveX, COM and Microsoft .NET components. That's a promise we have kept since our first components were released for 16-bit Visual Basic 3.0 and Delphi 1 back in 1995. Visit our web site at www.xceedsoft.com for up-to-date information on Xceed components.


Encode method

VB example   VC++ example  Delphi example

Description

The Encode method encodes data entirely in memory. It can encode data in a single call, or it can be called multiple times to encode data in a streaming fashion.

Parameters

Parameter	Description

vaSource	The data to encode. All OLE automation variant types are supported, including string and byte array variants.

bEndOfData	This parameter indicates to the library whether or not there is more data to encode.

If you only have a single block of data to encode, set this parameter to True. The library will then immediately encode all the data provided in the vaSource parameter and return the resulting encoded data.

If you can only provide a portion of the data to encode in the vaSource parameter and will provide more data later in a subsequent call to the Encode method, set this parameter to False. In this case, the library will encode and return as much data as possible. When the final portion of the data to encode has been provided, set the bEndOfData parameter to True. The method will then return the final portion of the encoded data.

Return value

The return value is a byte array variant containing the encoded data.

Associated properties

The EncodingFormat property allows you to specify the format of the encoded data to produce.

Remarks

When calling the Encode method with the bEndOfData parameter specified as False, you cannot call any other Xceed Binary Encoding control method (of the same instance of the control) until you have completed processing a stream of data by calling the Encode method with the bEndOfData parameter specified as True.

Language-specific remarks

With Visual Basic, it is often necessary to convert the resulting encoded data from a byte array variant to a native VB byte array before saving it or transmitting it. VB6 makes it particularly easy to do the conversion: If you have a variant named (for example) EncodedData, you can convert it to a native VB byte array with the following code:

Dim EncodedDataArray() As Byte

EncodedDataArray = EndodedData

With Microsoft Access, you can place the encoded data in either a Memo field or an OLE Object field. Using an OLE Object field in a table is the easiest: You can directly assign your data to the field and conversion is automatic. To assign the encoded data variant to a Memo field, use the "AppendChunk" function in Access.

Declaration (DXceedBinaryEncoding)

HRESULT Encode
(
  [in] VARIANT* vaSource,
  [in] VARIANT_BOOL bEndOfData,
  [out, retval] VARIANT* vaEncoded
)

Declaration (IXceedBinaryEncoding)

HRESULT Encode
(
  [size_is][in] BYTE* pcSource,
  [in] DWORD dwSourceSize,
  [in] BOOL bEndOfData,
  [size_is][size_is][out] BYTE** ppcEncoded,
  [out, retval] DWORD* pdwEncodedSize
)


Decode method

Description

The Decode method decodes data entirely in memory. It can decode data in a single call, or it can be called multiple times to decode data in a streaming fashion.

Parameters

Parameter	Description

vaEncoded	The data to decode. The variant can contain a string or a byte array.

bEndOfData	This parameter indicates to the library whether or not there is more data to decode.

If you only have a single block of data to decode, set this parameter to True. The library will then immediately decode all the data provided in the vaEncoded  parameter and return the resulting decoded data.

If you can (or want to) only provide a portion of the data to decode in the vaEncoded parameter and will provide more data later in a subsequent call to the Decode method, set this parameter to False. In this case, the library will decode and return as much data as possible. When the final portion of the data to decode has been provided, set the bEndOfData parameter to True. The method will then return the final portion of the decoded data.

Return value

The return value is a byte array variant containing the decoded data.

Associated properties

Set the EncodingFormat property so that the library can determine the format of the encoded data.

Remarks

When calling the Decode method with the bEndOfData parameter specified as False, you cannot call any other Xceed Binary Encoding control method (of the same instance of the control) until you have completed processing a stream of data by calling the Decode method with the bEndOfData parameter specified as True.

Language-specific remarks

With Visual Basic, it is often necessary to convert the resulting decoded data from a byte array variant to a native VB byte array before saving it or transmitting it. VB6 makes it particularly easy to do the conversion: If you have a variant named (for example) DecodedData, you can convert it to a native VB byte array with the following code:

Dim DecodedDataArray() As Byte

DecodedDataArray = DecodedData

With Microsoft Access, you can place the decoded data in either a Memo field or an OLE Object field. Using an OLE Object field in a table is the easiest: You can directly assign your data to the field and conversion is automatic. To assign the decoded data variant to a Memo field, use the "AppendChunk" function in Access.

Declaration (DXceedBinaryEncoding)

HRESULT Decode
(
  [in] VARIANT* vaEncoded,
  [in] VARIANT_BOOL bEndOfData,
  [out, retval] VARIANT* vaDecoded
)

Declaration (IXceedBinaryEncoding)

HRESULT Decode
(
  [size_is][in] BYTE* pcEncoded,
  [in] DWORD dwEncodedSize,
  [in] BOOL bEndOfData,
  [size_is][size_is][out] BYTE** ppcDecoded,
  [out, retval] DWORD* pdwDecodedSize
)


ReadFile method

VB example   VC++ example  Delphi example

Description

The ReadFile method can encode and decode data from a file to memory, as well as simply read file data to memory without processing it.

Parameters

Parameter	Description

sSourceFilename	The path and filename of the file to read and process data from.

lSourceOffset	The starting offset in the file to begin processing data from. Specify 0 to begin processing data from the beginning of the file.

lSourceSize	The amount of data to process. Specify 0 to process data from the starting offset until the end of the file.

eAction	The type of processing that should be performed. Specify bfpEncode to encode data before writing it to memory. Specify cfpDecode to decode data before writing it to memory.

bEndOfData	Determines whether or not the source data to read is the final (or the only) portion of data to process. Specify True if the source data should be completely encoded or decoded and written to memory. If the data to process is split apart in various sections of the same file, or in various files, then you can specify False in this parameter until all the source data has been read. You can specify True for the last portion of data (which can be 0 bytes long) so that the library knows it must finish processing the source data and return the last of the processed data immediately. When specifying False, the library will expect you to call the ReadFile method again later with either a new source filename and/or source offset and/or source size.

vaBytesRead	You must provide a variable in this parameter. Right before the ReadFile method completes and returns, the library will write to the variable the amount of bytes read and processed from the source file.

Return value

Returns a byte array variant containing the processed data.

When calling the ReadFile method with the bEndOfData parameter specified as False, the returned byte array variant may not contain any data. This can happen whenever the encoder or the decoder has not received enough source data in order to output a processed block.

Associated properties

The EncodingFormat property property allows you to specify which encoding format to use when encoding or decoding data.

Remarks

When calling the ReadFile method with the bEndOfData parameter specified as False, you cannot call any other Xceed Binary Encoding control method (of the same instance of the control) until you have completed processing a stream of data by calling the ReadFile method with the bEndOfData parameter specified as True.

Language-specific remarks

With Visual Basic, it is often necessary to convert the resulting processed data from a byte array variant to a native VB byte array before saving it or transmitting it. VB6 makes it particularly easy to do the conversion: If you have a variant named (for example) ProcessedData, you can convert it to a native VB byte array with the following code:

Dim ProcessedDataArray() As Byte

ProcessedDataArray = ProcessedData

With Microsoft Access, you can place the processed data in either a Memo field or an OLE Object field. Using an OLE Object field in a table is the easiest: You can directly assign your data to the field and conversion is automatic. To assign the processed data variant to a Memo field, use the "AppendChunk" function in Access.

Declaration (DXceedBinaryEncoding)

HRESULT ReadFile
(
  [in] BSTR sSourceFilename,
  [in] long lSourceOffset,
  [in] long lSourceSize,
  [in] EXBFileProcessing eAction,
  [in] VARIANT_BOOL bEndOfData,
  [out] VARIANT* vaBytesRead,
  [out, retval] VARIANT* vaResult
)

Declaration (IXceedBinaryEncoding)

HRESULT ReadFile
(
  [in] BSTR sSourceFilename,
  [in] DWORD dwSourceOffset,
  [in] DWORD dwSourceSize,
  [in] EXBFileProcessing eAction,
  [in] BOOL bEndOfData,
  [out] DWORD* pdwBytesRead,
  [size_is][out] BYTE** ppcData,
  [out, retval] DWORD* pdwDataSize
)


WriteFile method

VB example   VC++ example  Delphi example

Description

The WriteFile method can encode and decode data from memory and write it directly to a file, as well as simply write memory data to a file without processing it.

Parameters

Parameter	Description

vaData	The data to encode. All OLE automation variant types are supported, including string and byte array variants.

eAction	The type of processing that should be performed. Specify bfpEncode  to encode data. Specify bfpDecode to decode data.

bEndOfData	Determines whether or not the data provided in the vaData parameter is the final (or the only) portion of data to process. Specify True if the data should be completely encoded or decoded and written to the file. If the data to process must be processed in streaming fashion, then you can specify False in this parameter until all the source data has been processed. You can specify True for the last portion of data (which can be 0 bytes long) so that the library knows it must finish processing all the provided source data and flush its buffers to the destination file.

sDestFilename	The path and filename of the file to write the encoded or decoded data to. If the file does not already exist, it will be created and written to. If the file already exists, the library can either clear the file and write to it as a new file, or it can append the processed data to the end of the destination file.
When decoding a UUEncoded, XXEncoded or BinHexed file (or data) and the IncludeHeaderFooter property is set to True, you do not need to specify a filename in this parameter. You can specify only a path. In this case, the header information in the UUEncoded, XXEncoded or BinHexed data stream or file will provide the filename. Make sure the path you specify in this parameter ends with a "\".

bAppend	Determines the behavior of the library when the destination file already exists. Specify True to append to an existing file, or False to clear the file and write processed data to it as a new file.

Return value

Returns the amount of bytes written to the destination file.

Associated properties

The EncodingFormat property property allows you to specify which encoding format to use when encoding or decoding data.

Remarks

When calling the WriteFile method with the bEndOfData parameter specified as False, you cannot call any other Xceed Binary Encoding control method (of the same instance of the control) until you have completed processing a stream of data by calling the WriteFile method with the bEndOfData parameter specified as True.

Declaration (DXceedBinaryEncoding)

HRESULT WriteFile
(
  [in] VARIANT* vaData,
  [in] EXBFileProcessing eAction,
  [in] VARIANT_BOOL bEndOfData,
  [in] BSTR sDestFilename,
  [in] VARIANT_BOOL bAppend,
  [out, retval] long* plWritten
)

Declaration (IXceedBinaryEncoding)

HRESULT WriteFile
(
  [size_is][in] */ BYTE* pcData,
  [in] DWORD dwDataSize,
  [in] EXBFileProcessing eAction,
  [in] BOOL bEndOfData,
  [in] BSTR sDestFilename,
  [in] BOOL bAppend,
  [out, retval] DWORD* pdwWritten

)


ProcessFile method

VB example   VC++ example  Delphi example

Description

The ProcessFile method can encode or decode data from one file to another.

Parameters

Parameter	Description

sSourceFilename	The path and filename of the source file to encode or decode.

lSourceOffset	The starting offset in the source file to begin processing data from. Specify 0 to begin processing data from the beginning of the file.

lSourceSize	The amount of data to process. Specify 0 to process data from the starting offset until the end of the file.

eAction	The type of processing that should be performed. Specify bfpEncode to encode the data. Specify bfpDecode to encode the data.

bEndOfData	Determines whether or not the source data to process is the final (or the only) portion of data to process. Specify True if the source data should be completely encoded or decoded and written to the destination file. If the data to process is split apart in various sections of the same file, or in various files, then you can specify False in this parameter until all the source data has been processed. You can specify True for the last portion of data (which can be 0 bytes long) so that the library knows it must finish processing all the provided source data and flush its buffers to the destination file. When specifying False, the library will expect you to call the ProcessFile method again later with either a new source filename and/or source offset and/or source size.

sDestFilename	The path and filename of the file to write the encoded or decoded data to. If the file does not already exist, it will be created and written to. If the file already exists, the library can either clear the file and write to it as a new file, or it can append the processed data to the end of the destination file.

When decoding a UUEncoded, XXEncoded or BinHexed file (or data) and the IncludeHeaderFooter property is set to True, you do not need to specify a filename in this parameter. You can specify only a path. In this case, the header information in the UUEncoded, XXEncoded or BinHexed data stream or file will provide the filename. Make sure the path you specify in this parameter ends with a "\".

bAppend	Determines the behavior of the library when the destination file already exists. Specify True to append to an existing file, or False to clear the file and write processed data to it as a new file.

vaBytesRead	You must provide a variable in this parameter. Right before the ProcessFile method completes and returns, the library will write to the variable the amount of bytes read and processed from the source file.

Return value

Returns a long integer indicating the amount of bytes written to the destination file..

Associated properties

The EncodingFormat property property allows you to specify which encoding format to use when encoding or decoding data.

Remarks

When calling the ProcessFile method with the bEndOfData parameter specified as False, you cannot call any other Xceed Binary Encoding control method (of the same instance of the control) until you have completed processing a stream of data by calling the ProcessFile method with the bEndOfData parameter specified as True.

Declaration (DXceedBinaryEncoding)

HRESULT ProcessFile
(
 [in] BSTR sSourceFilename,
 [in] long lSourceOffset,
 [in] long lSourceSize,
 [in] EXBFileProcessing eAction,
 [in] VARIANT_BOOL bEndOfData,
 [in] BSTR sDestFilename,
 [in] VARIANT_BOOL bAppend,
 [out] VARIANT* vaBytesRead,
 [out, retval] long* plWritten
)

Declaration (IXceedBinaryEncoding)

HRESULT ProcessFile
(
  [in] BSTR sSourceFilename,
  [in] DWORD dwSourceOffset,
  [in] DWORD dwSourceSize,
  [in] EXBFileProcessing eAction,
  [in] BOOL bEndOfData,
  [in] BSTR sDestFilename,
  [in] BOOL bAppend,
  [out] DWORD* pdwBytesRead,
  [out, retval] DWORD* pdwWritten
)


Reset method

Description

The Reset method must be called to reset the library in the event that a sequence of calls to the Encode, Decode, ProcessFile, ReadFile or WriteFile methods (with the bEndOfData parameter specified as False) is interrupted and will not be completed with a final call specifying the bEndOfData parameter as True.

Calling the Reset method will cause the library to empty its internal buffers and to not process any accumulated (but not yet processed) data. The library will then be ready to accept new calls to these methods with new data to process.

Parameters

None

Return value

None. This method is always successful.

Declaration (DXceedBinaryEncoding and IXceedBinaryEncoding)

HRESULT Reset ()


Compressing and decompressing from file to memory
Encoding and decoding from file to memory

VB example   VB streaming example   VC++ example  Delphi example

In the descriptions below, you can freely replace the word "encode" with "decode" in order to find out how to decode data, because encoding and decoding work exactly the same way.

Basic (non-streaming) encoding from file to memory

To encode data from a file directly into memory, perform the following 4 steps. Put the Xceed Binary Encoding control on a form or instantiate it, then:

•	Specify the format for the resulting encoded data. To do this, set the EncodingFormat property.

•	Tell the library to encode. To do this, call the ReadFile method, passing the source filename, a destination memory buffer and specifying True for the bEndOfData parameter.

•	Obtain the encoded data. To do this, assign the return value of the ReadFile method to the variable of your choice.

•	Make sure that everything worked properly. To do this, use your language's error handling object or error handling capabilities. The Xceed Binary Encoding Library supports standard COM error handling functionality.

Streaming encoding

To encode data from a file directly into memory, in portions instead of the complete file, perform the following 7 steps. Put the Xceed Binary Encoding Control on a form or instantiate it, then:

•	Specify the format for the resulting encoded data. To do this, set the EncodingFormat property.

•	Determine the size of the file you will encode.

•	Tell the library to encode some data from the file. To do this, call the ReadFile method for each portion of data, passing the source filename, a destination memory buffer and specifying False for the bEndOfData parameter. Provide a starting offset of 0, and the size you specify should be the amount of data you want the library to encode during the first pass. You can use for example 32768 bytes per portion.

•	Accumulate the encoded data. To do this, append the data returned by the ReadFile method to a variable which contains the complete encoded memory buffer so far. You can also process the compressed data as it is returned by the library or pass it to other streaming methods.

•	Increment your current offset. The ReadFile method returns the amount of bytes read via the lBytesRead parameter. Add this amount to your offset.

•	Continue telling the library to encode data from the file until the your offset reaches the file's size. If your offset is smaller than the file size, call the ReadFile method, setting bEndOfData to False and passing the same filename, your new offset, and your portion size. If your offset has reached the file's size, call the ReadFile method with bEndOfData set to False, 0 for offset, 0 for file size, and if you want, an empty filename. In this case processing is complete.

•	Make sure that everything worked properly. To do this, use your language's error handling object or error handling capabilities. The Xceed Binary Encoding Library supports standard COM error handling functionality.


Compressing and decompressing from memory to file
Encoding and decoding from memory to file

VB example   VC++ example  Delphi example

In the descriptions below, you can freely replace the word "encode" with "decode" in order to find out how to decode data, because encoding and decoding work exactly the same way.

Basic (non-streaming) encoding from memory to file

To encode data from memory and place it directly into a file, perform the following 3 steps. Put the Xceed Binary Encoding control on a form or instantiate it, then:

•	Specify the format for the resulting encoded data. To do this, set the EncodingFormat property.

•	Tell the library to encode. To do this, call the WriteFile method, passing your source memory buffer, the destination filename and specifying True for the bEndOfData parameter.

•	Make sure that everything worked properly. To do this, use your language's error handling object or error handling capabilities. The Xceed Binary Encoding Library supports standard COM error handling functionality.

Streaming encoding

To encode data from memory and place it directly into a file as data becomes available, perform the following 4 steps. Put the Xceed Binary Encoding Control on a form or instantiate it, then:

•	Specify the format for the resulting encoded data. To do this, set the EncodingFormat property.

•	Provide each block of data to the library as it becomes available. To do this, call the WriteFile method for each portion of data, passing the memory buffer with a portion of the data, the destination filename and specifying False for the bEndOfData parameter.

•	Continue providing blocks of data to encode until you're done. When there is no more data to encode, call the Encode method with a final (or empty) block of data to encode and specify True for the bEndOfData parameter.

•	Make sure that everything worked properly. To do this, use your language's error handling object or error handling capabilities. The Xceed Binary Encoding Library supports standard COM error handling functionality.


Compressing and decompressing from file to file
Encoding and decoding from file to file

VB example   VC++ example  Delphi example

In the descriptions below, you can freely replace the word "encode" with "decode" in order to find out how to decode data, because encoding and decoding work exactly the same way.

Basic (non-streaming) encoding from file to file

To encode data from one file to another in a single pass, perform the following 3 steps. Put the Xceed Binary Encoding control on a form or instantiate it, then:

•	Specify the format for the resulting encoded data. To do this, set the EncodingFormat property.

•	Tell the library to encode. To do this, call the ProcessFile method, passing the source and destination filenames and specifying True for the bEndOfData parameter.

•	Make sure that everything worked properly. To do this, use your language's error handling object or error handling capabilities. The Xceed Binary Encoding Library supports standard COM error handling functionality.


EXBEndOfLineType enumeration

EXBEndOfLineType

{

  bltNone = 0,

  bltCrLf = 1,

  bltLf = 2,

  bltCr = 3

}

This enumeration is used by the EndOfLineType property. The meaning of each member of this enumeration can be found in that method's help topic.


EXBFileProcessing enumeration

EXBFileProcessing

{

  bfpEncode = 0,

  bfpDecode = 1

}

This enumeration is used in parameters of the ReadFile, WriteFile and ProcessFile methods. The meaning of each member of this enumeration can be found in each one of these methods property topics.


EXBError enumeration

EXBError

{

  berWarningInvalidCharacterInData 	= 0x44001L,

  berWarningInvalidEndOfData 	= 0x44002L,

  berWarningRemainingData 	= 0x44003L,

  berWarningInvalidLineLengthInData 	= 0x44004L,

  berWarningInvalidNumberOfCharacterOnLine	= 0x44005L,

  berWarningInvalidChecksum  	= 0x44006L,

  berWarningInvalidHeaderChecksum 	= 0x44007L,

  berInvalidCharacterInData  	= 0x80044001L,

  berInvalidEndOfData 	= 0x80044002L,

  berRemainingData 	= 0x80044003L,

  berInvalidLineLengthInData 	= 0x80044004L,

  berInvalidNumberOfCharacterOnLine 	= 0x80044005L,

  berInvalidChecksum 	= 0x80044006L,

  berInvalidHeaderChecksum 	= 0x80044007L,

  berIvalidFileProcessing 	= 0x80044008L,

  berEmptyFile 	= 0x80044009L,

  berInvalidFileOffset 	= 0x8004400aL,

  berReadFile 	= 0x8004400bL,

  berWriteFile 	= 0x8004400cL,

  berFileNotFound 	= 0x8004400dL,

  berPathNotFound 	= 0x8004400eL,

  berAccessDenied 	= 0x8004400fL,

  berAlreadyInUse 	= 0x80044010L,

  berInvalidFilename 	= 0x80044011L,

  berDiskFull 	= 0x80044012L,

  berAlreadyExists 	= 0x80044013L,

  berAccessingDrive 	= 0x80044014L,

  berOpenFileForReading 	= 0x80044015L,

  berOpenFileForWriting 	= 0x80044016L,

  berFileTooBig 	= 0x80044017L,

  berNotLicensed 	= 0x80044018L,

  berInvalidEndOfLineType 	= 0x80044019L,

  berSessionOpened 	= 0x8004401aL,

  berNoEncodingFormat 	= 0x8004401bL,

  berInvalidLengthInHeader 	= 0x8004401cL,

  berEmptyFileNameInHeader 	= 0x8004401dL,

  berBusy 	= 0x8004401eL,

  berInternalError 	= 0x80044fffL

}


EndOfLineType property

Description

When encoding, the EndOfLineType property allows you to specify the type of end-of-line delimiter (if any) to use for the encoded data being output.

Note: Use the MaxLineLength property to determine how many characters should be output between each end-of-line delimiter.

Notes

When encoding using the Quoted-Printable format, this property allows you to specify the end-of-line type that the source data uses, because in this case the library is unable to deduce the end-of-line type used. If you specify bltNone, the source file is assumed to be a binary file.

When decoding using the Quoted-Printable format, this property allows you to specify which type of end-of-line delimiter to output in the decoded file.

Data type

EXBEndOfLineType

Possible values

Value	Meaning

bltCrLf	Output or use both the CR (hex: 0x0D) and LF (hex: 0x0A) characters as an end-of-line delimiter.

bltLf	Output or use only the LF (hex:0x0A) character as an end-of-line delimiter.

bltCr	Output or use only the CR (hex:0x0D) character as an end-of-line delimiter.

bltNone	Do not output or use any end-of-line delimiter. (Invalid for the XceedUUEncodingFormat and XceedXXEncodingFormat objects. Also invalid for the XceedBinHexEncodingFormat object if the IncludeHeaderFooter property is set to True)

Default value

bltCrLf

Applicable methods

Decode, Encode, ProcessFile, ReadFile, WriteFile


MaxLineLength property

Description

The MaxLineLength property allows you to specify the maximum number of characters that the encoder should output between end-of-line delimiters. Depending on the encoding format (see EncodingFormat property), the encoder may not be able to output the exact number of characters specified and will therefore output as many characters as possible without surpassing the maximum number specified.

The value of this property is ignored if the EndOfLineType property is set to bltNone.

Data type

Long

Possible values

Setting this property to 0 means that the library should use the default line length recommended for the encoding method being used.

Some encoding formats have restrictions on the values you can place.

Encoding Format object	Default value and restrictions to possible values

XceedUUEncodingFormat	61 (minimum 5, maximum 85)
XceedXXEncodingFormat	77 (minimum 5, maximum 85)
XceedBase64EncodingFormat	76 (minimum 4)
XceedQuotedPrintableEncodingFormat	76 (minimum 4)
XceedHexaEncodingFormat	78 (minimum 2)
XceedBinHexEncodingFormat	64 (minimum 5)

Default value

0

Applicable methods

Encode, ProcessFile, ReadFile, WriteFile


ContinueOnInvalidData property

Description

The ContinueOnInvalidData property allows you to determine if the library should stop decoding data if it encounters invalid or corrupted data. Setting this property to True will cause the library to continue decoding data (without raising an error code) even if it encounters invalid data. Setting this property to False will cause the library to abort the operation and raise an error if it encounters invalid data.

Data type

Boolean Variant

Default value

True

Applicable methods

Decode, ProcessFile, ReadFile, WriteFile


IncludeHeaderFooter property

Description

The IncludeHeaderFooter property allows you to determine whether or not the library should process or include header and footer information when decoding or encoding data.

Header and footer information can contain a variety of parameters, depending on the encoding format. For UUEncode/Decode for example, the header contains a filename (see the HeaderFilename property), file permissions (See the HeaderPermissions property) and other information.

Data type

Boolean Variant

Default value

False

Applicable methods

Encode, Decode, ProcessFile, ReadFile, WriteFile


HeaderFilename property

Description

The HeaderFilname property allows you to get or set the filename in the header of data being encoded or decoded.

When encoding with the Encode or ReadFile method, a value for this property must be specified because the library has no way of determining what filename should be encoded in the header.

When encoding with the ReadFile or ProcessFile method, this property can be left empty. In this case the library will use the method's sSourceFilename parameter to determine the filename to put into the header of the data being encoded.

When decoding, as soon as the called method returns decoded data, this property's value will be changed to the filename in the header of the encoded data.

Data type

BSTR

Default value

Empty string

Remarks

The BinHex format does not support more than 63 characters in a filename.

Applicable methods

Encode, Decode, ProcessFile, ReadFile, WriteFile


HeaderPermissions property

Description

The HeaderPermissions property allows you to get or set the Unix-style file permissions in the header of data being encoded or decoded.

When encoding with the Encode or ReadFile method, this property must be set (unless you are content with the default value) because the library has no way of determining what file permissions should be encoded into the header.

When decoding, as soon as the called method returns decoded data, this property's value will be changed to the permissions contained in the encoded data's header.

Data type

EXBUnixFilePermission

Default value

bupUserRead + bupGroupRead + bupOtherRead

Possible values

Each of these values can be added together to combine multiple permissions.

Value	Description

bupUserRead (256)	Read permission for the user that owns the file.

bupUserWrite (128)	Write permission for the user that owns the file.

bupUserExecute (64)	Execute permission for the user that owns the file.

bupGroupRead (32)	Read permission for the group the file belongs to.

bupGroupWrite (16)	Write permission for the group the file belongs to.

bupGroupExecute (8)	Execute permission for the group the file belongs to.

bupOtherRead (4)	Read permission for all other users.

bupOtherWrite (2)	Write permission for all other users.

bupOtherExecute (1)	Execute permission for all other users.

Applicable methods

Encode, Decode, ProcessFile, ReadFile, WriteFile


How formatting characters are decoded

Encoded text often gets manipulated by applications (such as email applications, messaging servers or XML formatters) which often insert or remove formatting characters or change line lengths. Fortunately, most encoding schemes already allow for this behavior. Here is how the Xceed Binary Encoding Library handles formatting characters:

Character	Hex value	Action

Tab 	0x09	Ignored

Space	0x20	This character is ignored except when UUDecoding, in which case it is interpreted as a reverse apostrophe (`) with hex value 0x60. When decoding with the Quoted-Printable format, spaces after the end-of-line delimiter are ignored.

Form Feed	0x0C	Ignored

Line Feed	0x0A	This character is interpreted as an end-of-line character.

Carriage Return	0x0A	This character is interpreted as an end-of-line character.


EXBUnixFilePermission enumeration

EXCFileProcessing

{

  bupUserRead     = 256,

  bupUserWrite    = 128,

  bupUserExecute  = 64,

  bupGroupRead    = 32,

  bupGroupWrite   = 16,

  bupGroupExecute = 8,

  bupOtherRead    = 4,

  bupOtherWrite   = 2,

  bupOtherExecute = 1

}

This enumeration is used by the HeaderPermissions property. The meaning of each member of this enumeration can be found in this property's topic.


EncodingFormat property

Description

The EncodingFormat property allows you to specify the Encoding Format object that the library will use to encode or decode data.

Data type

An Encoding Format object

Possible values

Value	Encoding Format object description

XceedBase64EncodingFormat 	The Base64 encoding format as defined by RFC-2045 and the XML specification. Used by the MIME format to encode email attachments. Common filename extensions for this format are: .b64

XceedBinHexEncodingFormat 	The BinHex format as defined by RFC-1741. Commonly used on Apple platforms for encoding email attachments. Common filename extensions for this format are: .hqx or .bhx

XceedHexaEncodingFormat 	Plain hexadecimal encoding

XceedQuotedPrintableEncodingFormat 	The quoted-printable format as defined by RFC-2045. Often used to encode text in email

XceedUUEncodingFormat 	The standard Unix UUEncode format. Common filename extensions for this format are: .uue and .uu

XceedXXEncodingFormat 	The XXEncode format. An updated version of UUEncode which defines a better encoded character set. Common filename extensions for this format are: .xxe

Default value

XceedUUEncodingFormat

Applicable methods

Encode, Decode, ProcessFile, ReadFile, WriteFile


XceedUUEncode object
About the XceedUUEncodingFormat object

Description

This object encodes or decodes the standard Unix UUEncode format.

The format was created for transfering binary files between Unix systems. On Windows platforms, this format can be decoded by WinZip and other utilities.

Common filename extensions for this format are: .uue and .uu

Properties

• ContinueOnInvalidData  • EndOfLineType  • HeaderFilename  • HeaderPermissions	• IncludeHeaderFooter  • MaxLineLength  • SubProcessing
COM interfaces

DXceedUUEncodingFormat (Default dual interface)

IXceedUUEncodedingFormat


XceedXXEncode object
About the XceedXXEncodingFormat object

Description

This object encodes or decodes the XXEncode format.

An updated version of UUEncode which defines a better encoded character set On Windows platforms, this format can be decoded by WinZip and other utilities.

Common filename extensions for this format are: .xxe

Properties

• ContinueOnInvalidData  • EndOfLineType  • HeaderFilename  • HeaderPermissions	• IncludeHeaderFooter  • MaxLineLength  • SubProcessing
COM interfaces

DXceedXXEncodingFormat (Default dual interface)

IXceedXXEncodingFormat


XceedBase64Encode object
About the XceedBase64EncodingFormat object

Description

This object encodes or decodes the Base64 encoding format as defined by RFC-2045 and the XML specification.

Used by the MIME format to encode email attachments. On Windows platforms, this format can be decoded by WinZip and other utilities.

Common filename extensions for this format are: .b64

Properties

• ContinueOnInvalidData  • EndOfLineType	• MaxLineLength  • SubProcessing
COM interfaces

DXceedBase64EncodingFormat (Default dual interface)

IXceedBase64EncodingFormat


XceedHexaEncode object
About the XceedHexaEncodingFormat object

Description

This object encodes or decodes plain hexadecimal text.

Properties

• ContinueOnInvalidData  • EndOfLineType	• MaxLineLength  • SubProcessing
COM interfaces

DXceedHexaEncodingFormat (Default dual interface)

IXceedHexaEncodingFormat


XceedQuotedPrintableEncode object
About the XceedQuotedPrintableEncodingFormat object

Description

This object encodes or decodes the Quoted-Printable format as defined by RFC-2045.

Often used to encode text for email.

Properties

• ContinueOnInvalidData  • EndOfLineType	• MaxLineLength  • SubProcessing
COM interfaces

DXceedQuotedPrintableEncodingFormat (Default dual interface)

IXceedQuotedPrintableEncodingFormat


XceedBinHexEncode object
About the XceedBinHexEncodingFormat object

Description

This object encodes or decodes the BinHex format as defined by RFC-1741.

Commonly used on Apple platforms for encoding email attachments On Windows platforms, this format can be decoded by WinZip and other utilities.

Common filename extensions for this format are: .hqx or .bhx

Properties

• ContinueOnInvalidData  • EndOfLineType  • HeaderCreator  • HeaderFilename  • HeaderDataForkLength  • HeaderFlags	• HeaderRessourceForkLength  • HeaderType  • IncludeHeaderFooter  • MaxLineLength  • SubProcessing
COM interfaces

DXceedBinHexEncodingFormat (Default dual interface)

IXceedBinHexEncodingFormat


About the Encoding Objects
About the Encoding Format objects

Introduction

An Encoding Format object handles the encoding or decoding of a specific type of encoding format, such as the UUEncode or the Base64 format. Each Encoding Format object has its own specific properties depending on the particularities of the format that it handles. You can set these properties to determine how the library will handle encoding or decoding data for a specific format.

How to use

After instantiating the Encoding Format object you need and optionally setting its properties, you must assign it to the EncodingFormat property. After that you can call any of the library's methods.

Available Encoding Format objects

•	XceedBase64EncodingFormat

•	XceedBinHexEncodingFormat

•	XceedHexaEncodingFormat

•	XceedQuotedPrintableEncodingFormat

•	XceedUUEncodingFormat

•	XceedXXEncodingFormat


SubProcessing property

Description

The SubProcessing property allows you to efficiently preprocess or postprocess data by using other compatible Xceed components before encoding it or decoding it.

Currently, the other compatible Xceed components include the Xceed Streaming Compression Library and the Xceed Encryption Library. To use them, you must install them on your system.

The SubProcessing property can be assigned any formatting object from these other libraries. For example, you can assign to this property an XceedGZIPCompressionFormat object from the Xceed Streaming Compression Library, or an XceedRijndaelEncryptionFormat object from the Xceed Encryption Library.

When you are encoding, the object assigned to the SubProcessing property will preprocess the data before it is encoded by the Xceed Binary Encoding Library. If a compression formating object is assigned to this property, it will compress the data before it is encoded. If an encryption formatting object is assigned, it will encrypt the data before it is encoded.

When you are decoding, the object assigned to the SubProcessing property will postprocess the data after it is decoded by the Xceed Binary Encoding Library. If a compression formating object is assigned to this property, it will decompress the data after it is decoded. If an encryption formatting object is assigned, it will decrypt the data after it is decoded.

You can chain together multiple libraries in this way, by setting the SubProcessing property of the compression or encryption formatting object that you are assigning to the encoding formatting object's SubProcessing property.

Data type

Any formatting object from another compatible Xceed component.

Default value

Null

Applicable methods

Encode, Decode, ProcessFile, ReadFile, WriteFile


HeaderType property

Description

The HeaderType property allows you set (when encoding) or get (when decoding) a 4-byte value that represents the Macintosh OS-specific file type of the file contained in the BinHex-encoded data. This value has the same purpose as a file extension does on the Windows platform.

Data type

Byte array (Fixed at 4 elements)

Default value

{0, 0, 0, 0}


HeaderCreator property

Description

The HeaderCreator property allows you to set (when encoding) or get (when decoding) the 4-byte identification code of the application that created the file contained in the BinHex-encoded data. This 4-byte identification code is a Macintosh OS-specific value.

Data type

Byte array (Fixed at 4 elements)

Default value

{0, 0, 0, 0}


HeaderFlags property

Description

The HeaderFlags property allows you to set (when encoding) or get (when decoding) a 2-byte value that represents the Macintosh OS-specific file attributes of the file contained in the BinHex-encoded data.

When decoding, the value of this property is changed only after the first byte of data has been decoded.

Data type

WORD

Default value

0


HeaderDataForkLen property
HeaderDataForkLength property

Description

The HeaderDataForkLength property allows you to set (when encoding) or get (when decoding) the length of the Data Fork section of the BinHex-encoded data.

When encoding and the IncludeHeaderFooter property is set to True, the value of the HeaderDataForkLen property + the value of the HeaderResourceForkLength property must equal the amount of bytes you provide to the library to encode.

Data type

DWORD

Default value

0


HeaderRessourceForkLen property
HeaderResourceForkLength property

Description

The HeaderResourceForkLength property allows you set (when encoding) or get (when decoding) the length of the Resource Fork section of the BinHex-encoded data.

When encoding, the value of this property + the value of the HeaderDataForkLength property must equal the amount of bytes you provide to the library to encode.

Data type

DWORD

Default value

0


Encoding entirely in memory (VB example)

' This sample encodes data in memory with the Base64 encoding format

Dim xBinEncode As New XceedBinaryEncoding

Dim vaEncoded As Variant

Dim vaSource As Variant

Set xBinEncode.EncodingFormat = New XceedBase64EncodingFormat

vaSource = "This is the text to encode!"

On Error Resume Next

vaEncoded = xBinEncode.Encode(vaSource, True)

If Err.Number <> 0 Then

  Call MsgBox("Error " & Err.Number & " " & Err.Description)

Else

  Call MsgBox("Data encoded successfully!")

End If

On Error Goto 0

Set xBinEncode = Nothing


Encoding entirely in memory (Delphi example)

{ This sample encodes data in memory with the Base64 encoding format }

uses XceedBinaryEncodingLib_TLB

var

  xBinEncode    : TXceedBinaryEncoding;

  xBase64Format : XceedBase64EncodingFormat;

  vaSource      : OleVariant;

  vaEncoded     : OleVariant;

begin

  xBinEncode := TXceedBinaryEncoding.Create( self );

  xBase64Format := CoXceedBase64EncodingFormat.Create();

  xBinEncode.EncodingFormat := xBase64Format;

  vaSource := 'This is the data to encode!';

  try

    vaEncoded := xBinEncode.Encode( vaSource, true );

    ShowMessage( 'Data encoded successfully!' );

  except

    on xErr : Exception do

      ShowMessage( xErr.Message );

  end;

  xBinEncode.Free();

end;


Encoding entirely in memory (VC++ example)

The first portion of code demonstrates encoding, the second demonstrates decoding.

// This sample encodes data entirely in memory with the UUEncode format

// This code uses the #import directive.

// Put the following line at the beginning of your module

#import "XCEEDBEN.DLL" no_namespace named_guids

CoInitialize( NULL );

try

{

  IXceedBinaryEncodingPtr piBinEncoder;

  piBinEncoder.CreateInstance( CLSID_XceedBinaryEncoding );

  IXceedUUEncodingFormatPtr piUUEncode;

  piUUEncode.CreateInstance( CLSID_XceedUUEncodingFormat );

  piUUEncode->IncludeHeaderFooter = FALSE;

  piBinEncoder->EncodingFormat = IXceedEncodeDataPtr( piUUEncode );

  char* pcSource = "This is the data to encode";

  BYTE* pcEncoded = NULL;

  DWORD dwEncodedSize;

  piBinEncoder->Encode( ( BYTE* )pcSource, lstrlen( pcSource ), TRUE, &pcEncoded, &dwEncodedSize );

  MessageBox( NULL, "Encoding successful!", "Encoding result", MB_OK );

  CoTaskMemFree( pcEncoded );

}

catch( const _com_error& xErr )

{

  char szMsg[250];

  wsprintf( szMsg, "Error %08x\n%s", xErr.Error(),(char*)xErr.Description() );

  MessageBox( NULL, szMsg, "Error", MB_OK );

}

catch( ... )

{

  MessageBox( NULL, "Unknown error", "Error", MB_OK );

}

CoUninitialize();

// This sample decodes data entirely in memory with the UUEncode format

// This code uses the #import directive.

// Put the following line at the beginning of your module

#import "XCEEDBEN.DLL" no_namespace named_guids

CoInitialize( NULL );

try

{

  IXceedBinaryEncodingPtr piBinEncoder;

  piBinEncoder.CreateInstance( CLSID_XceedBinaryEncoding );

  IXceedUUEncodingFormatPtr piUUEncode;

  piUUEncode.CreateInstance( CLSID_XceedUUEncodingFormat );

  piUUEncode->IncludeHeaderFooter = FALSE;

  piBinEncoder->EncodingFormat = IXceedEncodeDataPtr( piUUEncode );

  BYTE* pcDecoded = NULL;

  DWORD dwDecodedSize;

  //"This is the encoded data"

  char* pcEncoded = "85&AI<R!I<R!T:&4@96YC;V1E9\"!D871A";

  piBinEncoder->Decode( ( BYTE* )pcEncoded, lstrlen( pcEncoded ), TRUE, &pcDecoded, &dwDecodedSize );

  MessageBox( NULL, "Decoding successful!", "Decoding result", MB_OK );

  CoTaskMemFree( pcDecoded );

}

catch( const _com_error& xErr )

{

  char szMsg[50];

  wsprintf( szMsg, "Error %08x\n", xErr.Error() );

  MessageBox( NULL, szMsg, "Error", MB_OK );

}

catch( ... )

{

  MessageBox( NULL, "Unknown error", "Error", MB_OK );

}

CoUninitialize();


Unlocking the free trial version

To unlock the free trial version, thereby converting it into a registered version, select the 'License this component' item found in the Start -> Programs -> Xceed Components -> Xceed Binary Encoding Library menu, then enter the registered license key provided to you by Xceed Software or an authorized Xceed component reseller.

Users that were calling the License method with their free trial license key must now call the method with their registered license key in order to unlock the library.

If you are using Delphi, C++Builder or any other language that generates an wrapper for ActiveX components, you must re-install your component or use the License method if you have registered your product after using the free trial version.


Manager Sample Application for VB6

Introduction

This sample demonstrates how to encode and decode single files using different kinds of encoding methods.

Project path

Project path: SAMPLES\VISUAL BASIC\MANAGER

Project file name: MANAGER.VBP

Demonstrates

Properties: EndOfLineType, MaxLineLength, ContinueOnInvalidData, HeaderDataForkLength, HeaderResourceForkLength, HeaderFilename, EncodingFormat and IncludeHeaderFooter from the various Encoding format objects.

Methods: ProcessFile

How to use

The form contains two tabs. One for encoding and one for decoding.

Encoding: Specify the source path and file name of the file to encode, the destination file name and the encoding method to use and click the Encode button. When you type the source file name, if the destination file name is empty, it will automatically be set to the same filename as the source, but with the appropriate filename extension depending on the selected encoding method.

Decoding: Select one or more encoded files. These files are added to the list box. Select a destination path and a file name to decode to. The sample will decode all these files into a single destination file. All source files must therefore be encoded using the same encoding method. If the destination file name is left empty, the sample will automatically select a file name when decoding the first file from the list. Click the Decode button to begin the process.

From the menu bar, you can access the Option form. This form allows you to set the maximum line length, the end of line type and also lets you specify if the library should continue if it encounters invalid data when decoding.

All errors that occur when encoding or decoding are shown in a text box at the bottom of the main form.

Delphi and C++ Builder: [From the main form you can also set various options. That is, the maximum line length, the end of line type and specify if the library should continue if it encounters invalid data when decoding.]


Manager Sample Application for Delphi

Introduction

This sample demonstrates how to encode and decode single files using different kinds of encoding methods.

Project file

Project path : SAMPLES\DELPHI\MANAGER

Project file name : MANAGER.DPR

Demonstrates

Properties: EndOfLineType, MaxLineLength, ContinueOnInvalidData, HeaderDataForkLength, HeaderResourceForkLength, HeaderFilename, EncodingFormat and IncludeHeaderFooter from the various Encoding format objects.

Methods: ProcessFile

How to use

The form contains two tabs. One for encoding and one for decoding.

Encoding: Specify the source path and file name of the file to encode, the destination file name and the encoding method to use and click the Encode button. When you type the source file name, if the destination file name is empty, it will automatically be set to the same filename as the source, but with the appropriate filename extension depending on the selected encoding method.

Decoding: Select one or more encoded files. These files are added to the list box. Select a destination path and a file name to decode to. The sample will decode all these files into a single destination file. All source files must therefore be encoded using the same encoding method. If the destination file name is left empty, the sample will automatically select a file name when decoding the first file from the list. Click the Decode button to begin the process.

Various other options can be set from the main form. This includes the maximum line length, the end of line type and also the choice of wether or not the library should continue if it encounters invalid data when decoding.

All errors that occur when encoding or decoding are shown in a text box at the bottom of the main form.


Manager Sample Application for C++Builder

Introduction

This sample demonstrates how to encode and decode single files using different kinds of encoding methods.

Project file

Project path : SAMPLES\C++BUILDER\MANAGER

Project file name : MANAGER.BPR

Demonstrates

Properties: EndOfLineType, MaxLineLength, ContinueOnInvalidData, HeaderDataForkLength, HeaderResourceForkLength, HeaderFilename, EncodingFormat and IncludeHeaderFooter from the various Encoding format objects.

Methods: ProcessFile

How to use

The form contains two tabs. One for encoding and one for decoding.

Encoding: Specify the source path and file name of the file to encode, the destination file name and the encoding method to use and click the Encode button. When you type the source file name, if the destination file name is empty, it will automatically be set to the same filename as the source, but with the appropriate filename extension depending on the selected encoding method.

Decoding: Select one or more encoded files. These files are added to the list box. Select a destination path and a file name to decode to. The sample will decode all these files into a single destination file. All source files must therefore be encoded using the same encoding method. If the destination file name is left empty, the sample will automatically select a file name when decoding the first file from the list. Click the Decode button to begin the process.

Various other options can be set from the main form. This includes the maximum line length, the end of line type and also the choice of wether or not the library should continue if it encounters invalid data when decoding.

All errors that occur when encoding or decoding are shown in a text box at the bottom of the main form.


Memory Encode Sample Application for VB6

Introduction

This sample demonstrates how to encode and decode a block of memory data using different kinds of encoding methods.

Project path

Project path: SAMPLES\VISUAL BASIC\MEMORYENCODE

Project file name: MEMORYENCODE.VBP

Demonstrates

Properties: ContinueOnInvalidData, IncludeHeaderFooter, EndOfLineType, MaxLineLength, HeaderDataForkLength, HeaderResourceForkLength and EncodingFormat from the various Encoding format interfaces.

Methods: Encode and Decode

How to use

Select the encoding method and the end-of-line type using the two combo boxes. Next, set set the maximum line length (meaningful only if the end-of-line type is not "None"). Type the text to encode in the "Decoded text" text box and click Encode to fill the "Encoded text" text box with the encoded results. You can click the Decode button to reverse the process (something has to be in the "Encoded text" box for this to work). The main form contains two labels that indicate the size of the decoded text and the size (in characters) of the encoded text.


Memory Encode Sample Application for Delphi

Introduction

This sample demonstrates how to encode and decode a block of memory data using different kinds of encoding methods.

Project path

Project path: SAMPLES\DELPHI\MEMORYENCODE

Project file name : MEMORYENCODE.DPR

Demonstrates

Properties: ContinueOnInvalidData, IncludeHeaderFooter, EndOfLineType, MaxLineLength, HeaderDataForkLength, HeaderResourceForkLength and EncodingFormat from the various Encoding format interfaces.

Methods: Encode and Decode

How to use

Select the encoding method and the end-of-line type using the two combo boxes. Next, set set the maximum line length (meaningful only if the end-of-line type is not "None"). Type the text to encode in the "Decoded text" text box and click Encode to fill the "Encoded text" text box with the encoded results. You can click the Decode button to reverse the process (something has to be in the "Encoded text" box for this to work). The main form contains two labels that indicate the size of the decoded text and the size (in characters) of the encoded text.


Memory Encode Sample Application for C++Builder

Introduction

This sample demonstrates how to encode and decode a block of memory data using different kinds of encoding methods.

Project path

Project path: SAMPLES\C++BUILDER\MEMORYENCODE

Project file name: MEMORYENCODE.BPR

Demonstrates

Properties: ContinueOnInvalidData, IncludeHeaderFooter, EndOfLineType, MaxLineLength, HeaderDataForkLength, HeaderResourceForkLength and EncodingFormat from the various Encoding format interfaces.

Methods: Encode and Decode

How to use

Select the encoding method and the end-of-line type using the two combo boxes. Next, set set the maximum line length (meaningful only if the end-of-line type is not "None"). Type the text to encode in the "Decoded text" text box and click Encode to fill the "Encoded text" text box with the encoded results. You can click the Decode button to reverse the process (something has to be in the "Encoded text" box for this to work). The main form contains two labels that indicate the size of the decoded text and the size (in characters) of the encoded text.


Memory Encode Sample Application for Visual C++ with MFC

Introduction

This sample demonstrates how to encode and decode a block of memory data using different kinds of encoding methods.

Project path

Project path: SAMPLES\VISUAL C++ MFC\MEMORYENCODE

Project file name: MEMORYENCODE.DSP

Demonstrates

Properties: ContinueOnInvalidData, IncludeHeaderFooter, EndOfLineType, MaxLineLength, HeaderDataForkLength, HeaderResourceForkLength and EncodingFormat from the various Encoding format interfaces.

Methods: Encode and Decode

How to use

Select the encoding method and the end-of-line type using the two combo boxes. Next, set set the maximum line length (meaningful only if the end-of-line type is not "None"). Type the text to encode in the "Decoded text" text box and click Encode to fill the "Encoded text" text box with the encoded results. You can click the Decode button to reverse the process (something has to be in the "Encoded text" box for this to work). The main form contains two labels that indicate the size of the decoded text and the size (in characters) of the encoded text.


Encode Sample Application for Visual C++

Introduction

This sample demonstrates how to encode a file using different kinds of encoding methods.

Project path

Project path: SAMPLES\VISUAL C++\ENCODE

Project file name: ENCODE.DSP

Demonstrates

Properties: EndOfLineType, MaxLineLength, EncodingFormat,  DataFormating, HeaderDataForkLen and HeaderResourceForkLen from the various Encoding format interfaces.

Method: ReadFile and ProcessFile

How to use

This sample is a console application that takes at least one parameter (the source file name) to perform encoding. The sample's command-line usage specifications are:

Encode [options] input_file [output_file]

The parameters between brackets are optional. The option parameter can be used to specify the encoding method, the end of line type and the max line length. If omitted, these options are set to UUEncoding, CrLf and 78 characters respectively. If the output file name is omitted, the encoded output is sent to the screen.


Decode Sample Application for Visual C++

Introduction

This sample demonstrates how to decode a file using different kinds of encoding methods.

Project path

Project path: SAMPLES\VISUAL C++\DECODE

Project file name : DECODE.DSP

Demonstrates

Properties used : ContinueOnInvalidData, DataFormating and EncodingFormat.

Method used : ReadFile and ProcessFile

How to use

This sample is a console application that takes at least one parameter (the source file name) to perform decoding. The sample's command-line usage specifications are:

Decode [options] input_file [output_file]

The parameters between brackets are optional. The option parameter can be used to specify the encoding method and if the decoding should continue if it encounters invalid data. If omitted, these options are set to UUEncoding and No respectively. If the output file name is omitted, the decoded output is sent to the screen.


Encoding from file to file (VC++ example)

The first portion of code demonstrates encoding, the second demonstrates decoding.

// This sample encodes with the UUEncode format from one file to another

// This code uses the #import directive.

// Put the following line at the beginning of your module

#import "XCEEDBEN.DLL" no_namespace named_guids

CoInitialize( NULL );

try

{

  IXceedBinaryEncodingPtr piBinEncoder;

  piBinEncoder.CreateInstance( CLSID_XceedBinaryEncoding );

  IXceedUUEncodingFormatPtr piUUEncode;

  piUUEncode.CreateInstance( CLSID_XceedUUEncodingFormat );

  piUUEncode->HeaderFilename = "source.txt"; // This will embed the original filename into the encoded data

  piBinEncoder->EncodingFormat = IXceedEncodeDataPtr( piUUEncode );

  DWORD dwBytesRead;

  DWORD dwBytesWritten;

  piBinEncoder->ProcessFile( "c:\\temp\\source.txt", 0, 0, bfpEncode, TRUE, "c:\\temp\\encoded.uue", FALSE, &dwBytesRead, &dwBytesWritten );

  MessageBox( NULL, "Encoding successful!", "Encoding result", MB_OK );

}

catch( const _com_error& xErr )

{

  char szMsg[250];

  wsprintf( szMsg, "Error %08x\n%s", xErr.Error(),(char*)xErr.Description() );

  MessageBox( NULL, szMsg, "Error", MB_OK );

}

catch( ... )

{

  MessageBox( NULL, "Unknown error", "Error", MB_OK );

}

CoUninitialize();

// This sample decodes UUEncoded data from one file to another

// This code uses the #import directive.

// Put the following line at the beginning of your module

#import "XCEEDBEN.DLL" no_namespace named_guids

CoInitialize( NULL );

try

{

  IXceedBinaryEncodingPtr piBinEncoder;

  piBinEncoder.CreateInstance( CLSID_XceedBinaryEncoding );

  IXceedUUEncodingFormatPtr piUUEncode;

  piUUEncode.CreateInstance( CLSID_XceedUUEncodingFormat );

  piBinEncoder->EncodingFormat = IXceedEncodeDataPtr( piUUEncode );

  DWORD dwBytesRead;

  DWORD dwBytesWritten;

  piBinEncoder->ProcessFile( "c:\\temp\\encoded.uue", 0, 0, bfpDecode, TRUE, "c:\\temp\\decoded.txt", FALSE, &dwBytesRead, &dwBytesWritten );

  // If you only specify a path in the above call (terminated with a \)

  // the filename that's embedded into the encoded data will be used.

  MessageBox( NULL, "Decoding successful!", "Decoding result", MB_OK );

}

catch( const _com_error& xErr )

{

  char szMsg[50];

  wsprintf( szMsg, "Error %08x\n", xErr.Error() );

  MessageBox( NULL, szMsg, "Error", MB_OK );

}

catch( ... )

{

  MessageBox( NULL, "Unknown error", "Error", MB_OK );

}

CoUninitialize();


Encoding from file to memory (VC++ example)

// This sample encodes data to Base64 from a file to a memory buffer

// This code uses the #import directive.

// Put the following line at the beginning of your module

#import "XCEEDBEN.DLL" no_namespace named_guids

CoInitialize( NULL );

try

{

  IXceedBinaryEncodingPtr piBinEncoder;

  piBinEncoder.CreateInstance( CLSID_XceedBinaryEncoding );

  IXceedBase64EncodingFormatPtr piBase64Encode;

  piBase64Encode.CreateInstance( CLSID_XceedBase64EncodingFormat );

  piBinEncoder->EncodingFormat = IXceedEncodeDataPtr( piBase64Encode );

  BYTE* pcData = NULL;

  DWORD dwDataSize;

  DWORD dwBytesRead;

  piBinEncoder->ReadFile( "c:\\temp\\source.txt", 0, 0, bfpEncode, TRUE, &dwBytesRead, &pcData, &dwDataSize );

  MessageBox( NULL, "Encoding successful!", "Encoding result", MB_OK );

  CoTaskMemFree( pcData );

}

catch( const _com_error& xErr )

{

  char szMsg[250];

  wsprintf( szMsg, "Error %08x\n%s", xErr.Error(),(char*)xErr.Description() );

  MessageBox( NULL, szMsg, "Error", MB_OK );

}

catch( ... )

{

  MessageBox( NULL, "Unknown error", "Error", MB_OK );

}

CoUninitialize();


Encoding from memory to file (VC++ example)

// This sample encodes data (using Base64) from memory to a file

// This code uses the #import directive.

// Put the following line at the beginning of your module

#import "XCEEDBEN.DLL" no_namespace named_guids

CoInitialize( NULL );

try

{

  IXceedBinaryEncodingPtr piBinEncoder;

  piBinEncoder.CreateInstance( CLSID_XceedBinaryEncoding );

  IXceedBase64EncodingFormatPtr piBase64Encode;

  piBase64Encode.CreateInstance( CLSID_XceedBase64EncodingFormat );

  piBinEncoder->EncodingFormat = IXceedEncodeDataPtr( piBase64Encode );

  char* pcSource = "This is the data that we will encode";

  DWORD dwBytesWritten;

  piBinEncoder->WriteFile( ( BYTE* )pcSource, lstrlen( pcSource ), bfpEncode, TRUE, "c:\\temp\\destination.b64", FALSE, &dwBytesWritten );

  MessageBox( NULL, "Encoding successful!", "Encoding result", MB_OK );

}

catch( const _com_error& xErr )

{

  char szMsg[250];

  wsprintf( szMsg, "Error %08x\n%s", xErr.Error(),(char*)xErr.Description() );

  MessageBox( NULL, szMsg, "Error", MB_OK );

}

catch( ... )

{

  MessageBox( NULL, "Unknown error", "Error", MB_OK );

}

CoUninitialize();


Encoding from file to file (Delphi example)

The first portion of code demonstrates encoding, the second demonstrates decoding.

{ This sample encodes with the Base64 format from file to file }

uses XceedBinaryEncodingLib_TLB

var

  xBinEncode    : TXceedBinaryEncoding;

  xBase64Format : XceedBase64EncodingFormat;

  vaBytesRead   : OleVariant;

begin

  xBinEncode := TXceedBinaryEncoding.Create( self );

  xBase64Format := CoXceedBase64EncodingFormat.Create();

xBinEncode.EncodingFormat := xBase64Format;

  try

    xBinEncode.ProcessFile( 'c:\temp\source.txt', 0, 0, bfpEncode, true, 'c:\temp\encoded.b64', false, vaBytesRead );

    ShowMessage( 'Encoding successful!' );

  except

    on xErr : Exception do

      ShowMessage( xErr.Message );

  end;

  xBinEncode.Free();

end;

{ This sample decodes with the Base64 format from file to file }

uses XceedBinaryEncodingLib_TLB;

var

  xBinEncode    : TXceedBinaryEncoding;

  xBase64Format : XceedBase64EncodingFormat;

  vaBytesRead   : OleVariant;

begin

  xBinEncode := TXceedBinaryEncoding.Create( self );

  xBase64Format := CoXceedBase64EncodingFormat.Create();

xBinEncode.EncodingFormat := xBase64Format;

  try

    xBinEncode.ProcessFile('c:\temp\encoded.b64', 0, 0, bfpDecode, true, 'c:\temp\destination.txt', false, vaBytesRead );

    ShowMessage( 'Decoding successful!' );

  except

    on xErr : Exception do

      ShowMessage( xErr.Message );

  end;

  xBinEncode.Free();

end;


Encoding from file to memory (Delphi example)

{ This sample encodes with the Base64 format from file to memory }

uses XceedBinaryEncodingLib_TLB;

var

  xBinEncode    : TXceedBinaryEncoding;

  xBase64Format : XceedBase64EncodingFormat;

  vaBytesRead   : OleVariant;

  vaEncoded     : OleVariant;

begin

  xBinEncode := TXceedBinaryEncoding.Create( self );

  xBase64Format := CoXceedBase64EncodingFormat.Create();

xBinEncode.EncodingFormat := xBase64Format;

  try

    vaEncoded := xBinEncode.ReadFile( 'c:\temp\source.txt', 0, 0, bfpEncode, true, vaBytesRead );

    ShowMessage( 'Encoding successful!' );

  except

    on xErr : Exception do

      ShowMessage( xErr.Message );

  end;

  xBinEncode.Free();

end;


Encoding from memory to file (Delphi example)

{ This sample encodes with the Base64 format from memory to a file }

uses XceedBinaryEncodingLib_TLB

var

  xBinEncode    : TXceedBinaryEncoding;

  xBase64Format : XceedBase64EncodingFormat;

  vaData     : OleVariant;

begin

  xBinEncode := TXceedBinaryEncoding.Create( self );

  xBase64Format := CoXceedBase64EncodingFormat.Create();

  xBinEncode.EncodingFormat := xBase64Format;

  vaData := 'This is the text to encode';

  try

    xBinEncode.WriteFile( vaData, bfpEncode, true, 'c:\temp\encoded.b64', false );

    ShowMessage( 'Encoding successful!' );

  except

    on xErr : Exception do

      ShowMessage( xErr.Message );

  end;

  xBinEncode.Free();

end;


Encoding from file to file (VB example)

The first portion of code demonstrates encoding, the second demonstrates decoding.

' This sample encodes with the Base64 format from one file to another

Dim xBinEncode As New XceedBinaryEncoding

Dim vaBytesRead As Variant

Set xBinEncode.EncodingFormat = New XceedBase64EncodingFormat

On Error Resume Next

Call xBinEncode.ProcessFile("c:\temp\source.txt", 0, 0, bfpEncode, True, "c:\temp\encoded.b64", False, vaBytesRead)

If Err.Number = 0 Then

  Call MsgBox("File encoded successfully!")

Else

  Call MsgBox(Err.Description)

End If

On Error Goto 0

Set xBinEncode = Nothing

' This sample decodes with the Base64 format from one file to another

Dim xBinEncode As New XceedBinaryEncoding

Dim vaBytesRead As Variant

Set xBinEncode.EncodingFormat = New XceedBase64EncodingFormat

On Error Resume Next

Call xBinEncode.ProcessFile("c:\temp\encoded.b64", 0, 0, bfpDecode, True, "c:\temp\decoded.txt", False, vaBytesRead)

If Err.Number = 0 Then

  Call MsgBox("File decoded successfully!")

Else

  Call MsgBox(Err.Description)

End If

On Error Goto 0

xBinEncode = Nothing


Encoding from file to memory (VB example)

' This sample encodes with the Base64 format from a file to memory

Dim xBinEncode As New XceedBinaryEncoding

Dim vaBytesRead As Variant

Dim vaEncoded As Variant

Set xBinEncode.EncodingFormat = New XceedBase64EncodingFormat

On Error Resume Next

vaEncoded = xBinEncode.ReadFile("c:\temp\source.txt", 0, 0, bfpEncode, True, vaBytesRead)

If Err.Number = 0 Then

  Call MsgBox("File encoded successfully!")

Else

  Call MsgBox(Err.Description)

End If

On Error Goto 0

Set xBinEncode = Nothing


Encoding from memory to file (VB example)

' This sample encodes with the Base64 format from memory to a file

Dim xBinEncode As New XceedBinaryEncoding

Dim vaData As Variant

Set xBinEncode.EncodingFormat = New XceedBase64EncodingFormat

vaData = "This is the data to encode"

On Error Resume Next

Call xBinEncode.WriteFile(vaData, bfpEncode, True, "c:\temp\encoded.b64", False)

If Err.Number = 0 Then

  Call MsgBox("Data encoded successfully!")

Else

  Call MsgBox(Err.Description)

End If

On Error Goto 0

Set xBinEncode = Nothing


Streaming encoding from file to memory (VB example)

' This example encodes data in the Base64 format

' from a file to memory in 8K (8192 byte) chunks.

Const CHUNKSIZE = 8192

Dim xEncode As New XceedBinaryEncoding

Dim lOffSet As Long

Dim lFileSize As Long

Dim vaBytesRead As Variant

Dim vaEncoded As Variant

Set xEncode.EncodingFormat = New XceedBase64EncodingFormat

lOffSet = 0 ' We must track the current offset

On Error Resume Next

lFileSize = FileLen("c:\temp\source.txt")

While lOffSet < lFileSize

  'bEndOfData will be true if the current offset + CHUNKSIZE exceeds the

  'end of the file.

  vaEncoded = xEncode.ReadFile("c:\temp\source.txt", lOffSet, CHUNKSIZE, bfpEncode, (lOffSet + CHUNKSIZE >= lFileSize), vaBytesRead)

  If Not IsEmpty(vaEncoded) Then

    ' You now have a portion of encoded data you can use.

    ' For example, transfer it, process it, etc.

  End If

  lOffSet = lOffSet + vaBytesRead

Wend

If Err.Number = 0 Then

  MsgBox "Finished encoding file to memory."

Else

  MsgBox Err.Number & "  " & Err.Description

End If