EBook::Tools::IMP - Object class for manipulating the SoftBook/GEB/REB/eBookWise .IMP and .RES e-book formats

 use EBook::Tools::IMP qw(:all)
 my $imp = EBook::Tools::IMP->new();
 $imp->load('myfile.imp');

Instantiates a new EBook::Tools::IMP object. If $filename is specified, it will also immediately initialize itself via the load method.

Loads a .imp file, parsing it into the various object attributes. Returns 1 on success, or undef on failure.

Loads a .RES resource directory, parsing it into the object attributes. Returns 1 on success, or undef on failure.

Returns the full name of the author of the book.

Author information can either be found entirely in the $self->{firstname} attribute or split up into $self->{firstname}, $self->{middlename}, and $self->{lastname}. If the last name is found separately, the full name is returned in the format "Last, First Middle". Otherwise, the full name is returned in the format "First Middle".

Returns the total length in bytes of the book properties data, including the trailing null used to pack the C-style strings, but excluding any ETI server data appended to the end of the standard book properties.

Returns the number of resource files as stored in $self->{filecount}. Note that this does NOT recompute that value from the actual number of resources in $self->{resources}. To do that, use create_toc_from_resources().

Goes through all stored images searching for one with the specified id value, returning the first image type found or undef if there were no matches or if no image id was specified. If the optional argument @excluded is specified, any types in the list will be skipped during the search.

Expected types are 'png', 'jpg', 'gif', and 'pic', searched for in that order.

This can be used to attempt to locate an alternate image for an undisplayable PICT image.

Takes as a single argument a resource name and if a resource with that name exists in $self->{resources} returns the resource type used as the hash key.

Returns undef if no match was found or a name was not specified.

Returns the image data stored in the resource of the specified type (specifically, stored in $self->{$type}->{$id}->{data} as parsed from the JPEG resource) corresponding to the 16-bit identifier provided as $id.

Valid values for $type are 'gif','jpg', and 'png'.

Carps a warning and returns undef if $type is not provided or is not valid, or if $id is not provided.

Returns the raw object hashref used to store parsed image data for the specified type, as stored in $self->{$type}. Valid types are 'gif', 'jpg', and 'png'.

Carps a warning and returns undef if $type is not provided or is not valid.

If $id is not specified, the keys of the returned hash are the image IDs for the specified image type, and the values are hashrefs pointing to hashes containing the following keys:

* unknown

A 16-bit integer only available on EBW 1150 resources. Use with caution. This key may be renamed if more information is found.

* length

The length of the actual image data

* offset

The byte offset inside of the raw resource data in which the JPEG image data can be found.

* const0

An unknown value, but it appears to always be zero. Use with caution. This key may be renamed if more information is found.

If the optional argument $id is specified, only the hash for that specific ID is returned, rather than the entire hash of hashrefs.

Returns a list of the 16-bit integer IDs of the the specified type of image data stored in the associated resource (specifically, stored in $self->{$type} as parsed from the JPEG resource).

Valid types are 'gif', 'jpg', and 'png'. The method will carp a warning and return undef if another type is specified, or no type is specified.

Returns 1 if $self->{device} == 2, returns 0 if it is some other value, and undef it is undefined. This has value because resources packed for a EBW 1150 or GEB 1150 are in a different format than resources packed for other IMP readers.

Returns the text of the element corresponding to the given text offset as stored in $self->{offsetelements}, or undef if no such element exists.

Packs object attributes into the 7 null-terminated strings that constitute the book properties section of the header. Returns that string.

Note that this does NOT pack the ETI server data appended to this section in encrypted books downloaded directly from the ETI servers, even if that data was found when the .imp file was loaded. This is because the extra data can confuse the GEBLibrarian application, and is not needed to read the book. The bookproplength() and pack_imp_header() methods also assume that this data will not be present.

Packs object attributes into the 48-byte string representing the IMP header. Returns that string on success, carps a warning and returns undef if a required attribute did not contain valid data.

Note that in the case of an encrypted e-book with ETI server data in it, this header will not be identical to the original -- the resdiroffset value is recalculated for the position with the ETI server data stripped. See bookproplength() and pack_imp_book_properties().

Packs the specified resource stored in $self->{resources} into a a data string suitable for writing into a .imp file, with a header format determined by $self->{version}.

Returns a reference to that string if the resource was found, or undef it was not.

* name

Select the resource by resource name.

If both this and type are specified, the type is checked first and the name is only used if the type lookup fails.

* type

Select the resource by resource type. This is faster than selecting by name (since resources are stored in a hash keyed by type) and is recommended for most use.

If both this and name are specified, the type is checked first and the name is only used if the type lookup fails.

