|
The Mail Message component can be used to create and process
messages in the format defined by the Multipurpose Internet Mail
Extensions (MIME) standard. When a message is parsed, it is broken
into parts, each consisting of two sections. The first part is
called the header section and it describes the format of the data
and how it should be represented to the user. The second section is
the data itself. A typical mail message without file attachments
has one part, with the body of the message being the data. Messages
with attachments have multiple parts, each with a header describing
the type of data. The component can be then used to extract the
data from a multipart message and save it to a file on the local
system, delete the part from the message, or add additional parts
to the message, such as attaching a file.
The component can also be used to create new multipart messages
with alternative content, such a message with both plain text and
styled HTML text. Once a message has been created, files can be
attached to the message and the application can make any other
changes that are needed. The component provides complete access to
all headers and content in a multipart message, including the
ability to create your own custom headers and make modifications to
specific sections.
The following properties, methods and events are available for
use by your application:
Initialize
Initialize the component for the current process. The application
must call this method to initialize the component before setting
any properties or calling any other methods.
ComposeMessage
Compose a new message using the specified header field values and
content. Using this method, you can create a message with the From,
To, Cc and Subject headers already defined, along with any text for
the message. You can also optionally provide both plain and styled
HTML text versions of the message and the method will automatically
create a multipart message.
ClearMessage
Releases the memory allocated for the current message, including
any file attachments, and creates a new, empty message.
Uninitialize
Release any resources that have been allocated for the current
process. This is the last method call that the application should
make prior to terminating.
Message Headers
Each message has one or more headers fields which provide
information about the contents of the message. For example, the
"From" header field specifies the email address of the person who
sent the message. There are a fairly large number of header fields
defined by the MIME standard, and applications can also create
their own custom headers if they wish. The component gives the
application complete access to the header fields in a message.
Headers can be examined, modified, created or removed from the
message as needed.
GetHeader
This method copies the value of a header field into a string buffer
that you provide. To return the value of the common header fields
such as "From", "To" and "Subject", you should specify a message
part of zero by setting the MessagePart property.
GetFirstHeader
This method returns the value of the first header defined in the
current message part, copying it into the string buffer that you
provide. This is used in conjunction with the GetNextHeader method
to enumerate all of the headers that have been defined.
GetNextHeader
This method returns the value of the next header defined in the
current message part. It should be called in a loop until it
returns a value of zero (False) which indicates that the last
message header has been returned.
SetHeader
Set a message header field to the specified value in the current
message part. If the value is an empty string, the message header
will be deleted from the message.
DeleteHeader
Delete the specified message header from the current message
part.
Message Contents
The content or body of a message contains the text that is to be
read or processed by the recipient. It may be a simple, plain text
message or it may be more complex, such as a combination of plain
and styled HTML text or the data for a file attachment. The
component provides complete access to the contents of the message,
enabling the application to modify, extract, replace or delete
specific sections of the message.
Message
This property returns the current message, including the headers
and all message parts, as a string. Setting this property will
cause the current message to be cleared and replaced by the new
value. The string contents must follow the standard specifications
for a message. If the property is set to an empty string, the
current message is cleared.
Text
This property returns the body of the current message part. Setting
this property replaces the entire message body with the new
text.
SelLength, SelStart, SelText
The SelText property returns the selected message body text as
specified by the SelStart and SelLength properties. Setting this
property replaces text in the message body starting at the byte
offset specified by the SelStart property.
Multipart Messages
Most typical messages contain a single part, which consists of
the message headers followed by the contents of the message.
However, when files are attached to a message or alternative
content types such as HTML are used, a more complex multipart
message is required. With a multipart message, the contents of the
message are split into logical sections with each section
containing a specific part of the message. For example, when a file
is attached to a message, one part of the message contains the text
to be read by the recipient and another part contains the data for
the file.
The first of a multipart message is called part 0, and contains
the main header block. This is what defines the headers that you
are most familiar with, such as "From", "To" and "Subject". The
body of this message part is typically a plain text message that
indicates that this is a multipart message. This is done for the
benefit of older mail clients that cannot parse MIME messages
correctly. Next part, part 1, typically contains the actual body of
the message that would be displayed by the mail client. Additional
parts may contain file attachments and other information. In the
case of a multipart message that contains both plain and styled
HTML text versions of a message, part 1 is typically the plain text
version of the message while part 2 contains the HTML version. The
mail client can then make a decision based on its own configuration
as to which version of the message it displays.
Part
This property returns the current message part index. All messages
have at least one part, which consists of one or more header
fields, followed by the body of the message. The default part, part
0, refers to the main message header and body. If the message
contains multiple parts (as with a message that contains one or
more attached files), this property can be set to refer to that
specific part of the message.
PartCount
This property returns the number of parts in the current message.
All messages have at least one part, referenced as part 0.
Multipart messages will consist of additional parts which may be
accessed by setting the Part property.
CreatePart
Create a new, empty message part. If the message was not originally
a multipart message, it will be restructured into one. Otherwise,
the new part is simply added to the end of the message. This method
will cause the current message part to change to the new part that
was just created.
DeletePart
Delete the message part from the message. If the message part is in
the middle of the message, it will cause the subsequent parts of
the message to be reordered. You should not delete part zero to
delete a message; use the MimeDeleteMessage method instead.
Importing Messages
The component can be used to import existing messages, either
from memory or from a file. Once the message has been parsed, the
application can examine or modify specific parts of the message.
The following methods are provided to import the contents of a
message:
ImportMessage
The simplest method of importing a message, this method reads the
contents of the specified file and imports it into the current
message. This method is typically called immediately after
MimeCreateMessage to load a file into a new message context.
Exporting Messages
After a message has been created or modified, it can be exported
to a file or to memory. Exporting the message to a memory buffer is
particularly useful when using the component with another one of
the SocketTools libraries. For example, the contents of a message
can be exported to memory, and that memory address can be passed to
the Simple Mail Transfer Protocol (SMTP) component for delivery to
the recipient. The following methods are provided to export the
contents of a message:
ExportMessage
This method exports the current message to a file. When using this
method, only certain headers are exported and they may be
reordered. To force all headers to be included in the message or to
preserve the order of the headers, set the Options property.
File Attachments
In addition to simple text messages, one or more files can be
attached to a message. The process of attaching a file involves
creating a multipart message, encoding the contents of the file and
then including that encoded data in the message. The following
methods are provided to manage files attached to the message, as
well as attach files to an existing message:
Attachment
A property which returns the name of a file attachment in the
current message part. This property serves two purposes, to
determine if the current message part contains a file attachment,
and if so, what file name should be used when extracting that
attachment.
AttachFile
This method attaches the contents of the file to the message. The
file will be attached using the specified encoding algorithm and
will become the current message part. If the message is not a
multipart message, it will be converted to one; if it already is a
multipart message, the attachment will be added to the end of the
message.
AttachData
This method works in similar fashion to MimeAttachFile, except that
instead of the contents of a file, the data in a memory buffer will
be attached to the message. If the message is not a multipart
message, it will be converted to one; if it already is a multipart
message, the attachment will be added to the end of the
message.
ExtractFile
Extract the file attachment in the current message part, storing
the contents in a file. The attachment will automatically be
decoded if necessary. This method also recognizes uuencoded
attachments that are embedded directly in the body of the message,
rather than using the standard MIME format.
Mail Addresses
The Mail Message component also has methods which are designed
to make it easier to work with email addresses. Addresses are
typically in the format of "user@domain.com" however additional
information can be included with the address, such as the user's
name or other comments that aren't part of the address itself. The
component can parse these addresses for you, returning them in a
format that is suitable for use with other protocols such as the
SMTP component.
ParseAddress
Parse an email address that may include an address without a domain
name or comments in the address, such as the user's name. For
example, the From header field may return an address like "Joe
Smith <joe@bigcorp.com>"; this method would parse the address
and return "joe@bigcorp.com", the actual address for the user.
Recipient
It is common for certain headers to contain multiple addresses
separated by a comma. These addresses may also include comments
such as the user's name. This property array returns a list of
valid addresses defined in the current message. For example, the To
header field may contain "Tom Jones <tom@bigcorp.com>, Jerry
Lewis <jerry@bigcorp.com>"; this property array would return
"tom@bigcorp.com" and "jerry@bigcorp.com" as the two addresses
listed. The total number of addresses that are available is
returned by the Recipients property.
|