Sending mail using the Microsoft Windows CE Mail API

Preface

Please note this article outlines the development of mail software on platforms Pocket PC 2000 and older only. Pocket 2002 had significantly changed how mail is handled by the OS. I suggest you read the aricles available at the Pocket PC Developers Network

Introduction

Windows CE provides support for Email Storage as part of the core operating system (ie. its comes on the ROM chip). Microsoft provides a series of API's in the library 'msgstore.lib' which its calls Microsoft Mail API or MAPI. These API's allow the developer to manipulate the Systems Email Folders . Although these API's provide functionality to manipulate the Systems Email Folders and the Emails within those folders, no support has yet been provided for the sending and receiving of Email Messages. Microsoft assumes that the responsibility is upon the developer of the Email Client to provide these services.

//Includes

#include "msgstor2.h"

#include "msgstore.h"



CDummyMailClass::SendMail(CString csReciepent, CString csSubject, 
                          CString csBodyText, CString csAttachment)
{
    CTime      p_CurrentTime    = CTime::GetCurrentTime();
    SYSTEMTIME p_CurrentSystemTime;
    HANDLE     p_hMail          = NULL;    //This holds a Handle to our mail context

    BOOL       p_bReturn        = FALSE;
    MailMsg    p_MailMsg;


    //Open the mail context and return a handle to it

    p_bReturn = MailOpen(&p_hMail, TRUE)

        ASSERT(p_bReturn);

    if(!p_bReturn)
    {
        RptMailError(p_hMail);
    }

    //

    p_CurrentTime.GetAsSystemTime(p_CurrentSystemTime);

    memset(&p_MailMsg,0,sizeof(MailMsg));

    //A new message ID will assigned by the system when we call MsgPut

    p_MailMsg.dwMsgId=0;

    //Indicate that the mail is to be placed into the Outbox and its status 

    //is composed

    p_MailMsg.dwFlags=MAIL_FOLDER_OUTBOX | MAIL_STATUS_COMPOSED; 

    //Set up the time of sending as the current system time

    SystemTimeToFileTime(&p_CurrentSystemTime,&p_MailMsg.ftDate);

    //The service name as specify by msdn

    p_MailMsg.szSvcNam = _T("Windows CE Inbox Services");

    //The Messages body

    p_MailMsg.szBody = (LPTSTR) (LPCTSTR) csBodyText;


    p_bReturn = MailSetField ( &p_MailMsg, _T( "To" ), 
        (LPTSTR) (LPCTSTR) csReciepent );

    ASSERT(p_bReturn);

    p_bReturn = MailSetField ( &p_MailMsg, _T( "Subject" ),
        (LPTSTR) (LPCTSTR)  csSubject);

    ASSERT(p_bReturn);

    //Put the mail messages into the outgoing folder


    p_bReturn = MailPut ( p_hMail, &p_MailMsg);

    ASSERT(p_bReturn);


    //Close the handle to the open Mail Context, releasing the associated 

    //resources

    BOOL p_bReturn = MailClose(&p_hMail);

    ASSERT(p_bReturn);

}

Ok, so we have provided some basic functionality. However what is not immediately evident is that the above code, places any messages it creates into the Activesync Outbox. Under Windows CE the Mail Folders are Hierarchical, the standard mail folders; inbox, outbox, deleted, etc are created below a root folder. Whenever a mail client (in most cases Microsoft Outlook) configures a new Transport, it will also create a new root folder and subfolders to hold messages for that transport. A newily installed Windows CE system comes with the ActiveSync transport already installed and configured (send and recieving of mail via a desktop pc) and then the user can configure other transports, such as IMAP or SMTP. So therefore let us assume that our application needs to send Mail via Simple Mail Transport Protocol (SMTP), therefore all our new messages need to be placed in the SMTP 'Outbox'.

FID    p_ParentFolderId;
FID    p_FolderId;

//Get The Folder Id of the Root Folder for the SMTP transport

p_bReturn = MailGetFolderIdEx(p_hMail, MAIL_FOLDER_NONE, 
                              &p_ParentFolderId, _T("POP3 Mail"));

ASSERT(p_bReturn);

//Get the Folder Id of the Child Folder Outbox

p_bReturn = MailGetFolderIdEx(p_hMail, p_ParentFolderId, &p_FolderId, 
                              _T("Outbox"));

ASSERT(p_bReturn);

//Specify the into folder which the new mail is be put.

p_bReturn = MailPutEx ( p_hMail, &p_MailMsg, p_FolderId );

ASSERT(p_bReturn);

So lets add some more functionality. Application will often wish to attach files to Emails they are sending. Please note, any files you attach to Emails will be automatically deleted by the API.

MailAtt p_MailAttachment;
BOOL    p_bReturn;

memset(&p_MailAttachment, 0, sizeof(MailAtt));

// Setup the Mail Attachment Structure

//This must be incremented for every new attachment to a mail

p_MailAttachment.uiAttachmentNumber = 1;
p_MailAttachment.dwFlags = NULL;
// Not needed since we are sending a local file

p_MailAttachment.ulSize = NULL;
//The Orignal File Name (the file without the path)

p_MailAttachment.szOriginalName = (LPTSTR) (LPCTSTR) p_csFileName;
//The full path to the file

p_MailAttachment.szLocalName = (LPTSTR) (LPCTSTR) csAttachment;

p_bReturn = MailPutAttachment(p_hMail, &p_MailMsg, &p_MailAttachment);

ASSERT(p_bReturn);

A final word on Error Handling. The Mail API also provides fairly comprehensive error information, this can be accessed through the MailError* API calls.

INT        p_iBufferLength    = 100;
INT        p_iLineNumber    = 0;
CString    p_csErrorMsg;

MailErrorMsg (p_hMail , p_csErrorMsg.GetBuffer(p_iBufferLength), 
              p_iBufferLength, &p_iLineNumber);

p_csErrorMsg.ReleaseBuffer();

AfxMessageBox(p_csErrorMsg, MB_OK|MB_ICONSTOP);

For more information please see the MSDN article Using the Microsoft Windows CE Mail API . As I have said the Mail API is limited in that it doesn't actually send the Email. If this functionality is required a 'smtp.dll' is provided on the ROM, and is used by 'Outlook' to send Email via SMTP. Information on this library is not provided by Micrsoft, however its Exports are listed in the header 'msgxport.h'.

Any problems or question feel free to query me at Ray Kinsella