|
The Mail Message library 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 library 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 library 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 library 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 first step that your application must take is to initialize
the library, then establish a connection to the server and
authenticate the client. The following functions are available for
use by your application:
MimeInitialize
Initialize the library for the current process. This must be the
first function call that the application makes before calling the
other MIME API functions.
MimeComposeMessage
Compose a new message using the specified header field values and
content. Using this function, 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 function will
automatically create a multipart message. The function returns a
handle which can be used by the application to make further
modifications, such as attaching files to the message.
MimeCreateMessage
Create a new, empty message and return a handle which can be used
by the application to reference the message. In most cases, using
the MimeComposeMessage function is preferred, however there may be
some situations where the application needs a message handle when
the contents of the message aren't known at the time. For example,
parts of a message may be created dynamically based on the results
of several database queries.
MimeDeleteMessage
Releases the memory allocated for the message and destroys the
message handle. After this function returns, the handle is no
longer valid. This function should be called when the message is no
longer needed by the application.
MimeUninitialize
Release any resources that have been allocated for the current
process. This is the last function 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 library 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.
MimeGetMessageHeader
This function returns a pointer to a null terminated string which
contains the value of the specified header field in the current
message part. For languages like Visual Basic, it is recommended
that you use the MimeGetMessageHeaderEx function instead.
MimeGetMessageHeaderEx
This function copies the value of a header field into a null
terminated string buffer that you provide. This function also
allows you to specify the message part in a multipart message. To
return the value of the common header fields such as "From", "To"
and "Subject", you should specify a message part of zero.
MimeGetFirstMessageHeader
This function 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
MimeGetNextMessageHeader function to enumerate all of the headers
that have been defined.
MimeGetNextMessageHeader
This function 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.
MimeSetMessageHeader
Set a message header field to the specified value in the current
message part. If the value is a null pointer or empty string, the
message header will be deleted from the message.
MimeSetMessageHeaderEx
Set a message header field to the specified value. This version of
the function allows you to also specify the message part, rather
than just using the current message part. To return the value of
the common header fields such as "From", "To" and "Subject", you
should specify a message part of zero. If the value is a null
pointer or empty string, the message header will be deleted from
the message.
MimeDeleteMessageHeader
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 library
provides complete access to the contents of the message, enabling
the application to modify, extract, replace or delete specific
sections of the message.
MimeGetMessageText
Copy the text from the body of the current message part into a null
terminated string buffer. The offset and length of the text being
copied can be specified, which enables you to return just a portion
of the message. For example, it would be possible to return just
the first 1K byte of a text message.
MimeSetMessageText
Set or replaces the text in the body of the current message part.
You can specify an offset in this function, enabling you to replace
just portions of the message.
MimeAppendMessageText
Append text to the body of the current message part. Instead of
replacing existing text, the new text will be added to the end of
the message.
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.
MimeGetMessagePartCount
Return the number of parts in the message. A simple message will
contain just one part. This can be used to determine if the message
is a MIME multipart message, with a value greater than one
indicating that it is.
MimeGetMessagePart
Return the current message part. Each message has the concept of a
"current message part", which is the default message part that the
other functions will use. When a message is first created, the
current message part is zero. The simplest way to think of message
parts is as a zero-based index into an array into sections of the
message.
MimeSetMessagePart
Change the current message part. Once the current message part has
been set, it will remain as the current part until explicitly
changed or until a new message part is created.
MimeCreateMessagePart
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
function will cause the current message part to change to the new
part that was just created.
MimeCreateMessagePartEx
Create a new message part using the specified character set and
text. 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 function will cause the
current message part to change to the new part that was just
created.
MimeDeleteMessagePart
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 function instead.
Importing Messages
The library 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 functions are provided to import the contents of a
message:
MimeImportMessage
The simplest method of importing a message, this function reads the
contents of the specified file and imports it into the current
message. This function is typically called immediately after
MimeCreateMessage to load a file into a new message context.
MimeImportMessageEx
This version of the function enables you to import the message from
a file, the system clipboard, a pointer to a memory buffer or a
global memory handle. This is typically used to import messages
that were retrieved using the POP3 or IMAP protocols by passing a
pointer to the buffer that contains the data returned by the
server.
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 library 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) library for delivery to the
recipient. The following functions are provided to export the
contents of a message:
MimeExportMessage
This function exports the current message to a file. When using
this function, 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, use the extended version of this
function.
MimeExportMessageEx
This extended version of the function exports the message to a
file, the system clipboard, a memory buffer or returns a handle to
a global memory buffer that contains the message. There are
additional options that enable you to control what headers are
exported, and whether the order the headers were set should be
preserved.
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
functions are provided to manage files attached to the message, as
well as attach files to an existing message:
MimeAttachFile
This function 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.
MimeAttachData
This function 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.
MimeAttachImage
This function attaches an inline image file to the message. It is
similar to the MimeAttachFile function, except that the image is
designed to be referenced as an embedded graphic in an HTML
message. This function 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.
MimeGetAttachedFileName
Return the name of a file attachment in the current message part.
This function 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.
MimeExtractFile
Extract the file attachment in the current message part, storing
the contents in a file. The attachment will automatically be
decoded if necessary. This function also recognizes uuencoded
attachments that are embedded directly in the body of the message,
rather than using the standard MIME format.
Mail Addresses
The library has functions 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 library can parse these
addresses for you, returning them in a format that is suitable for
use with other protocols such as the SMTP library.
MimeParseAddress
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 function would parse the
address and return "joe@bigcorp.com", the actual address for the
user.
MimeEnumMessageRecipients
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 function parses a string and returns
a list of valid addresses. For example, the To header field may
contain "Tom Jones <tom@bigcorp.com>, Jerry Lewis
<jerry@bigcorp.com>"; this function would return
"tom@bigcorp.com" and "jerry@bigcorp.com" as the two addresses
listed.
Message Storage
The library has a collection of functions 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.
MimeOpenMessageStore
This function is used to open an existing message store or create a
new one. The function returns a handle which is used to access the
messages in the storage file, and must be closed using the
MimeCloseMessageStore function. The storage files may either be
plaintext, or stored in a compressed format. It also supports
opening storage files in the UNIX mbox format.
MimeGetStoredMessageCount
This function returns the number of messages that currently in the
message store. Each message is referred to by an integer which is
its index into the storage file. The first stored message has a
value of 1, and increments with each additional message in the
storage file.
MimeFindStoredMessage
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 function 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.
MimeGetStoredMessage
This function returns a handle to the message in the storage file,
and can be used with any of the other functions in the Mail Message
API. The application can also request its own private copy of the
message, which it can modify independently of what is currently in
the message store.
MimeStoreMessage
This function stores a new message, specified by its message
handle, to the open message store. Note that the message store must
be opened for write access, and this function will always append
the message to the storage file. The new message index is returned
to the caller.
MimeDeleteStoredMessage
This function 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.
MimeReplaceStoredMessage
This function replaces an existing message in the storage file,
overwriting it with the specified message. Unlike many of the other
functions which do not permit the application to reference a
deleted message, this function can be used to replace a previously
deleted message.
MimeCloseMessageStore
The message store must be closed when the application has finished
accessing it. The storage file is updated with any changes, all
deleted messages are purged and the handle to the open file is
closed. If the storage file is locked for exclusive access, this
function will release that lock, allowing another process to open
the file.
|