The WARP File Format - Version 1.0

WARP is an acronym for Waba Application Resource Package. A WARP file contains the class files, images, sounds and other resources that comprise a Waba application or class library.

In a way, WARP files are similar to ZIP or JAR files in that they contain other resources (files). However, resources are not automatically compressed when they are added to a WARP file.

This difference becomes important on small devices where decompression can be a slow and expensive operation. Any resource that requires compression should be compressed before being added to a WARP file.

The WARP file format comes in two forms; PDB form for the PalmPilot and WRP form for Windows. When they appear as files, a PDB file will have a .pdb extension (file.pdb, for example) and a WRP file will appear with a .wrp extension. The "warpgen" program is used to generate WARP files.

Since there are two forms for WARP files, we'll discuss each separately.

PDB WARP Files

A PDB WARP file exists structurally in the format of a PalmPilot PDB database file. This allows PDB WARP files to be loaded onto a PalmPilot device using the normal programs one would use to install a .pdb file.

Each record in the PDB file contains a resource such as a class file. The overall PDB file format is reasonably well documented by others so we'll only focus here on the format of individual records.

Each record in the file contains the full path of the resource (the resource name) at the start of the record and the actual binary representation of the resource following the full path. The format of each record is as follows:

    name                type/size

    -------------------------------

    path length         int/2 bytes

    path (name)         char/varies

    resource            byte/varies

As an example, if we had a record containing a class file named "mypackage/test.class", the record would start with the number 20 (the length of the path). The number is 2 bytes long and appears in network order (also known as big-endian or MSB order). This would be followed by the ASCII characters "mypackage/test.class" and following that would be the binary representation of the class file itself. The length of the record can be determined by examining the PDB record headers.

Any resource in a PDB WARP file is unmodified from its original form. The warpgen program does not compress resources and does not modify class files in any way.

The warpgen program uses the relative path of the files being added to the WARP as the path name of the resources in the WARP file. When adding class files to a WARP file, you should be careful to add them from a directory which will cause the relative paths to match their package definitions. For example a class named "myClass" defined in a package "myPack1.myPack2" should be added using the path:

    myPack1/myPack2/myClass.class

The records in a PDB WARP file appear in sorted order by path name. The path name with the least value (according to the ISO C strcmp() function) will appear first. The warpgen program will convert any reverse slashes in path names to forward slashes before writing into the path portion of the record.

WRP WARP Files

Like PDB WARP files, a WRP WARP file contains a number of records where each record contains the full path and binary representation of a resource such as a class file or image. However, the two formats are structurally different. The structure of a WRP file is much simpler than that of a PDB file. WRP files are used to package Waba class libraries and applications for Windows and Windows CE.

A WRP file has 3 parts; a header, a record offset section and the records themselves:

A WRP file starts with the following header:

    name                type/size

    -------------------------------

    magic chars         char/4 bytes

    number of records   int/4 bytes

The "magic chars" for the WRP file format version 1.0 are "Wrp1". This is followed by the number of records contained in the file as a 4 byte value. All integer values in the WRP file format are in network order (also known as big-endian or MSB order).

The header is followed by a number of record offset values. Each offset is 4 bytes in the format of:

    name                type/size

    -------------------------------

    record offset       int/4 bytes

Each offset corresponds to a record in the file. The offsets are byte locations relative to the beginning of the WARP file and denote the positions of the records in the file.

The record offset section is followed by an end-of-file offset. This value is useful when determining the length of the last record. To determine the length of any record, you can subtract that records offset from the next record offset.

To get the size of the last record, you can subtract the record offset of the last record from the end-of-file offset. The end-of-file offset is a 4 byte value in the format of:

    name                type/size

    -------------------------------

    end-of-file offset  int/4 bytes

The record offset section is followed by the records themselves. The individual records are in the same format as the records in a PDB WARP file. For reference, this is:

    name                type/size

    -------------------------------

    path length         int/2 bytes

    path (name)         char/varies

    resource            byte/varies

As is the case with PDB WARP files, resources are contained in a WRP file in their original format, uncompressed and the records appear in sorted order by path name. The path name with the least value (according to the ISO C strcmp() function) will appear first.

Also as with PDB WARP files, the warpgen program will change reverse slashes into forward slashes in path names before placing them in a record.