Packs object attributes into the data string that would be the content of the RSRC.INF file. Returns that string.

Packs the $self->{toc} object attribute into a data string suitable for writing into a .imp file. The format is determined by $self->{version}.

Returns that string, or undef if valid version or TOC data is not found.

In scalar context, this returns the basename of $self->{resdirname}. In list context, it actually returns the basename, directory, and extension as per fileparse from File::Basename.

Returns the length of the .RES directory name as stored in $self->{resdirlength}. Note that this does NOT recompute the length from the actual name stored in $self->{resdirname} -- for that, use set_resdirlength().

Returns the .RES directory name stored in $self->{resdirname}.

Returns a hashref containing the resource data for the specified resource type, as stored in $self->{resources}->{$type}.

Returns undef if $type is not specified, or if the specified type is not found.

Returns a hashref of hashrefs containing all of the resource data keyed by type, as stored in $self->{resources}.

Returns the uncompressed text originally stored in the DATA.FRK (' ') resource. This will only work if the text was unencrypted.

Returns the book title as stored in $self->{title}.

Takes as a single argument an integer index to the table of contents data stored in $self->{toc}. Returns the hashref corresponding to that TOC entry, if it exists, or undef otherwise.

Returns the version of the IMP format used to determine TOC and resource metadata size as stored in $self->{version}. Expected values are 1 (10-byte metadata) and 2 (20-byte metadata).

Writes the images, if any, to the specified output directory. Filenames are in the format JPEG_XXXX.jpg or PNG_XXXX.png where XXXX is the image ID for that image type formatted as four hexadecimal characters.

* dir

The output directory in which to write the file. This will be created if it does not exist. Defaults to the basename of the stored resource directory (see also resdirname()).

Takes as a sole argument the name of a file to write to, and writes a .imp file to that filename using the object attribute data.

Returns 1 on success, or undef if required data (including the filename) was invalid or missing, or the file could not be written.

Writes a .RES resource directory from the object attribute data, using $self->{resdirname} as the directory name.

Writes the uncompressed text, if any, to the specified output directory and file.

* dir

The output directory in which to write the file. This will be created if it does not exist. Defaults to the basename of the stored resource directory (see also resdirname()).

* filename

The filename of the output file to write. If not specified, a warning will be carped and the method will return undef.

Creates appropriate table of contents data from the metadata in $self->{resources}, in the format specified by $self->{version}. This will also set $self->{filecount} to match the actual number of resources.

Returns the number of resources found.

Parses ETI server data, as potentially found appended to the end of .imp book properties or a RSRC.INF resource file on encrypted books downloaded directly from ETI servers.

Takes as a single argument a string containing just the extra appended data, and stores the parsed values in $self->{etiserverdata} as a hash. Note that parsing requires knowledge of the length of the book properties at the time this data was inserted; if the book properties have not been properly parsed or have been modified, the resulting behaviour of this method is not defined.

Returns the number of bytes handled, zero if no data was provided.

The data has the following format and keys:

* [0-3 bytes]: padding data to make sure the following data is 4-byte aligned, stored in key pad.

* [4 bytes, big-endian unsigned long int]: unknown value, usually = 2, stored in key unknown1

* [4 bytes, big-endian unsigned long int]: issue number for periodicals (always 0xffffffff for books), stored in key issuenumber.

* [variable-length null-terminated string]: content feed for periodicals, null string for books, stored in key contentfeed.

* [variable-length null-terminated string]: source string in the format 'SOURCE_ID:SOURCE_TYPE:None', where SOURCE_ID is usually '3' and SOURCE_TYPE is usually 'B'.

* [4 bytes, big-endian unsigned long int]: unknown value, stored in key unknown2. This value may not be present at all.

Takes as a single argument a string containing the book properties data. Sets the object variables from its contents, which should be seven null-terminated strings in the following order:

* Identifier

* Category

* Subcategory

* Title

* Last Name

* Middle Name

* First Name

Note that the entire name is frequently placed into the "First Name" component, and the "Last Name" and "Middle Name" components are left blank.

In addition, ETI server data may be appended to this data on encrypted books downloaded from ETI servers. If present, that data will be stored in the hash $self->{etiserverdata}. See parse_eti_server_data($data) for details.

A warning will be carped if the length of the parsed properties (including the C null string terminators) is not equal to the length of the data passed.

Parses the first 48 bytes of a .IMP file, setting object variables. The method croaks if it receives any more or less than 48 bytes.

* Offset 0x00 [2 bytes, big-endian unsigned short int]

Version. Expected values are 1 or 2; the version affects the format of the table of contents header. If this isn't 1 or 2, the method carps a warning and returns undef.

