Creating and Using Cabinet Files for Java Applets and Libraries Previous
Previous		 About Tools
About Tools		 Index
Index

Introduction to Cabarc

Using Cabinets with Java Files , Using the Cabarc Utility

Cabarc is a utility that creates, extracts, and lists the contents of cabinet files (.cab files). Cabarc uses a command-line interface similar to that of popular archiving tools. Cabarc supports wildcards and recursive directory searches.

The cabinet format is an efficient way to package multiple files. The cabinet format has two key features: multiple files can be stored in a single cabinet (.cab file) and data compression is performed across file boundaries, which significantly improves the compression ratio. Cabinet file construction can be designed around the number of files to be compressed and the expected patterns for gaining access to them (sequential, random, all at once, or a few at a time).

A key concept of the cabinet file is the folder. A folder is a collection of one or more compressed files that are compressed together as a single entity. Compressing files this way improves the compression ratio. Random access time suffers, however, because decoding (decompressing) any file in a folder requires that all preceding files in that folder must also be decoded. The focus is on maximum compression as opposed to quick decompression, since the cabinet format is designed to deliver file content, such as installable software or Java classes, rather than to stream media.


Using Cabinets with Java Files

There are two reasons to use the cabinet technology with Java classes. The first reason is if you are building Java applets with lots of classes and graphics or audio files that you would like compressed and which would not be shared by other sites. This group is referred to here as the "applet" group, referring to the <APPLET> HTML tag that is used to access the contents of the cabinet file.

The second reason is to distribute your Java class libraries to users so that your classes can be accessed like system classes by Java applets or applications. HTML pages that download cabinets containing library files use the <OBJECT> tag to download and access the libraries. Note that the library scheme only supports the download and access of class files, not images or audio, which should be provided by the applet and not the cabinet file. This is because class files are typically shared between applets, whereas image and audio files are not.

Archiving Applets and Multimedia files

The following will help you create a cabinet file for delivering compressed class and multimedia files to a user's system:

  1. Make sure that the SDK-Java\Bin directory, which contains Cabarc.exe, is in your path.
  2. Run Cabarc.exe to build a cabinet containing all of your files. See the section of this article for command-line syntax for the cabarc tool.
  3. Optionally, digitally sign the cabinet file.

    Code-signing is important for users, so that they know to trust your code before placing it on their computers. The default settings in Internet Explorer will reject unsigned code. For the latest information on how to get your code signed, check http://www.microsoft.com/workshop External Link

When creating cabinets which will be read by the browser from the CABBASE parameter, make sure to use the default compression mode (MSZIP) and not the new LZX compression mode, which is not supported by Internet Explorer 3.xx.

Archiving Library Files

When delivering libraries in a cabinet file, the files to be compressed and delivered are archived in one cabinet file (called the inner cabinet), which is itself archived in another cabinet file (called the outer cabinet), along with an .inf file. The .inf file, based on the Master.inf template found in the SDK-Java\Bin directory, is used by the setup engine in Internet Explorer, so it contains the names of the libraries, where the libraries should be placed, the class identifier used in the <OBJECT> tag, and so on. The use of the .inf file only pertains to libraries, which are referenced using the <OBJECT> HTML tag, and does not pertain to applets.

Information for the Master.inf Template

For Java libraries, you will need to gather the following information to fill out the .inf file copied from the Master.inf template (found in the SDK-Java\Bin directory):

Optionally, you can use the following information:

Instructions for Building Cabinet Files for Libraries

The following steps will help you create a cabinet file for installing Java libraries on a user's computer:

  1. Make sure that the SDK-Java\Bin directory, which contains Cabarc.exe, is in your path.
  2. Run Cabarc.exe to build your cabinet containing all of your class files. For command-line syntax for the cabarc tool, see the section of this article. It is recommended that your vendor name be at the beginning of all your classes to avoid having them overwritten. For example, your classes should be in the form suggested by the following example (where "vendor" is your unique vendor name): 
    
		vendor.util.loader.class
		vendor.util.builder.class
		vendor.applet.start.class

    Say your company is called CoolTools. You have a package called "widgets" located on your development computer at c:\JavaCode\CoolTools\Widgets\*.class. You want to install this package in the user's <windir>\Windows\Java\Lib directory. You would change directory to c:\JavaCode\ and run cabarc as follows: 

    
