MAPI32::MAPISendMail以邮件附件形式发送文件

MAPISendMail

The MAPISendMail function sends a message, this function differs from the MAPISendDocuments function in that it allows greater flexibility in message generation.

Header file:MAPI.H

ULONG FAR PASCAL MAPISendMail(

LHANDLE lhSession,

 ULONG ulUIParam,

lpMapiMessage lpMessage,

 FLAGS flFlags,

ULONG ulReserved )

Parameters

lhSession

[in] handle to a simple MAPI session or zero. If the value of  the lhSession parameter is zero, MAPI logs on the user and creates a session that exists only for the duration of the call. This temporary session can be an existing shared session or a new one. If necessary, the logon dialog box is displayed.

ulUIParam

[in] Parent window handle or zero.indicating that if a dialog box is displayed, it is application modal. If the ulUIParam contains a parent window handle, it is of type HWND (cast TO A ULONG). If no dialog box is displayed during the call, ulUIParam is ignored.

lpMessage

[in] pointer to a MapiMessage structure containing the message to be sent. If the MAPI_DIALOG flag is not set, the nRecipCount and lpRecips members must be valid for sucessful message delivery. Client application can set the flFlags member to MAPI_RECEIPT_REQUESTED to request a read report. All other members are ignored and unused pointers should be NULL.

flFlags

[in] bitmark of option flags. The following flags can be set:

MAPI_DIALOG

A dialog box should be displayed to prompt the user for recipients and other sending options. When MAPI_DIALOG is not set, at least one recipient must be specified.

MAPI_LOGON_UI

A dialog box should be displayed to prompt the user to log on if required. When the MAPI_LOGON_UI is not set, the client application does not display a logon dialog box and returns an error value if the user is not logged on. MAPISendMail ignores this flag if the lpszMessageID parameter is empty.

MAPI_NEW_SEEEION

An attempt should be made to create a new session rather that acquire the environment's shared session. If the MAPI_SESSION flag is not set, MAPISendMail uses an existing share session.

ulReserved

Reserved; must be zero.

Return Values

MAPI_E_AMBIGUOUS_RECIPIENT

A recipient matched more than one of the recipient descriptor structures and MAPI_DIALOG was not set. No message was sent.

MAPI_E_ATTACHMENT_NOT_FOUND

The specified attachment was not found. No message was sent.

MAPI_E_ATTACHMENT_OPEN_FAILURE

The specified attachment could not be opened. No message was sent.

MAPI_E_BAD_RECIPTYPE

The type of a recipient was not MAPI_TO, MAPI_CC, or MAPI_BCC. No message was sent.

MAPI_E_FAILURE

One or more unspecified errors occurred. No message was sent.

MAPI_E_INSUFFICIENT_MEMORY

There was insufficient memory to proceed. No message was sent.

MAPI_E_INVALID_RECIPS

One or more recipients were invalid or did not resolve to any address.

MAPI_E_LOGIN_FAILURE

There was no default logon, and the user failed to log on successfully when the logon dialog box was displayed. No message was sent.

MAPI_E_TEXT_TOO_LARGE

The text in the message was too large. No message was sent.

MAPI_E_TOO_MANY_FILES

There were too many file attachments. No message was sent.

MAPI_E_TOO_MANY_RECIPIENTS

There were too many recipients. No message was sent.

MAPI_E_UNKNOWN_RECIPIENT

A recipient did not appear in the address list. No message was sent.

MAPI_E_USER_ABORT

The user canceled one of the dialog boxes. No message was sent.

SUCCESS_SUCCESS

The call succeeded and the message was sent.

Remarks

The MAPISendMail function sends a standard message, with or without any user interface. The profile must be configured so that MAPISendMail can open the default service paroviders without requiring user interface. However, if the flFlags parameter is set to MAPI_NEW_SESSION, disallowing the use of a shared session, and the profile requires a passsword, MAPI_LONON_UI must be set or  the function will fall. Client application can avoid this situation by using an explicit profile without a password or by using the default profile without a password.

Client application can provide a full or partial of recipient names, subject text,file attachments,or message text. If any information is missing, MAPISendMail can prompt the user for it. If no information is missing, either the message can be sent as if or the user can be prompted to verify the information, changing values if necessary.

A successful return form MAPISendMail does not necessarily imply recipient validation. The message might not have been sent to all recipients. Depending on the transport provider, recipient validation can be a lengthy process.

A NULL value for the lpszSubject member of the MapiMessage structure pointed to by the lpMessage parameter indicates that there is not text for the subject of the message.

A NULL value for the lpszNoteText member indicate that there is no message text. Some client application can truncate subject lines that are too long or contain carriage returns, line feeds, or form feeds.

Each paragraph should be terminated with a CR(OXOD), and LF(0X0a), or a CRLF(0X0D0A). MAPISendMail wraps lines as appropriate. If the text exceeds system limits, the function returns the MAPI_E_TEXT_TOO_LARGE values.

The lpszMessageType member of the MapiMessage structure pointed by lpMessage is used only by non_IPM applications. Applications that handle IPM message can set it to NULL or have it point to an empty string.

