|
The Mail Message control 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
control 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 control 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 control 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 control for the current process. This method is
normally not used if the control is placed on a form in languages
such as Visual Basic. However, if the control is being created
dynamically using a function similar to CreateObject, then the
application must call this method to initialize the component before
setting any properties or calling any other methods in the
control.
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 control 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 control
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 zero. 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 control 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 control 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) control 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.
AttachImage
This method attaches an inline image file to the message. It is
similar to the AttachFile method, except that the image is designed
to be referenced as an embedded graphic in an HTML message. This
method will automatically set the correct header values for an inline
image attachment, and enables the developer to specify a content ID
which is used in the HTML 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 control 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 control can parse
these addresses for you, returning them in a format that is suitable
for use with other protocols such as the SMTP control.
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@example.com>"; this method would parse the
address and return "joe@example.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@example.com>, Jerry
Lewis <jerry@example.com>"; this property array would
return "tom@example.com" and "jerry@example.com"
as the two addresses listed. The total number of addresses that are
available is returned by the Recipients property.
Message Storage
The control has a collection of methods which makes it simple for an
application to store a group of messages together in a single file,
search for and retrieve specific message. The collection of messages is
referred to as a "message store" and messages may either be
stored in a plaintext format or in a compressed binary format.
OpenStore
This method is used to open an existing message store or creates a
new storage file. If a storage file has been opened previously, it
will be closed and the new storage file will be opened. The storage
files may either be plaintext, or stored in a compressed format. It
also supports opening storage files in the UNIX mbox format.
StoreSize
This property returns the total number of messages that currently in
the message store, including deleted messages. Each message is
referred to by an integer which is its index into the storage
file.
StoreIndex
This property specifies the current message index into the storage
file. Messages are identified by an integer value that starts at one
for the first message and increments for each additional message in
the storage file. If no message store has been opened, this property
will return a value of zero. Changing the value of this property
changes the current message index for the message store.
FindMessage
An application can search the message store for messages that match
any header value. Searches can be complete or partial, and may be
case-sensitive or case-insensitive. For example, this method can be
used to enumerate all of the messages in the storage file that were
sent by a specific user or match a specific subject.
ReadStore
This method reads a message from the storage file and replaces the
current message. If the application modifies the message, it can
replace the message in the storage file or discard the changes.
WriteStore
This method writes the current message to the message store. Note
that the message store must be opened for write access, and the
message will always be appended to the storage file. The StoreIndex
property is updated with the index value for the new message.
DeleteMessage
This method flags a message for deletion from the message store. Once
a message has been flagged for deletion, it may no longer be accessed
by the application. When the storage file is closed, the contents of
the deleted message will be removed from the file.
ReplaceMessage
This method replaces an existing message in the storage file,
overwriting it with the current message. Unlike many of the other
methods which do not permit the application to reference a deleted
message, this method can be used to replace a previously deleted
message.
CloseStore
The message store must be closed when the application has finished
accessing it. This method updates the storage file with any changes,
purges all deleted messages and closes the storage file. If the
storage file is locked for exclusive access, this method will release
that lock, allowing another process to open the file.
|