NAME
    Mail::Exchange::Tutorial - Introduction to the Mail::Exchange classes
    and Interface

DESCRIPTION
  Introduction
    Microsoft Exchange, as a server application, uses a proprietary binary
    protocol when communicating with Microsoft Outlook as a client program.
    This protocol is tightly connected to the internal format used to store
    message objects, which in turn is tightly connected to the binary format
    (.msg) that Outlook uses to store messages in files.

    Right now, the Mail::Exchange classes are little more than a facility to
    read and write .msg files, but it is expected they grow into a more
    complete way to interact with an Exchange Server in the future.

  Data structures
    A Message object, in Exchange/Outlook, is something like a Property
    Container, that contains a list of property/value pairs. Many often-used
    properties are pre-defined by Microsoft, having constant, unique,
    property IDs, along with property types like String, Integer, Time etc.
    A (more or less) complete list of these properties is defined in
    [MS-OXPROPS], and they are made available by the
    Mail::Exchange::PidTagIDs module.

    In addition to those properties, Microsoft defines named properties as
    well. These may be string named properties, which are, for example, used
    for non-standard Internet Headers, or numerical named properties, which
    abbreviate often-used strings with a 2 byte number, and define a data
    type, just like the standard properties do. These numeric named
    Properties are listed in Mail::Exchange::PidLidIDs.

    There are two data object types may occur more than once in a message
    object - Attachments and Recipients. A message can have only one sender,
    but several recipients, with each of them having properties like email
    address, address type ('To', 'Cc', 'Bcc'), and real names. Thus,
    Attachments and Recipients have their own Object type, of which zero or
    more instances can be attached to a message. Mail::Exchange::Attachment
    and Mail::Exchange::Recipient are the classes to handles these data
    objects.

  Reading Message Files
    When creating a new Message object, the new() method can be given a
    filename parameter. This will read in the complete message object, from
    which properties can be extracted afterwards:

        my $msg=Mail::Exchange::Message->new("my.msg");
        print "Subject: ", $msg->get(PidTagSubject), "\n";

  Writing Message Files
    Message Files can be created by modifying existing ones, or by creating
    them from scratch. Also, there is a method to import a MIME-formatted
    email message into a Message object.

   Modifying existing Message files
    To modify an existing message file, read it in as above, set the
    properties you want changed, and write it out to the same or a different
    file name:

        my $msg=Mail::Exchange::Message->new("original.msg");
        $msg->set(PidTagImportance, 2);
        $msg->set('received-spf', 'none', 6, PtypString,
                     "00020386-0000-0000-c000-000000000046");
        $msg->setSubject('new subject');
        $msg->save('changed.msg');

    The primary method to set Properties is the "set" method. Its first
    parameter is either a standard PidTag property, a numeric named PidLid
    property, or a string named property. In the case of PidTag or PidLid
    properties, their type is already known to the message object, but for
    string named properties, the property data type and property use guid
    must be given. Property data types are defined in
    Mail::Exchange::PropertyTypes.pm, while GUIDs can be taken from
    [MS-OXPROPS] section 1.3.2. The above example GUID is defined to contain
    Internet Headers.

    For some often uses Properties, there are abbreviation functions, like
    setSubject. These abbreviation functions may set several properties at
    once, so it makes sense to use them where possible.

   Creating message files from scratch
    The Mail::Exchange::Message->new method, when called without a file
    parameter, creates an empty message object, but sets a few of the most
    important message properties in it. However, it does NOT set the message
    type, which can be one of Calendar entry, ToDo task entry, Mail, or
    various others. So, to create an email message, it is better to use
    Mail::Exchange::Message::Email->new to create an email message object.
    (At the time of this writing, Email ist the only existing subclass, more
    are expected to be implemented in the future).

    After creating an empty message, set some properties in it and save it,
    like in

        my $message=Mail::Exchange::Message::Email->new();
        $message->setUnicode(1);
        $message->setSender('somebody@somewhere.com');
        $message->setDisplayTo("Doe, John <jdoe@target.com>");
        $message->setSubject("trying out message files");
        $message->setBody("hello world");

        my $recipient=Mail::Exchange::Recipient->new();
        $recipient->setEmailAddress("jdoe@target.com");
        $recipient->setDisplayName("Doe, John");
        $message->addRecipient($recipient);

        $message->save("mail.msg");

    If you want to prepare a message to be sent by Outlook, set the
    "mfUnsent" message flag before saving it:

        $message->set(PidTagMessageFlags, mfUnsent);

    This way, you'll get your standard "send" button from Outlook, so you
    can prepare a message from perl, review it in Outlook, and send it just
    like you'd written it yourself. If you don't set this flag, the message
    will be displayed by outlook like one in your inbox - you can reply to
    it, forward it, or save attachments as files, but can't send it again.

   Adding recipients
    For each recipient you want your message to have, you need to create a
    Mail::Exchange::Recipient object and add it to the message:

        my $recipient=Mail::Exchange::Recipient->new();
        $recipient->setEmailAddress('jdoe@target.com');
        $recipient->setDisplayName('Doe, John');
        $recipient->setType("To");

        my $recipient=Mail::Exchange::Recipient->new();
        $recipient->setEmailAddress('mdae@target.com');
        $recipient->setDisplayName('Dae, Mary');
        $recipient->setType("To");

        my $recipient=Mail::Exchange::Recipient->new();
        $recipient->setEmailAddress('bob@another.target.org');
        $recipient->setDisplayName('Bob');
        $recipient->setType("Cc");

        $message->addRecipient($recipient);

        $message->setDisplayTo("Doe, John; Dae, Mary");
        $message->setDisplayCc("Bob");

    Adding a recipient will _not_ make that recipient show in the To: and
    CC: boxes in Outlook, you have to use setDisplayTo, setDisplayCC (and
    setDisplayBcc) to set these entries.

   Adding attachments
    Just like with recipients, you can add attachments to a Message object:

        my $attachment=Mail::Exchange::Attachment->new("file.dat");
        $message->addAttachment($attachment);

    If you pass an existing file name to the constructor, all properties
    that can be derived from the file (name, content, extension, creation
    and modification time, ...) will be set automatically. Or, you can use a
    string for the contents of a file, but you'll have to set other
    properties yourself:

        my $attachment=Mail::Exchange::Attachment->new();
        $attachment->setString($content);
        $attachment->setFileName("string.dat");
        $attachment->set(PidTagCreationTime, mstime_to_unixtime(time());
        $attachment->set(PidTagLastModificationTime, mstime_to_unixtime(time());

        $message->addAttachment($attachment);

  Reading MIME Mail files
    To read in a MIME mail file, use Email::MIME to parse it first. Then,
    you can use the Mail:Exchange::Message::Email->fromMIME constructor to
    turn it into a Message object:

        open(MAIL, "<$message.mime");
        do {
            local $/;
            $mail=<MAIL>;
        };
        close MAIL;

        $parsed=Email::MIME->new($mail);
        $msg=Mail::Exchange::Message::Email->fromMIME($parsed);

        $msg->save("message.msg");

AUTHOR
    Guntram Blohm <gbl at bso2001 dot com>

REFERENCES
    A good amount of documentation by Microsoft can be downloaded from:
    http://msdn.microsoft.com/en-us/library/cc425499(v=exchg.80).aspx

BUGS
    Probably many. This implementation is quite new, so there's lots of
    stuff not finished yet. However, the basic functions work. Still, please
    don't use this library in a context where bugs might do any harm. As
    always, there is no warranty at all.

