MIME

Table of Contents >> Optional Protocols

Description

MIME is an acronym for Multipurpose Internet Mail Extensions, and refers to an set of Internet standards that specify how messages must be formatted so that they can be exchanged between different email systems. MIME is a very flexible format, permitting one to include virtually any type of file or document in an email message. Specifically, MIME messages can contain text, images, audio, video, or other application-specific data.

The Treck MIME engine is designed to be a data stream processor to maximize its usability with a simple implementation and small footprint.

Use Case

Here is a typical use case of the MIME engine:

1. User creates a new MIME message (a small data structure)
2. User adds MIME parts to the MIME message, no real MIME data is added in, just the descriptions of how to get the input data for each part, and how to encode the part. The data source could be a file, static buffer, or dynamic content.
3. User asks the MIME message for a specified size of a buffer out of the encoded stream, the MIME encoding engine gets just enough data from the input source, encodes it, and puts it into the user-provided output buffer.
4. User uses the encoded buffer in whatever way they wish, e.g. send it as an email body, send it to a HTTP client, save it as a file, etc.
5. User repeats steps 3 and 4 until no more encoded buffers are available.
6. User frees the MIME message.

Memory Usage

Since the MIME message is not trying to hold all of the data sources, it takes a very small amount of memory just to hold the parts desciptions. The major run-time memory usage is the temporary buffer used to hold an input buffer. It is dynamically allocated and its size is proportional to the size of the encoded buffer asked for by the user.

Function References

• tfMimeNewMessage()
• tfMimeFreeMessage()
• tfMimeAddPart()
• tfMimeGetHeader()
• tfMimeGetBody()
• tfMimeReset()
• tfMimeSrcFunc()

Macro References

Macro	Description
TM_MIME_ENCODING_BASE64	Base 64 encoding scheme
TM_MIME_INLINE	Inline disposition type
TM_MIME_ATTACH	Attachment disposition type
TM_MIME_MIN_BUFFER_LEN	Minimum buffer size for function tfMimeGetBody()

Examples

Construct a MIME Message

 
#ifdef TM_USE_MIME
ttMimeHandle mimeHandle;
int          errorCode;
 
/* craete a Mime message */
mimeHandle = tfMimeNewMessage();
if (mimeHandle == (ttMimeMessagePtr)0)
{
/* Not enough memory available */
    goto CONSTRUCT_MIME_MESSAGE_EXIT;
}
 
/* Add the attachments as generic application octet*/
errorCode = tfMimeAddPart(mimeHandle, 
                          "c:\\test.jpg", 
                          tfxMimeFileSourceFun, 
                          "test.jpg", 
                          "application/octet-stream",
                          TM_MIME_ENCODING_BASE64);
if (errorCode != TM_ENOERROR)
{
    printf("tfMimeAddPart returned %s", tfStrError(errorCode));
    goto CONSTRUCT_MIME_MESSAGE_EXIT;
}
 
/* write the mail body as a file for debugging purppse */
FILE * filePtr = fopen("c:\\mime.eml", "w+");
if (filePtr != NULL)
{
    while((readLen = tfMimeGetCodedBuffer(mimeHandle, writeBuffer, 1024)) != 0)
    {
        fwrite(writeBuffer, 1, readLen, filePtr);
    }
    fclose(filePtr);
    tfMimeReset(m_mimeHandle);
 
CONSTRUCT_MIME_MESSAGE_EXIT:
    return;
}
#endif TM_USE_MIME
 
 

Callback Function

Two call back functions are available in '/examples/txmime.c'

Send MIME Encoded Email

An example of how to send a Mime message as a mail body is provided in '/examples/txsmtp.c'

Table of Contents >> Optional Protocols