cabarc -r -p -P javacode\ n CTClasses.cab CoolTools\*.*

    This syntax tells cabarc to recursively (-r) archive everything under CoolTools, maintaining the directory structure (-p) but stripping off javacode from directories (-P javacode\) and creating a cabinet file called CTClasses.cab.

    When this is installed on the user's system, all classes would be placed under the <windir>\Java\Lib unless the .inf file was modified to place them in the TrustLib directory.

  3. Make a copy of the Master.inf template in the SDK-Java\Bin directory and edit the copy. This sets up the layout and instructions for installing the libraries. The Master.inf file is heavily commented and includes places to put the information you have gathered. For details about what goes into this file, see .

    Remember to run the Guidgen tool to create a ClassId and copy it into the correct place in the .inf file.

    Following on with the CoolTools example, you would create a file (say, Cool.inf) based on Master.inf, create a ClassId using Guidgen and copy it into the file, and then edit the name of the .inf file and the .cab file in Cool.inf.

    The following code excerpt from the Cool.inf file shows the mandatory edits that must be made. 

    
[hook1]

; In this line, replace CabFileName.cab with the your CAB file name

run=extrac32.exe /e /a /y /l %49000% CTClasses.cab 

[hook2]

; Change the name of master.inf to the name you are assigning this
; file. Leave the second line alone.

InfFile=cool.inf
InfSection=RegistryData


[Strings]
; Running uuidgen in the SDK generates the ClassId you need to fill 
; in here. This classId also goes in the OBJECT tag.
; Don't forget the set braces!

ClassId="{4439E200-6FCC-11d0-89AA-00A0C9054129}"

; Put the name by which your packages should be referred to 
; (i.e. "Bob's Text Viewer") here.

PackageName="CoolTool Java Classes"
  4. Run Cabarc.exe again to build the cabinet file containing the class cabinet and the .inf file (and any other files you might want to include). The following example demonstrates how a cabinet file called CoolDown.cab, which includes the Cool.inf and the CTClasses.cab files. In this example, the 6144 leaves space for a digital signature. 
    
       cabarc -s 6144 n CoolDown.cab CTClasses.cab Cool.inf
  5. Digitally sign the cabinet file.

    Code-signing is important for users, so that they know to trust your code before placing it on their machines. The default settings in Internet Explorer will reject unsigned code. Check http://www.microsoft.com/workshopExternal Link for the latest information on how to get your code signed.


Accessing the Cabinet from the Web Page

For Java applets, you use the CABBASE parameter in an APPLET tag to point to the .cab file. If the applet is not already present on the user's system, the .cab file is downloaded, the contents extracted, and the applet started.

To use the APPLET tag, you set the parameters as shown in the following example: 


<APPLET CODE="sample.class" WIDTH=100 HEIGHT=100>
<PARAM NAME="cabbase" VALUE="vendor.cab">
</APPLET>

Using the CABBASE parameter does not conflict with CODEBASE or any other parameters necessary for other browsers. Using CABBASE along with the other tags allows Internet Explorer 3.0 and other CAB-supporting browsers to use .cab files without impeding the ability of other browsers to download and execute applets.

For Java libraries, you use the OBJECT tag to point to the .cab file. If the classes (in the current version) are not already present on the user's system, the .cab file is downloaded and the contents extracted and placed in the appropriate location on the user's system. This should be done according to following syntax: 


<OBJECT CLASSID="<classid>" CODEBASE="<path to cab>#Version=x,x,x,x">
</OBJECT>

For example: 


<OBJECT 
    CLASSID="clsid:12345678-9abc-def1-1234567890ab" 
    CODEBASE="cabs/vendor.cab#Version=1,0,0,12">
</OBJECT>

As in the preceding example, the CODEBASE attribute can specify a version number, allowing the libraries to be downloaded and installed if the version on the user's system is out-of-date.

