ruby-msg 1.3.1 → 1.4.0

data/lib/mapi/convert/note-tmail.rb

@@ -0,0 +1,287 @@
+require 'rubygems'
+require 'tmail'
+
+# these will be removed later
+require 'time'
+require 'mime'
+
+# there is some Msg specific stuff in here.
+
+class TMail::Mail
+	def quoted_body= str
+		body_port.wopen { |f| f.write str }
+		str
+	end
+end
+
+module Mapi
+	class Message
+		def mime
+			return @mime if @mime
+			# if these headers exist at all, they can be helpful. we may however get a
+			# application/ms-tnef mime root, which means there will be little other than
+			# headers. we may get nothing.
+			# and other times, when received from external, we get the full cigar, boundaries
+			# etc and all.
+			# sometimes its multipart, with no boundaries. that throws an error. so we'll be more
+			# forgiving here
+			@mime = Mime.new props.transport_message_headers.to_s, true
+			populate_headers
+			@mime
+		end
+
+		def headers
+			mime.headers
+		end
+
+		# copy data from msg properties storage to standard mime. headers
+		# i've now seen it where the existing headers had heaps on stuff, and the msg#props had
+		# practically nothing. think it was because it was a tnef - msg conversion done by exchange.
+		def populate_headers
+			# construct a From value
+			# should this kind of thing only be done when headers don't exist already? maybe not. if its
+			# sent, then modified and saved, the headers could be wrong?
+			# hmmm. i just had an example where a mail is sent, from an internal user, but it has transport
+			# headers, i think because one recipient was external. the only place the senders email address
+			# exists is in the transport headers. so its maybe not good to overwrite from.
+			# recipients however usually have smtp address available.
+			# maybe we'll do it for all addresses that are smtp? (is that equivalent to 
+			# sender_email_address !~ /^\//
+			name, email = props.sender_name, props.sender_email_address
+			if props.sender_addrtype == 'SMTP'
+				headers['From'] = if name and email and name != email
+					[%{"#{name}" <#{email}>}]
+				else
+					[email || name]
+				end
+			elsif !headers.has_key?('From')
+				# some messages were never sent, so that sender stuff isn't filled out. need to find another
+				# way to get something
+				# what about marking whether we thing the email was sent or not? or draft?
+				# for partition into an eventual Inbox, Sent, Draft mbox set?
+				# i've now seen cases where this stuff is missing, but exists in transport message headers,
+				# so maybe i should inhibit this in that case.
+				if email
+					# disabling this warning for now
+					#Log.warn "* no smtp sender email address available (only X.400). creating fake one"
+					# this is crap. though i've specially picked the logic so that it generates the correct
+					# email addresses in my case (for my organisation).
+					# this user stuff will give valid email i think, based on alias.
+					user = name ? name.sub(/(.*), (.*)/, "\\2.\\1") : email[/\w+$/].downcase
+					domain = (email[%r{^/O=([^/]+)}i, 1].downcase + '.com' rescue email)
+					headers['From'] = [name ? %{"#{name}" <#{user}@#{domain}>} : "<#{user}@#{domain}>" ]
+				elsif name
+					# we only have a name? thats screwed up.
+					# disabling this warning for now
+					#Log.warn "* no smtp sender email address available (only name). creating fake one"
+					headers['From'] = [%{"#{name}"}]
+				else
+					# disabling this warning for now
+					#Log.warn "* no sender email address available at all. FIXME"
+				end
+			# else we leave the transport message header version
+			end
+
+			# for all of this stuff, i'm assigning in utf8 strings.
+			# thats ok i suppose, maybe i can say its the job of the mime class to handle that.
+			# but a lot of the headers are overloaded in different ways. plain string, many strings
+			# other stuff. what happens to a person who has a " in their name etc etc. encoded words
+			# i suppose. but that then happens before assignment. and can't be automatically undone
+			# until the header is decomposed into recipients.
+			recips_by_type = recipients.group_by { |r| r.type }
+			# i want to the the types in a specific order.
+			[:to, :cc, :bcc].each do |type|
+				# don't know why i bother, but if we can, we try to sort recipients by the numerical part
+				# of the ole name, or just leave it if we can't
+				recips = recips_by_type[type]
+				recips = (recips.sort_by { |r| r.obj.name[/\d{8}$/].hex } rescue recips)
+				# switched to using , for separation, not ;. see issue #4
+				# recips.empty? is strange. i wouldn't have thought it possible, but it was right?
+				headers[type.to_s.sub(/^(.)/) { $1.upcase }] = [recips.join(', ')] unless recips.empty?
+			end
+			headers['Subject'] = [props.subject] if props.subject
+
+			# fill in a date value. by default, we won't mess with existing value hear
+			if !headers.has_key?('Date')
+				# we want to get a received date, as i understand it.
+				# use this preference order, or pull the most recent?
+				keys = %w[message_delivery_time client_submit_time last_modification_time creation_time]
+				time = keys.each { |key| break time if time = props.send(key) }
+				time = nil unless Date === time
+
+				# now convert and store
+				# this is a little funky. not sure about time zone stuff either?
+				# actually seems ok. maybe its always UTC and interpreted anyway. or can be timezoneless.
+				# i have no timezone info anyway.
+				# in gmail, i see stuff like 15 Jan 2007 00:48:19 -0000, and it displays as 11:48.
+				# can also add .localtime here if desired. but that feels wrong.
+				headers['Date'] = [Time.iso8601(time.to_s).rfc2822] if time
+			end
+
+			# some very simplistic mapping between internet message headers and the
+			# mapi properties
+			# any of these could be causing duplicates due to case issues. the hack in #to_mime
+			# just stops re-duplication at that point. need to move some smarts into the mime
+			# code to handle it.
+			mapi_header_map = [
+				[:internet_message_id, 'Message-ID'],
+				[:in_reply_to_id, 'In-Reply-To'],
+				# don't set these values if they're equal to the defaults anyway
+				[:importance, 'Importance', proc { |val| val.to_s == '1' ? nil : val }],
+				[:priority, 'Priority', proc { |val| val.to_s == '1' ? nil : val }],
+				[:sensitivity, 'Sensitivity', proc { |val| val.to_s == '0' ? nil : val }],
+				# yeah?
+				[:conversation_topic, 'Thread-Topic'],
+				# not sure of the distinction here
+				# :originator_delivery_report_requested ??
+				[:read_receipt_requested, 'Disposition-Notification-To', proc { |val| from }]
+			]
+			mapi_header_map.each do |mapi, mime, *f|
+				next unless q = val = props.send(mapi) or headers.has_key?(mime)
+				next if f[0] and !(val = f[0].call(val))
+				headers[mime] = [val.to_s]
+			end
+		end
+
+		# redundant?
+		def type
+			props.message_class[/IPM\.(.*)/, 1].downcase rescue nil
+		end
+
+		# shortcuts to some things from the headers
+		%w[From To Cc Bcc Subject].each do |key|
+			define_method(key.downcase) { headers[key].join(' ') if headers.has_key?(key) }
+		end
+
+		def body_to_tmail
+			# to create the body
+			# should have some options about serializing rtf. and possibly options to check the rtf
+			# for rtf2html conversion, stripping those html tags or other similar stuff. maybe want to
+			# ignore it in the cases where it is generated from incoming html. but keep it if it was the
+			# source for html and plaintext.
+			if props.body_rtf or props.body_html
+				# should plain come first?
+				part = TMail::Mail.new
+				# its actually possible for plain body to be empty, but the others not.
+				# if i can get an html version, then maybe a callout to lynx can be made...
+				part.parts << TMail::Mail.parse("Content-Type: text/plain\r\n\r\n" + props.body) if props.body
+				# this may be automatically unwrapped from the rtf if the rtf includes the html
+				part.parts << TMail::Mail.parse("Content-Type: text/html\r\n\r\n"  + props.body_html) if props.body_html
+				# temporarily disabled the rtf. its just showing up as an attachment anyway.
+				#mime.parts << Mime.new("Content-Type: text/rtf\r\n\r\n"   + props.body_rtf)  if props.body_rtf
+				# its thus currently possible to get no body at all if the only body is rtf. that is not
+				# really acceptable FIXME
+				part['Content-Type'] = 'multipart/alternative'
+				part
+			else
+				# check no header case. content type? etc?. not sure if my Mime class will accept
+				Log.debug "taking that other path"
+				# body can be nil, hence the to_s
+				TMail::Mail.parse "Content-Type: text/plain\r\n\r\n" + props.body.to_s
+			end
+		end
+
+		def to_tmail
+			# intended to be used for IPM.note, which is the email type. can use it for others if desired,
+			# YMMV
+			Log.warn "to_mime used on a #{props.message_class}" unless props.message_class == 'IPM.Note'
+			# we always have a body
+			mail = body = body_to_tmail
+
+			# If we have attachments, we take the current mime root (body), and make it the first child
+			# of a new tree that will contain body and attachments.
+			unless attachments.empty?
+				raise NotImplementedError
+				mime = Mime.new "Content-Type: multipart/mixed\r\n\r\n"
+				mime.parts << body
+				# i don't know any better way to do this. need multipart/related for inline images
+				# referenced by cid: urls to work, but don't want to use it otherwise...
+				related = false
+				attachments.each do |attach|
+					part = attach.to_mime
+					related = true if part.headers.has_key?('Content-ID') or part.headers.has_key?('Content-Location')
+					mime.parts << part
+				end
+				mime.headers['Content-Type'] = ['multipart/related'] if related
+			end
+
+			# at this point, mime is either
+			# - a single text/plain, consisting of the body ('taking that other path' above. rare)
+			# - a multipart/alternative, consiting of a few bodies (plain and html body. common)
+			# - a multipart/mixed, consisting of 1 of the above 2 types of bodies, and attachments.
+			# we add this standard preamble if its multipart
+			# FIXME preamble.replace, and body.replace both suck.
+			# preamble= is doable. body= wasn't being done because body will get rewritten from parts
+			# if multipart, and is only there readonly. can do that, or do a reparse...
+			# The way i do this means that only the first preamble will say it, not preambles of nested
+			# multipart chunks.
+			mail.quoted_body = "This is a multi-part message in MIME format.\r\n" if mail.multipart?
+
+			# now that we have a root, we can mix in all our headers
+			headers.each do |key, vals|
+				# don't overwrite the content-type, encoding style stuff
+				next if mail[key]
+				# some new temporary hacks
+				next if key =~ /content-type/i and vals[0] =~ /base64/
+				#next if mime.headers.keys.map(&:downcase).include? key.downcase
+				mail[key] = vals.first
+			end
+			# just a stupid hack to make the content-type header last, when using OrderedHash
+			#mime.headers['Content-Type'] = mime.headers.delete 'Content-Type'
+
+			mail
+		end
+	end
+
+	class Attachment
+		def to_tmail
+			# TODO: smarter mime typing.
+			mimetype = props.attach_mime_tag || 'application/octet-stream'
+			part = TMail::Mail.parse "Content-Type: #{mimetype}\r\n\r\n"
+			part['Content-Disposition'] = %{attachment; filename="#{filename}"}
+			part['Content-Transfer-Encoding'] = 'base64'
+			part['Content-Location'] = props.attach_content_location if props.attach_content_location
+			part['Content-ID'] = props.attach_content_id if props.attach_content_id
+			# data.to_s for now. data was nil for some reason.
+			# perhaps it was a data object not correctly handled?
+			# hmmm, have to use read here. that assumes that the data isa stream.
+			# but if the attachment data is a string, then it won't work. possible?
+			data_str = if @embedded_msg
+				raise NotImplementedError
+				mime.headers['Content-Type'] = 'message/rfc822'
+				# lets try making it not base64 for now
+				mime.headers.delete 'Content-Transfer-Encoding'
+				# not filename. rather name, or something else right?
+				# maybe it should be inline?? i forget attach_method / access meaning
+				mime.headers['Content-Disposition'] = [%{attachment; filename="#{@embedded_msg.subject}"}]
+				@embedded_msg.to_mime.to_s
+			elsif @embedded_ole
+				raise NotImplementedError
+				# kind of hacky
+				io = StringIO.new
+				Ole::Storage.new io do |ole|
+					ole.root.type = :dir
+					Ole::Storage::Dirent.copy @embedded_ole, ole.root
+				end
+				io.string
+			else
+				data.read.to_s
+			end
+			part.body = @embedded_msg ? data_str : Base64.encode64(data_str).gsub(/\n/, "\r\n")
+			part
+		end
+	end
+
+	class Msg < Message
+		def populate_headers
+			super
+			if !headers.has_key?('Date')
+				# can employ other methods for getting a time. heres one in a similar vein to msgconvert.pl,
+				# ie taking the time from an ole object
+				time = @root.ole.dirents.map { |dirent| dirent.modify_time || dirent.create_time }.compact.sort.last
+				headers['Date'] = [Time.iso8601(time.to_s).rfc2822] if time
+			end
+		end
+	end
+end
+

data/lib/mapi/msg.rb

@@ -0,0 +1,440 @@
+require 'rubygems'
+require 'ole/storage'
+require 'mapi'
+require 'mapi/rtf'
+
+module Mapi
+	#
+	# = Introduction
+	#
+	# Primary class interface to the vagaries of .msg files.
+	#
+	# The core of the work is done by the <tt>Msg::PropertyStore</tt> class.
+	#
+	class Msg < Message
+		#
+		# = Introduction
+		#
+		# A big compononent of +Msg+ files is the property store, which holds
+		# all the key/value pairs of properties. The message itself, and all
+		# its <tt>Attachment</tt>s and <tt>Recipient</tt>s have an instance of
+		# this class.
+		#
+		# = Storage model
+		#
+		# Property keys (tags?) can be either simple hex numbers, in the
+		# range 0x0000 - 0xffff, or they can be named properties. In fact,
+		# properties in the range 0x0000 to 0x7fff are supposed to be the non-
+		# named properties, and can be considered to be in the +PS_MAPI+
+		# namespace. (correct?)
+		# 
+		# Named properties are serialized in the 0x8000 to 0xffff range,
+		# and are referenced as a guid and long/string pair.
+		#
+		# There are key ranges, which can be used to imply things generally
+		# about keys.
+		#
+		# Further, we can give symbolic names to most keys, coming from
+		# constants in various places. Eg:
+		# 
+		#   0x0037 => subject
+		#   {00062002-0000-0000-C000-000000000046}/0x8218 => response_status
+		#   # displayed as categories in outlook
+		#   {00020329-0000-0000-C000-000000000046}/"Keywords" => categories
+		# 
+		# Futher, there are completely different names, coming from other
+		# object models that get mapped to these things (CDO's model,
+		# Outlook's model etc). Eg "urn:schemas:httpmail:subject"
+		# I think these can be ignored though, as they aren't defined clearly
+		# in terms of mapi properties, and i'm really just trying to make
+		# a mapi property store. (It should also be relatively easy to
+		# support them later.)
+		# 
+		# = Usage
+		#
+		# The api is driven by a desire to have the simple stuff "just work", ie
+		#
+		#   properties.subject
+		#   properties.display_name
+		# 
+		# There also needs to be a way to look up properties more specifically:
+		# 
+		#   properties[0x0037] # => gets the subject
+		#   properties[0x0037, PS_MAPI] # => still gets the subject
+		#   properties['Keywords', PS_PUBLIC_STRINGS] # => gets outlook's categories array
+		# 
+		# The abbreviated versions work by "resolving" the symbols to full keys:
+		#
+		#		# the guid here is just PS_PUBLIC_STRINGS
+		#   properties.resolve :keywords # => #<Key {00020329-0000-0000-c000-000000000046}/"Keywords">
+		#   # the result here is actually also a key
+		#   k = properties.resolve :subject  # => 0x0037
+		#   # it has a guid
+		#   k.guid == Msg::Properties::PS_MAPI # => true
+		#
+		# = Parsing
+		#
+		# There are three objects that need to be parsed to load a +Msg+ property store:
+		# 
+		# 1. The +nameid+ directory (<tt>Properties.parse_nameid</tt>)
+		# 2. The many +substg+ objects, whose names should match <tt>Properties::SUBSTG_RX</tt>
+		#    (<tt>Properties#parse_substg</tt>)
+		# 3. The +properties+ file (<tt>Properties#parse_properties</tt>)
+		#
+		# Understanding of the formats is by no means perfect.
+		#
+		# = TODO
+		#
+		# * While the key objects are sufficient, the value objects are just plain
+		#   ruby types. It currently isn't possible to write to the values, or to know
+		#   which encoding the value had.
+		# * Update this doc.
+		# * Perhaps change from eager loading, to be load-on-demand.
+		#
+		class PropertyStore
+			include PropertySet::Constants
+			Key = PropertySet::Key
+
+			# note that binary and default both use obj.open. not the block form. this means we should
+			# #close it later, which we don't. as we're only reading though, it shouldn't matter right?
+			# not really good though FIXME
+			# change these to use mapi symbolic const names
+			ENCODINGS = {
+				0x000d =>   proc { |obj| obj }, # seems to be used when its going to be a directory instead of a file. eg nested ole. 3701 usually. in which case we shouldn't get here right?
+				0x001f =>   proc { |obj| Ole::Types::FROM_UTF16.iconv obj.read }, # unicode
+				# ascii
+				# FIXME hack did a[0..-2] before, seems right sometimes, but for some others it chopped the text. chomp
+				0x001e =>   proc { |obj| obj.read.chomp 0.chr },
+				0x0102 =>   proc { |obj| obj.open }, # binary?
+				:default => proc { |obj| obj.open }
+			}
+
+			SUBSTG_RX = /^__substg1\.0_([0-9A-F]{4})([0-9A-F]{4})(?:-([0-9A-F]{8}))?$/
+			PROPERTIES_RX = /^__properties_version1\.0$/
+			NAMEID_RX = /^__nameid_version1\.0$/
+			VALID_RX = /#{SUBSTG_RX}|#{PROPERTIES_RX}|#{NAMEID_RX}/
+
+			attr_reader :nameid
+
+			def initialize
+				@nameid = nil
+				# not exactly a cache currently
+				@cache = {}
+			end
+
+			#--
+			# The parsing methods
+			#++
+
+			def self.load obj
+				prop = new
+				prop.load obj
+				prop
+			end
+
+			# Parse properties from the +Dirent+ obj
+			def load obj
+				# we need to do the nameid first, as it provides the map for later user defined properties
+				if nameid_obj = obj.children.find { |child| child.name =~ NAMEID_RX }
+					@nameid = PropertyStore.parse_nameid nameid_obj
+					# hack to make it available to all msg files from the same ole storage object
+					# FIXME - come up with a neater way
+					class << obj.ole
+						attr_accessor :msg_nameid
+					end
+					obj.ole.msg_nameid = @nameid
+				elsif obj.ole
+					@nameid = obj.ole.msg_nameid rescue nil
+				end
+				# now parse the actual properties. i think dirs that match the substg should be decoded
+				# as properties to. 0x000d is just another encoding, the dir encoding. it should match
+				# whether the object is file / dir. currently only example is embedded msgs anyway
+				obj.children.each do |child|
+					next unless child.file?
+					case child.name
+					when PROPERTIES_RX
+						parse_properties child
+					when SUBSTG_RX
+						parse_substg(*($~[1..-1].map { |num| num.hex rescue nil } + [child]))
+					end
+				end
+			end
+
+			# Read nameid from the +Dirent+ obj, which is used for mapping of named properties keys to
+			# proxy keys in the 0x8000 - 0xffff range.
+			# Returns a hash of integer -> Key.
+			def self.parse_nameid obj
+				remaining = obj.children.dup
+				guids_obj, props_obj, names_obj =
+					%w[__substg1.0_00020102 __substg1.0_00030102 __substg1.0_00040102].map do |name|
+						remaining.delete obj/name
+					end
+
+				# parse guids
+				# this is the guids for named properities (other than builtin ones)
+				# i think PS_PUBLIC_STRINGS, and PS_MAPI are builtin.
+				guids = [PS_PUBLIC_STRINGS] + guids_obj.read.scan(/.{16}/m).map do |str|
+					Ole::Types.load_guid str
+				end
+
+				# parse names.
+				# the string ids for named properties
+				# they are no longer parsed, as they're referred to by offset not
+				# index. they are simply sequentially packed, as a long, giving
+				# the string length, then padding to 4 byte multiple, and repeat.
+				names_data = names_obj.read
+
+				# parse actual props.
+				# not sure about any of this stuff really.
+				# should flip a few bits in the real msg, to get a better understanding of how this works.
+				props = props_obj.read.scan(/.{8}/m).map do |str|
+					flags, offset = str[4..-1].unpack 'v2'
+					# the property will be serialised as this pseudo property, mapping it to this named property
+					pseudo_prop = 0x8000 + offset
+					named = flags & 1 == 1
+					prop = if named
+						str_off = *str.unpack('V')
+						len = *names_data[str_off, 4].unpack('V')
+						Ole::Types::FROM_UTF16.iconv names_data[str_off + 4, len]
+					else
+						a, b = str.unpack('v2')
+						Log.debug "b not 0" if b != 0
+						a
+					end
+					# a bit sus
+					guid_off = flags >> 1
+					# missing a few builtin PS_*
+					Log.debug "guid off < 2 (#{guid_off})" if guid_off < 2
+					guid = guids[guid_off - 2]
+					[pseudo_prop, Key.new(prop, guid)]
+				end
+
+				#Log.warn "* ignoring #{remaining.length} objects in nameid" unless remaining.empty?
+				# this leaves a bunch of other unknown chunks of data with completely unknown meaning.
+				# pp [:unknown, child.name, child.data.unpack('H*')[0].scan(/.{16}/m)]
+				Hash[*props.flatten]
+			end
+
+			# Parse an +Dirent+, as per <tt>msgconvert.pl</tt>. This is how larger properties, such
+			# as strings, binary blobs, and other ole sub-directories (eg nested Msg) are stored.
+			def parse_substg key, encoding, offset, obj
+				if (encoding & 0x1000) != 0
+					if !offset
+						# there is typically one with no offset first, whose data is a series of numbers
+						# equal to the lengths of all the sub parts. gives an implied array size i suppose.
+						# maybe you can initialize the array at this time. the sizes are the same as all the
+						# ole object sizes anyway, its to pre-allocate i suppose.
+						#p obj.data.unpack('V*')
+						# ignore this one
+						return
+					else
+						# remove multivalue flag for individual pieces
+						encoding &= ~0x1000
+					end
+				else
+					Log.warn "offset specified for non-multivalue encoding #{obj.name}" if offset
+					offset = nil
+				end
+				# offset is for multivalue encodings.
+				unless encoder = ENCODINGS[encoding]
+					Log.warn "unknown encoding #{encoding}"
+					#encoder = proc { |obj| obj.io } #.read }. maybe not a good idea
+					encoder = ENCODINGS[:default]
+				end
+				add_property key, encoder[obj], offset
+			end
+
+			# For parsing the +properties+ file. Smaller properties are serialized in one chunk,
+			# such as longs, bools, times etc. The parsing has problems.
+			def parse_properties obj
+				data = obj.read
+				# don't really understand this that well...
+				pad = data.length % 16
+				unless (pad == 0 || pad == 8) and data[0...pad] == "\000" * pad
+					Log.warn "padding was not as expected #{pad} (#{data.length}) -> #{data[0...pad].inspect}"
+				end
+				data[pad..-1].scan(/.{16}/m).each do |data|
+					property, encoding = ('%08x' % data.unpack('V')).scan /.{4}/
+					key = property.hex
+					# doesn't make any sense to me. probably because its a serialization of some internal
+					# outlook structure...
+					next if property == '0000'
+					case encoding
+					when '0102', '001e', '001f', '101e', '101f', '000d'
+						# ignore on purpose. not sure what its for
+						# multivalue versions ignored also
+					when '0003' # long
+						# don't know what all the other data is for
+						add_property key, *data[8, 4].unpack('V')
+					when '000b' # boolean
+						# again, heaps more data than needed. and its not always 0 or 1.
+						# they are in fact quite big numbers. this is wrong.
+# 					p [property, data[4..-1].unpack('H*')[0]]
+						add_property key, data[8, 4].unpack('V')[0] != 0
+					when '0040' # systime
+						# seems to work:
+						add_property key, Ole::Types.load_time(data[8..-1])
+					else
+						#Log.warn "ignoring data in __properties section, encoding: #{encoding}"
+						#Log << data.unpack('H*').inspect + "\n"
+					end
+				end
+			end
+
+			def add_property key, value, pos=nil
+				# map keys in the named property range through nameid
+				if Integer === key and key >= 0x8000
+					if !@nameid
+						Log.warn "no nameid section yet named properties used"
+						key = Key.new key
+					elsif real_key = @nameid[key]
+						key = real_key
+					else
+						# i think i hit these when i have a named property, in the PS_MAPI
+						# guid
+						Log.warn "property in named range not in nameid #{key.inspect}"
+						key = Key.new key
+					end
+				else
+					key = Key.new key
+				end
+				if pos
+					@cache[key] ||= []
+					Log.warn "duplicate property" unless Array === @cache[key]
+					# ^ this is actually a trickier problem. the issue is more that they must all be of
+					# the same type.
+					@cache[key][pos] = value
+				else
+					# take the last.
+					Log.warn "duplicate property #{key.inspect}" if @cache[key]
+					@cache[key] = value
+				end
+			end
+
+			# delegate to cache
+			def method_missing name, *args, &block
+				@cache.send name, *args, &block
+			end
+		end
+
+		# these 2 will actually be of the form
+		# 1\.0_#([0-9A-Z]{8}), where $1 is the 0 based index number in hex
+		# should i parse that and use it as an index, or just return in
+		# file order? probably should use it later...
+		ATTACH_RX = /^__attach_version1\.0_.*/
+		RECIP_RX = /^__recip_version1\.0_.*/
+		VALID_RX = /#{PropertyStore::VALID_RX}|#{ATTACH_RX}|#{RECIP_RX}/
+
+		attr_reader :root
+		attr_accessor :close_parent
+
+		# Alternate constructor, to create an +Msg+ directly from +arg+ and +mode+, passed
+		# directly to Ole::Storage (ie either filename or seekable IO object).
+		def self.open arg, mode=nil
+			msg = new Ole::Storage.open(arg, mode).root
+			# we will close the ole when we are #closed
+			msg.close_parent = true
+			if block_given?
+				begin   yield msg
+				ensure; msg.close
+				end
+			else msg
+			end
+		end
+
+		# Create an Msg from +root+, an <tt>Ole::Storage::Dirent</tt> object
+		def initialize root
+			@root = root
+			@close_parent = false
+			super PropertySet.new(PropertyStore.load(@root))
+			Msg.warn_unknown @root
+		end
+
+		def self.warn_unknown obj
+			# bit of validation. not important if there is extra stuff, though would be
+			# interested to know what it is. doesn't check dir/file stuff.
+			unknown = obj.children.reject { |child| child.name =~ VALID_RX }
+			Log.warn "skipped #{unknown.length} unknown msg object(s)" unless unknown.empty?
+		end
+
+		def close
+			@root.ole.close if @close_parent
+		end
+
+		def attachments
+			@attachments ||= @root.children.
+				select { |child| child.dir? and child.name =~ ATTACH_RX }.
+				map { |child| Attachment.new child }.
+				select { |attach| attach.valid? }
+		end
+
+		def recipients
+			@recipients ||= @root.children.
+				select { |child| child.dir? and child.name =~ RECIP_RX }.
+				map { |child| Recipient.new child }
+		end
+
+		class Attachment < Mapi::Attachment
+			attr_reader :obj, :properties
+			alias props :properties
+
+			def initialize obj
+				@obj = obj
+				@embedded_ole = nil
+				@embedded_msg = nil
+
+				super PropertySet.new(PropertyStore.load(@obj))
+				Msg.warn_unknown @obj
+
+				@obj.children.each do |child|
+					# temp hack. PropertyStore doesn't do directory properties atm - FIXME
+					if child.dir? and child.name =~ PropertyStore::SUBSTG_RX and
+						 $1 == '3701' and $2.downcase == '000d'
+						@embedded_ole = child
+						class << @embedded_ole
+							def compobj
+								return nil unless compobj = self["\001CompObj"]
+								compobj.read[/^.{32}([^\x00]+)/m, 1]
+							end
+
+							def embedded_type
+								temp = compobj and return temp
+								# try to guess more
+								if children.select { |child| child.name =~ /__(substg|properties|recip|attach|nameid)/ }.length > 2
+									return 'Microsoft Office Outlook Message'
+								end
+								nil
+							end
+						end
+						if @embedded_ole.embedded_type == 'Microsoft Office Outlook Message'
+							@embedded_msg = Msg.new @embedded_ole
+						end
+					end
+				end
+			end
+
+			def valid?
+				# something i started to notice when handling embedded ole object attachments is
+				# the particularly strange case where there are empty attachments
+				not props.raw.keys.empty?
+			end
+		end
+
+		#
+		# +Recipient+ serves as a container for the +recip+ directories in the .msg.
+		# It has things like office_location, business_telephone_number, but I don't
+		# think enough to make a vCard out of?
+		#
+		class Recipient < Mapi::Recipient
+			attr_reader :obj, :properties
+			alias props :properties
+
+			def initialize obj
+				@obj = obj
+				super PropertySet.new(PropertyStore.load(@obj))
+				Msg.warn_unknown @obj
+			end
+		end
+	end
+end
+