lib/mapi/msg.rb
#
# = 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.
#
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 Attachments and Recipients 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.



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



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.



Parsing

There are three objects that need to be parsed to load a +Msg+ property store.

1. The +nameid+ directory (Properties.parse_nameid)
2. The many +substg+ objects, whose names should match Properties::SUBSTG_RX
(Properties#parse_substg)
3. The +properties+ file (Properties#parse_properties)

Understanding of the formats is by no means perfect.



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.
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 Attachments and Recipients 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 . 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 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 . Parsing There are three objects that need to be parsed to load a + Msg + property store . 1 . The + nameid + directory ( Properties . parse_nameid ) 2 . The many + substg + objects whose names should match Properties :: SUBSTG_RX ( Properties#parse_substg ) 3 . The + properties + file ( Properties#parse_properties ) Understanding of the formats is by no means perfect . 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 .
def recipients
			@recipients ||= @root.children.
				select { |child| child.dir? and child.name =~ RECIP_RX }.
				map { |child| Recipient.new child }
		end
def recipients @recipients ||= @root . children . select { | child | child . dir? and child . name =~ RECIP_RX } . map { | child | Recipient . new child } end
Introduction
A big compononent of +Msg+ files is the property store, which holds
all the key/value pairs of properties.
Introduction A big compononent of + Msg + files is the property store which holds all the key / value pairs of properties .