Both the ClassId and the version number are also stored in the .inf file inside the outer cabinet file. The version number is optional, but highly recommended. This installs the classes permanently on the user's system, so only use this for libraries.

After libraries are installed in this manner, APPLET tags can refer to the classes placed in the library specified by Cabs/Vendor.cab. Those applets work like normal, with classes brought in through CABBASE or CODEBASE. >


Using the Cabarc Utility

Cabinets are created using the n command, followed by the name of the cabinet to create, followed by a file name list. This is shown in the following example: 

cabarc n mycab.cab prog.c prog.h prog.exe readme.txt

The previous command creates the cabinet Mycab.cab containing the files Prog.c, Prog.h, Prog.exe, and Readme.txt, in a single folder, using the default compression mode, MSZIP.

Command Line Usage

Cabarc is used as follows: 

cabarc [<options>] <command> [<file list>]

Three commands are currently supported: n (create new cabinet), l (list contents of an existing cabinet), and x (extract files from a cabinet). These commands are described later in this document.

Using Wildcards

Cabarc supports wildcards in the filename list, as shown in the example below: 

cabarc n mycab.cab prog.* readme.txt

Creating Folders

All files are added to a single folder (compression history) in the cabinet. It is possible to instruct cabarc to begin a new folder by using the plus sign (+) for the file to be added, as shown in the following example: 

cabarc n mycab.cab test.c main.c + test.exe *.obj

The above command creates the cabinet mycab.cab with one folder containing test.c and main.c, and a second folder containing test.exe and all files matching *.obj.

Preserving Directory Paths

By default, directory names are not preserved in the cabinet, only the filename component is stored. For example, the following command stores prog.c in the cabinet: 

cabarc n mycab.cab c:\source\myproj\prog.c

To preserve path names, use the -p option as shown in the following example: 

cabarc -p n mycab.cab c:\mysource\myproj\prog.c

This command puts mysource\myproj\prog.c in the cabinet. Be aware that the c:\ prefix is still stripped from the filename; Cabarc will not allow absolute paths to be stored in the cabinet, nor will it extract such absolute paths.

Stripping Paths

Path stripping is an option, -P, for preserving part (but not all) of a path name. The following example shows how the path stripping option can archive everything in the c:\mysource\myproj\ directory, but store only the myproj\ component of the path. 

cabarc -p -P mysource\ n mycab.cab c:\mysource\myproj\prog.c

The -P option strips any strings that begin with the provided string. Be aware that wildcards are not supported by the -P option; it is a simple text match. Absolute path prefixes, such as c:\ or \, are stripped before the comparison takes place. Do not include absolute path prefixes when using the -P option.

The -P option may be used multiple times to strip out multiple paths. Cabarc builds a list of all paths to be stripped and applies only the first one that matches. Consider the following example: 

cabarc -p -P mysrc\ -P yoursrc\ n mycab.cab c:\mysrc\myproj\*.* d:\yoursrc\yourproj\*.c

The trailing slash at the end of the path name is important: Entering -P mysrc instead of -P mysrc\ would cause files to be added as \myproj\<filename>.

Using Recursive Directory Search

Cabarc can archive files in a directory and all of its subdirectories, by use of the -r option. For example, the following command example archives all files ending in .h that are in c:\msdev\include\, c:\msdev\include\sys, and c:\msdev\include\gl (assuming these directories exist on your system). 

cabarc -r -p n mycab.cab c:\msdev\include\*.h

The -p option is used here to preserve the path information when the files are added to the cabinet. Without this option, only the filename components would be stored, although sometimes it might be desirable behavior to not use -p.

Reserving Space for Code Signature

Cabarc can reserve space in the cabinet for a code signature. This is done with the -s option, which reserves a specified amount of empty space in the cabinet. For code signatures, reserve 6144 bytes. Consider the following example for doing so: 

cabarc -s 6144 n mycab.cab test.exe

Be aware that the -s option does not actually write the code signature; it merely reserves space for it in the cabinet. Use the appropriate code signing utility to fill out the code signature.

Setting the Cabinet ID