The number of attachments per message of the MapiMessage structure can be limited in some messaging systems. If the limit is exceeded, the MAPI_E_TOO_MANY_FILES value if returned. If no files are specified, a pointer value of NULL should be assigned to the files do not affect the contents of the message. The files must be closed when they are copied. Do not attempt to display attachments outside the range of the message text.

Some messaging systems can limit the number of recipients per message. A pointer value of NUL  for the lpRecipts member in the MapiMessage structure pointed by the lpMessage indicates no recipients. If the client application passes a non-NUll value indicating a number of recipients exceeding the system limit, MAPISendMail returns the MAPI_E_TOO_MANY_RECIPIENTS value. If the value of the nRecipCount member in the MapiMessage structure is 0, the MAPI_DAILOG flag must be present in the call to MAPISendMail.

Note that the lpRecips member in the MapiMessage structure can include either an entry identifier, the recipient's name, and address, or a name and address pair. The following table show how MAPISendMail handles the variety of information that can be specified:

Information	Action
entry identifier	No name resolution; the name and address are ignored.
name	Name resolved using the Simple MAPI resolution rules.
address	No name resolution; address is used for both message delivery and for displaying the recipient name.
name and address	No name resolution; name used only for displaying the recipient name.

Client applications that send messages to custom recipients can avoid name resolution. Such clients should set the lpszAddress member of the MapiRecipDesc structure pointed to by the lpRecips member of the MapiMessage structure pointed to by the lpMessage parameter to the custom address.

MAPISendMail does not require an originator-type recipient to send a message.

MapiMessage (simple MAPI)

A MapiMessage structure contains information about a message.

Header file: MAPI.H

typedef struct {

ULONG ulReserved;

LPTSTR lpszSubject;

LPTSTR lpszNoteText;

LPTSTR lpszMessageType;

LPTSTR lpszDateReceived;

LPTSTR lpszConversationID;

FLAGS flFlags;

lpMapiRecipDesc lpOriginator;

ULONG nRecipCount;

lpMapiRecipDesc lpRecips;

ULONG nFileCount;

lpMapiFileDesc lpFiles;

}MapiMessage, FAR *lpMapiMessage;

Members

ulReserved

Reserved, must be zero.

lpszSubject

pointer to the text string describing the message subject, typically limited to 256 characters or less. If this member is empty or NULL, the user has not entered subject text.

lpszNoteText

pointer to a string containing the message text. If this member is empty or NULL, there is no message text.

lpszMessageType

Pointer to a string indicating a non-IPM type of message. Client application can select message types for their non_IPM messages. Clients that only support IPM messages can ignore the lpszMessageType member when reading messages and set it to empty or NULLwhen sending messages.

lpszDateReceived

Pointer to a string indicating the date when the message was received. The format is YYYY/MM/DD HH:MM, using a 24-hour clock.

lpszConversationID

pointer to a string identifying the conversation thread to which the message belongs. some messaging system can ignore and not return this member.

flFlagsBitmark of message status flags. The following flags can be set:

MAPI_RECEIPT_REQUESTED

A receipt notification is requested. Client applications set this flag when sending a message.

MAPI_SENT

The message has been sent.

MAPI_UNREAD

The message has not been read.

lpOriginatorPointer to a MapiRecipDescstructure containing information about the sender of the message.nRecipCountThe number of message recipient structures in the array pointed to by the lpRecipsmember. A value of zero indicates no recipients are included.lpRecipsPointer to an array of MapiRecipDescstructures, each containing information about a message recipient.nFileCountThe number of structures describing file attachments in the array pointed to by the lpFiles member. A value of zero indicates no file attachments are included.lpFilesPointer to an array of MapiFileDesc structures, each containing information about a file attachment.

 

MapiFileDesc (simple MAPI)

A MapiFileDesc structure contains information about a file containing a message attachment stored as a temporary file. That file can contain a static OLE object, an embedded OLE object, and embedded message, and other types of files.

typedef struct {

ULONG ulReserved;

ULONG flFlags;

ULONG nPosition;

LPTSTR lpszPathName;

LPTSTR lpszFileName;

LPVOID lpFileType;

} MapiFileDesc, FAR *lpMapiFileDesc;

Members

ulReserved

Reserved; must be zero.

flFlags

Bitmask of attachment flags. The following flags can be set:

MAPI_OLE

The attachment is an OLE object. If MAPI_OLE_STATIC is also set, the attachment is a static OLE object. If MAPI_OLE_STATIC is not set, the attachment is an embedded OLE object.

MAPI_OLE_STATIC

The attachment is a static OLE object.

If neither flag is set, the attachment is treated as a data file.

 

 

nPosition

An integer used to indicate where in the message text to render the attachment. Attachments replace the character found at a certain position in the message text. That is, attachments replace the character in the MapiMessage structure field NoteText[nPosition]. A value of – 1 (0xFFFFFFFF) means the attachment position is not indicated; the client application will have to provide a way for the user to access the attachment.

lpszPathName

Pointer to the fully qualified path of the attached file. This path should include the disk drive letter and directory name.

lpszFileName