* Offset 0x02 [8 bytes]

Identifier. This is always 'BOOKDOUG', and the method carps a warning and returns undef if it isn't.

* Offset 0x0A [8 bytes]

Unknown data, stored in $self->{unknown0x0a}. Use with caution -- this value may be renamed if more information is obtained.

* Offset 0x12 [2 bytes, big-endian unsigned short int]

Number of included files, stored in $self->{filecount}.

* Offset 0x14 [2 bytes, big-endian unsigned short int]

Length in bytes of the .RES directory name, stored in $self->{resdirlength}.

* Offset 0x16 [2 bytes, big-endian unsigned short int]

Offset from the point after this value to the .RES directory name, which also marks the end of the book properties, stored in $self->{resdiroffset}. Note that this is NOT the length of the book properties. To get the length of the book properties, subtract 24 from this value (the number of bytes remaining in the header after this point). It is also NOT the offset from the beginning of the file to the .RES directory name -- to find that, add 24 to this value (the number of bytes already parsed).

* Offset 0x18 [4 bytes, big-endian unsigned long int?]

Unknown value, stored in $self->{unknown0x18}. Use with caution -- this value may be renamed if more information is obtained.

* Offset 0x1C [4 bytes, big-endian unsigned long int?]

Unknown value, stored in $self->{unknown0x1c}. Use with caution -- this value may be renamed if more information is obtained.

* Offset 0x20 [4 bytes, big-endian unsigned long int]

Compression type, stored in $self->{compression}. Expected values are 0 (no compression) and 1 (LZSS compression).

* Offset 0x24 [4 bytes, big-endian unsigned long int]

Encryption type, stored in $self->{encryption}. Expected values are 0 (no encryption) and 2 (DES encryption).

* Offset 0x28 [2 bytes, big-ending unsigned short int]

Unknown value, stored in $self->{unknown0x28}. Use with caution -- this value may be renamed if more information is obtained.

* Offset 0x2A [1 byte]

Unknown value, stored in $self->{unknown0x2A}. Use with caution -- this value may be renamed if more information is obtained.

* Offset 0x2B [2 nybbles (1 byte)]

The upper nybble at this position is the IMP reader device for which the e-book was designed, stored in $self->{device}. Expected values are 0 (Softbook 200/250e), 1 (REB 1200/GEB 2150), and 2 (EBW 1150/GEB1150).

The lower nybble marks the possible zoom states, stored in $self->{zoomstates}. Expected values are 0 (both zooms), 1 (small zoom), and 2 (large zoom)

* Offset 0x2C [4 bytes, big-endian unsigned long int]

Unknown value, stored in $self->{unknown0x2c}. Use with caution -- this value may be renamed if more information is obtained.

Parses the !!cm resource loaded into $self->{resources}, if present, extracting the LZSS uncompression parameters into $self->{lzssoffsetbits} and $self->{lzsslengthbits}.

Returns 1 on success, or undef if no !!cm resource has been loaded yet or the resource data is invalid.

Parses the image data resources loaded into $self->{resources}, if present, placing the image data and metadata of each image found into $self->{jpg} and $self->{png}, keyed by 16-bit image resource ID.

Returns the total number of images found and parsed.

This method is called automatically by load() and load_resdir().

See also accessor methods image(%args) and image_hashrefs(%args).

Parses the index of text offsets to all images as stored in $self->{resources}->{'ImRn'}, if present, storing them in $self->{imrn} as a hash of hashrefs indexed by its 32-bit integer offset to the 0x0F control code in the uncompressed text stored in the DATA.FRK resource.

Returns the total number of offsets found and parsed.

The hash keys of each offset hash are:

* width

Image display width in pixels.

* height

Image display height in pixels.

* id

A 16-bit integer value used to uniquely identify the image inside a particular resource type.

* restype

The four-letter resource type string.

* constF1

A 32-bit value of unknown purpose which should always be 0xFFFFFFFF.

* constF2

A second 32-bit value of unknown purpose which should always be 0xFFFFFFFF.

* const0

A 32-bit integer value of unknown purpose which should always be 0x00000000.

* constB

A 16-bit integer value of unknown purpose which could be 0xFFFA, 0xFFFB, 0xFFFC, or 0xFFFE.

* unknown16

A 16-bit integer value of unknown purpose found only in 1150 resources.

* unknown32

A 32-bit integer value of unknown purpose.

This method is called automatically by load() and load_resdir().

Parses the ' ' (DATA.FRK) resource loaded into $self->{resources}, if present, extracting the text into $self->{text}, uncompressing it if necessary. LZSS uncompression will use the $self->{lzsslengthbits} and $self->{lzssoffsetbits} attributes if present, and default to 3 length bits and 14 offset bits otherwise.