Cabinet files have a 16-bit cabinet ID field that is designed for application use. The default value of this field is zero; however, use the -i option of cabarc to set this field to any 16-bit value. Consider the following example: 

cabarc -i 12345 n mycab.cab test.exe

Setting the Compression Type

Set the compression type with the -m option. The default compression type for a cabinet is MSZIP . The three supported compression modes are MSZIP compression (-m MSZIP), no compression (-m NONE), and LZX compression. LZX compression is selected by -m LZX:<w> where <w> is a number in the 15 to 21 range denoting the size of the compression history window, 2 to the power <w>. A larger history window requires more memory when compressing or decompressing, but provides better compression. LZX compression must not be used when creating cabinets which will be read by the browser from the CABBASE parameter, since Internet Explorer 3.xx does not support the LZX compression mode.

The following command stores files in the cabinet with MSZIP compression: 

cabarc -m MSZIP n mycab.c *.*

Using a File List from a File

Cabarc can input its list of files from a text file, instead of from the command line, using the @file option followed by the name of the file from which to take the inputs. Consider the following example: 

cabarc n mycab.cab @file filelist.txt

The text file must list the physical file names of the files to be added, one per line. As is the case when specifying filenames on the command line, the plus (+) symbol can be used as a filename to specify the beginning of a new folder. If a filename contains any embedded spaces, it must be enclosed as quotes, as shown below: 


test.c
myapp.exe
"output file.exe"

Quotation marks are required because each physical filename can be followed (on the same line) by an optional logical filename, which specifies the name under which the file will be stored in the cabinet. Consider the following example: 


test.c myapp.c
myapp.exe
"output file.exe" myfile.exe

If the logical filename contains spaces, it also must be enclosed in quotation marks. Note that the logical filename overrides the -p (preserve path names) and -P (strip path name) options; the file is added to the cabinet exactly as indicated. Wildcards can be used in the physical filename, but in this situation, a logical filename is not allowed.

The @file option can be used multiple times, to retrieve file lists from multiple files. Cabarc does not check for the presence of duplicate files, so if the same physical file appears in multiple file lists, it will be added to the cabinet multiple times.

The @file option can be combined with filenames on the command line. The files from the use of -l option are added first. Consider the following example: 

cabarc -l filelist1.txt -l filelist2.txt n mycab.cab *.c *.h

Note that the @file option is available only when creating cabinets, not when extracting or listing cabinets.

Listing Cabinet Contents

It is possible to view the contents of a cabinet using the L (list) command, as shown below: 

cabarc l mycab.cab

Cabarc displays the cabinet identifier in the cabinet (see the -s option for cabinet creation). Cabarc also displays the following file information: size, date, time, and attributes.

Extracting Files from Cabinets

The X (extract) command extracts files from a cabinet. The simplest use of the X command is shown in the following example, which extracts all files from the cabinet: 

cabarc x mycab.cab

Alternatively, it is possible to selectively extract files by providing a list of filenames and/or wildcards: 

cabarc x mycab.cab readme.txt *.exe *.c

Full path names (if they are present in the cabinet) are not preserved upon extraction by default. For example, if a file named mysrc\myproj\test.c is present in the cabinet, the command cabarc x mycab.cab will cause the file test.c to be extracted into the current directory. To preserve file names upon extraction, the -p option must be used. The -p option causes any required directories to be created, if necessary.

Only the filename component is considered in the matching process. The path name is ignored. For example, the command "cabarc x mycab.cab test.c" causes the file mysrc\myproj\test.c to be extracted to the current directory as test.c, as will cabarc x mycab.cab *.c (which also extracts any other files matching *.c).

By default, the extracted files are stored in the current directory (and its subdirectories, if the -p option is used). However, it is possible to specify a destination directory for the extracted files. This is accomplished by appending a directory name to the command line. The directory name must end in a backslash ("\"). Consider the following examples: 


cabarc x mycab.cab c:\somedir\
cabarc x mycab.cab *.exe c:\somedir\


Top© 1997 Microsoft Corporation. All rights reserved. Legal Notices.