/ 
TheBat-Read_TBB-0.02
River stage zero No dependents
/ TheBat::Read_TBB

NAME

TheBat::Read_TBB - Read individual email messages out of TheBat! .tbb messages files

SYNOPSIS

use TheBat::Read_TBB;
while(&Read_TBB("messages.tbb",\%ref) {
  print "$ref{'sender'}\n";
}

DESCRIPTION

Reads the TheBat! binary messages flags (status codes like "deleted" or "replied" or "flagged" etc) as well as the email headers and body, and returns md5 checksums of some parts as well as flags and headers etc.

Call repeatedly in a loop; returns 0 when there's no more to read.

The Write_TBB function will set or reset only the 4 flags: flag_P (parked) flag_F (flagged) flag_o (read) flag_D (deleted) (see note below re writing binary files)

EXPORT

Read_TBB Write_TBB

EXAMPLE

use TheBat::Read_TBB;
my %ref;
while(&Read_TBB("t/messages.tbb",\%ref)) {	# List all emails
  foreach my $k (keys %ref) {
    print "$k:\t" . $ref{$k} . "\n";
  }
  if($ref{$msgno}==3){ $ref{'flag_P'}=1; &Write_TBB(\%ref); }	# Set the "Parked" flag on the 3rd email
}

SEE ALSO

http://www.felix-schwarz.name/files/thebat/tbb.txt

NOTE re TheBat TBB file format differences

Some more modern TheBat! clients may store messages in .TBB files with a different format in them which this code can't read. You can fix this problem by finding an older .tbb file (there's one in this package in the t/ folder) and creating a new bat folder, then exiting TheBat!, copying the old .tbb over the new folder tbb and erasing the tbn file, restarting TheBat!, and moving all your messages into this new folder

NOTE re Writing to the binary files

I only coded changed to the Deleted, Parked, and Flagged flags; and you may need to erase the MESSAGES.TBN file if you change those; warning; the TBN file holdes your memos and message colours and stuff.

AUTHOR

Chris Drake, <cdrake@cpan.org>

COPYRIGHT AND LICENSE

Copyright (C) 2013 by Chris Drake

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.10.1 or, at your option, any later version of Perl 5 you may have available.

ParseHead

Extract fields from header

write_log

Outputs debugging and informational letters to /var/log file.

BUGS

  • Little testing

SEE ALSO

TBB file format from: http://www.felix-schwarz.name/files/thebat/tbb.txt

http://www.felix-schwarz.name/TheBat_Importer_(en)

TBB file format specification

Every TBB file consists of a global file header and the parts per message.

Global File Header

The header has always the same length (0x0C08 bytes). The file starts with a
magic number: 0x20 0x06 0x79 0x19 0x08 0x0C
				  ^^^^^^^^^ total header length (*including* these 6 bytes)
That number is being followed by (0x0C08 - 6) zeros.

The Message Part

The message part has a per message header which is always 48 bytes long. This
header is followed by a RFC 822 mail message.

The Mail Header
A mail header starts with another magic number: 0x21 0x09 0x70 0x19 0x30.

bytes 0-3:      21 09 70 19		magic number
bytes 4-5	30 00			message header size
bytes 6-7:      00 00
bytes 8-11:     38 ed ad 7a		(not always "38 ed ad 7a")
bytes 12-15     WW WW WW WW             received time (unix timestamp) (little endian! 15, 14, 13, 12)
bytes 16-17:    07 00                   id number (maybe display position) (little endian! 17, 16)
bytes 18-19:    00 00
bytes 20-21:    XX XX XX XX             message status flag
bytes 22-27:    00 00 00 00
bytes 28-31:    YY YY YY YY             message belongs to a certain color group
bytes 32-35:    VV VV VV VV		priority status
bytes 36-39:    ZZ ZZ ZZ ZZ             size of the variable part (little endian! 39, 38, 37, 36)
bytes 40-47:    00 00 00 00 00 00 00 00

The size of the RFC 822 message is specified by the bytes 36-39. The mail is
followed by the next message or EOF. There is no way to know in advance if
there is another message.

The message status flag (chris):

					 01234567abcdefghijklmnopqrstuvwx
typical status using perl unpack b32 is "01001000001000000000000000010000"
		   			 01234567abcdefghijklmnopqrstuvwx

The message status flag:

Bit 7654 3210
    0000 0000

1 = yes, 0 = no
D Bit 0   deleted
o Bit 1   read				(0=unread)
a Bit 2   answered			message is replied (envelope with green arrow icon)
P Bit 3   parked				message is parked (blue p icon)
A Bit 4   has attachement
x Bit 5   attachment was deleted (?)
F Bit 6   flagged				message is flagged (red flag icon)
f Bit 7   forwarded/redirected
m     t = message has memo or is tagged (or has been modified?)

DoaPaxFft-c----------------m----
01234567abcdefghijklmnopqrstuvwx

The priority status field:

00 00 00 00	normal priority
05 00 00 00	high priority
FB FF FF FF	low priority