Pointer to the attachment filename seen by the recipient, which may differ from the filename in the lpszPathName member if temporary files are being used. If the lpszFileName member is empty or NULL, the filename from lpszPathNameis used.

lpFileType

Pointer to the attachment file type, which can be represented with a MapiFileTagExt structure. A value of NULL indicates an unknown file type or a file type determined by the operating system.

Remarks

Simple MAPI works with three kinds of embedded attachments:

• Data file attachments
• Editable OLE object file attachments
• Static OLE object file attachments

Data file attachments are simply data files. OLE object file attachments are OLE objects that are displayed in the message text. If the OLE attachment is editable, the recipient can double-click it and its source application will be started to handle the edit session. If the OLE attachment is static, the object cannot be edited. The flag set in the flFlags member of the MapiFileDesc structure determines the kind of a particular attachment. Embedded messages can be identified by a .MSG extension in the lpszFileNamemember.

OLE object files are file representations of OLE object streams. The client application can recreate an OLE object from the file by calling the OLE function OleLoadFromStreamwith an OLESTREAM object that reads the file contents. If an OLE file attachment is included in an outbound message, the OLE object stream should be written directly to the file used as the attachment.

When using the MapiFileDesc member nPosition, the client application should not place two attachments in the same location. Client applications might not display file attachments at positions beyond the end of the message text.

Example

/*********************************************************************
* 函数名称:CSendEMailDlg::OnSendMapi
* 说明:  调用MAPI函数发送邮件。摘自 VC98/MFC/SRC/DOCMAPI.CPP
* 作者:  Geng
* 时间 : 2003-04-22 20:08:30 
*********************************************************************/

/*  m_list 为ListControl的变量 ,程序将ListControl中列出的所有item以附近形式发送，如果你的系统安装了Outlook发送邮件器，那么会启动它来作为邮件发送默认程序*/

/* code 为非Unicode版本 */
void CSendEMailDlg::OnSendMapi() 
{
    UpdateData(true); 

    //加载MAPI32.DLL动态库
    HMODULE hMod = LoadLibrary(_T("MAPI32.DLL")); 

    if (hMod == NULL)    //加载动态库失败
    {
        AfxMessageBox(AFX_IDP_FAILED_MAPI_LOAD);
        return;
    } 

    //获取发送邮件的函数地址
    ULONG (PASCAL *lpfnSendMail)(ULONG, ULONG, MapiMessage*, FLAGS, ULONG);
    (FARPROC&)lpfnSendMail = GetProcAddress(hMod, "MAPISendMail"); 

    if (lpfnSendMail == NULL)
    {
        AfxMessageBox(AFX_IDP_INVALID_MAPI_DLL);
        return;
    } 

    int nFileCount = m_list.GetCount();    //有多少个附件需要发送 

    //分配内存保存附件信息    不能使用静态数组，因为不知道要发送附件的个数
    MapiFileDesc* pFileDesc = (MapiFileDesc*)malloc(sizeof(MapiFileDesc) * nFileCount);
    memset(pFileDesc,0,sizeof(MapiFileDesc) * nFileCount); 

    //分配内存保存附件文件路径
    TCHAR* pTchPath = (TCHAR*)malloc(MAX_PATH * nFileCount); 

    CString szText;
    for(int i = 0;i < nFileCount;i++)
    {
        char* p = pTchPath + MAX_PATH * i;
        m_list.GetText(i,szText);
       strcpy(p,szText);
        (pFileDesc + i)->nPosition = (ULONG)-1;
        (pFileDesc + i)->lpszPathName = p;
        (pFileDesc + i)->lpszFileName = p;
    } 

    //收件人结构信息
    /*MapiRecipDesc recip;
    memset(&recip,0,sizeof(MapiRecipDesc));
    recip.lpszAddress    = m_szEmailMAPI.GetBuffer(0);
    recip.ulRecipClass = MAPI_TO;*/ 

    //邮件结构信息
    MapiMessage message;
    memset(&message, 0, sizeof(message));
    message.nFileCount    = nFileCount;                //文件个数
    message.lpFiles        = pFileDesc;                //文件信息
    //message.nRecipCount = 0;                        //收件人个数
    //message.lpRecips     = NULL;//&recip;                    //收件人
    //message.lpszSubject    = NULL; //m_szSubject.GetBuffer(0);    //主题
    //message.lpszNoteText= NULL;//m_szText.GetBuffer(0);    //正文内容 

    //保存本程序窗口指针，因为发完邮件后要返回本程序的窗口
    CWnd* pParentWnd = CWnd::GetSafeOwner(NULL, NULL); 

    //发送邮件
    int nError = lpfnSendMail(0, 0,
                    &message, MAPI_LOGON_UI|MAPI_DIALOG, 0); 

    if (nError != SUCCESS_SUCCESS && nError != MAPI_USER_ABORT 
            && nError != MAPI_E_LOGIN_FAILURE)
    {
        AfxMessageBox(AFX_IDP_FAILED_MAPI_SEND);
    } 

    //返回程序
    pParentWnd->SetActiveWindow(); 

    //不要忘了释放分配的内存
    free(pFileDesc);
    free(pTchPath);
    FreeLibrary(hMod);
}