HTML headers and footers are then applied, and control codes replaced with appropriate tags.

Returns the length of the raw uncompressed text before any HTML modification was done, or undef if no text resource was found or the text was encrypted.

Takes as a single argument a string containing the table of contents data, and parses it into object attributes following the version 1 format (10 bytes per entry).

* Offset 0x00 [4 bytes, text]

Resource name. Stored in hash key name. In the case of the 'DATA.FRK' text resource, this will be four spaces (' ').

* Offset 0x04 [2 bytes, big-endian unsigned short int]

Unknown, but always zero or one. Stored in hash key unknown1.

* Offset 0x08 [4 bytes, big-endian unsigned long int]

Size of the resource data in bytes. Stored in hash key size.

Takes as a single argument a string containing the table of contents data, and parses it into object attributes following the version 2 format (20 bytes per entry).

* Offset 0x00 [4 bytes, text]

Resource name. Stored in name. In the case of the 'DATA.FRK' text resource, this will be four spaces (' ').

* Offset 0x04 [4 bytes, big-endian unsigned long int]

Unknown, but always zero. Stored in unknown1.

* Offset 0x08 [4 bytes, big-endian unsigned long int]

Size of the resource data in bytes. Stored in size.

* Offset 0x0C [4 bytes, text]

Resource type. Stored in type, and used as the key for the stored resource hash.

* Offset 0x10 [4 bytes, big-endian unsigned long int]

Unknown, but always either zero or one. Stored in unknown2.

Sets the specified book properties. Returns 1 on success, or undef if no properties were specified.

* identifier

The book identifier, as might be provided as an OPF <dc:identifier> element.

* category

The main book category, as might be provided as an OPF <dc:subject> element.

* subcategory

The subcategory, generally a set of search arguments for the ETI website.

* title

The book title, as might be provided as an OPF <dc:title> element.

* lastname

The primary author's last name, but see the entry for firstname before deciding how to handle name storage.

* middlename

The primary author's middle name, but see the entry for firstname before deciding how to handle name storage.

* firstname

The primary author's first name, but this field is also used by a great many .imp books to store the entire name in "First Last" format. If this field is to be used this way, lastname and middlename must be blank.

 $imp->set_book_properties(title => 'My Best Book',
                           category => 'Fiction',
                           firstname => 'John Q. Public');

All procedures are exportable, but none are exported by default.

Takes as a sole argument a reference to the data component of a resource. Returns a 4-byte string containing the resource type if detected successfully, or undef otherwise.

Detection will not work on the DATA.FRK (' ') resource. That one must be detected separately by name/type.

Takes as a sole argument a string containing the data (including the 10-byte header) of a version 1 IMP resource.

Returns a hashref containing that data separated into the following keys:

* name

The four-letter name of the resource.

* type

The four-letter type of the resource. This is detected from the data, and is not part of the v1 header.

* unknown1

A 16-bit unsigned int of unknown purpose. Expected values are 0 or 1.

Use with caution. This key may be renamed later if more information is found.

* size

The expected size in bytes of the actual resource data. A warning will be carped if this does not match the actual size of the data following the header.

* data

The actual resource data.

Takes as a sole argument a string containing the data (including the 20-byte header) of a version 2 IMP resource.

Returns a hashref containing that data separated into the following keys:

* name

The four-letter name of the resource.

* unknown1

A 32-bit unsigned int of unknown purpose. Expected values are 0 or 1.

Use with caution. This key may be renamed later if more information is found.

* size

The expected size in bytes of the actual resource data. A warning will be carped if this does not match the actual size of the data following the header.

* type

The four-letter type of the resource.

* unknown2

A 32-bit unsigned int of unknown purpose. Expected values are 0 or 1.

Use with caution. This key may be renamed later if more information is found.

* data

The actual resource data.

* Not finished. Do not try to use yet.

* MacPaint PICT images are not well-supported. If present in the book, they will be saved, but a warning will be carped about invalid image data.

* Support for v1 files is completely untested and implemented with some guesswork. Bug reports welcome.

Zed Pobre <zed@debian.org>

Thanks are due to Nick Rapallo <nrapallo@yahoo.ca> for invaluable assistance in understanding the .IMP format and testing this code.

Thanks are also due to Jeffrey Kraus-yao <krausyaoj@ameritech.net> for his work reverse-engineering the .IMP format to begin with, and the documentation at http://krausyaoj.tripod.com/reb1200.htm.

Copyright 2008 Zed Pobre

Licensed to the public under the terms of the GNU GPL, version 2.