mapISENDMAILW 回呼函式 (mapi.h)
傳送 Unicode 訊息。 此函式會取代 ANSI 函式 MAPISendMail。
在 Windows 7 和更早版本上： 安裝 適用于 Windows 8 的 Microsoft Windows 軟體發展工具組 (SDK) ，並使用 MAPISendMailHelper 傳送訊息。
除非另有指定，否則所有資訊都適用于 MAPISendMailW 和 MAPISendMail 。
語法
MAPISENDMAILW Mapisendmailw;
ULONG Mapisendmailw(
[in] LHANDLE lhSession,
[in] ULONG_PTR ulUIParam,
[in] lpMapiMessageW lpMessage,
[in] FLAGS flFlags,
ULONG ulReserved
)
{...}
參數
[in] lhSession
類型： LHANDLE
簡單 MAPI 會話或零的控制碼。
如果 lhSession 參數的值為零，MAPI 會登入使用者，並建立只在呼叫期間存在的會話。 此暫存會話可以是現有的共用會話或新的會話。 如有必要，會顯示登入對話方塊。
[in] ulUIParam
類型： ULONG_PTR
父視窗控制碼或零。
如果 ulUIParam 參數包含父視窗控制碼，控制碼的類型為 HWND (轉換成 ULONG_PTR) 。
如果在呼叫期間未顯示任何對話方塊， 則會忽略 ulUIParam 。
[in] lpMessage
類型： lpMapiMessageW
MAPISendMailW結構的指標，其中包含要傳送的訊息。
| 成員 | 備註 |
|---|---|
| lpFiles | 當郵件沒有檔案附件時，請將此成員設定為 Null 。 |
| lpszMessageType | 由未處理個人訊息的應用程式所使用。 如果您的應用程式處理個人訊息，請將 lpszMessageType 成員設定為 Null ，或將它設定為指向空字串。 |
| lpszSubject | Null值表示訊息的主旨沒有文字。 |
| lpszNoteText | Null值表示訊息本文中沒有文字。 |
| lpRecips | Null值表示沒有收件者。 此外，當此成員為 Null時， nRecipCount 成員必須是零。 |
| nRecipCount | 值為零表示沒有收件者。 此外，當這個成員為零時， lpRecips 成員必須是 Null。 |
For more details about how the function handles recipient information, see Handling Recipient Information in Remarks.
[in] flFlags
類型： FLAGS
選項旗標的位元遮罩。 您可以設定下列旗標。
| 值 | 意義 |
|---|---|
|
應該會顯示應用程式強制回應對話方塊，以提示使用者輸入收件者和其他傳送選項。
如果未 設定MAPI_DIALOG 或 MAPI_DIALOG_MODELESS ，則必須至少指定一個收件者。 |
|
可在 Windows 上使用下一版 Office： 應該會顯示無強制回應對話方塊，以提示使用者輸入收件者和其他傳送選項。 如果 已設定MAPI_DIALOG_MODELESS ， lhSession 參數應該設定為零。 否則，如果設定此旗標且 lhSession 不是零，Outlook 將會引發例外狀況。 此外，如果已設定 MAPI_DIALOG_MODELESS ，系統會忽略 MAPI_NEW_SESSION 旗標。 如果未 設定MAPI_DIALOG 或 MAPI_DIALOG_MODELESS ，則必須至少指定一個收件者。 提示 若要在 Windows 7 或更早版本上使用這個旗標，您必須同時安裝 適用于 Windows 8 和下一版 Office 的 Windows SDK，而且您必須呼叫 MAPISendMailHelper 而不是 MAPISendMailW。
|
|
應該顯示對話方塊，以提示使用者視需要登入。
如果未設定 MAPI_LOGON_UI 旗標，用戶端應用程式就不會顯示登入對話方塊，而且如果使用者未登入，則會傳回錯誤值。 如果 lpszMessageID 參數是空的，則會忽略 MAPI_LOGON_UI 旗標。 |
|
嘗試建立新的會話，而不是取得環境的共用會話。 如果未設定 MAPI_NEW_SESSION 旗標，函式會使用現有的共用會話。
如果您設定 MAPI_NEW_SESSION 旗標 (防止使用共用會話) ，而且設定檔需要密碼，您也必須設定 MAPI_LOGON_UI 旗標，否則函式將會失敗。 用戶端應用程式可以使用沒有密碼的預設設定檔，或使用不含密碼的明確設定檔來避免此失敗。 |
|
如果提供者不支援 Unicode，請勿將訊息轉換為 ANSI。
注意 此旗標僅適用于 MAPISendMailW 。
|
ulReserved
類型： ULONG
保留;必須是零。
傳回值
類型： ULONG
此函式會傳回下列其中一個值。
| 傳回碼/值 | 描述 |
|---|---|
|
收件者符合一個以上的收件者描述項結構，且未設定MAPI_DIALOG。 未傳送任何訊息。 |
|
找不到指定的附件。 未傳送任何訊息。 |
|
無法開啟指定的附件。 未傳送任何訊息。 |
|
指定的附件太大。 未傳送任何訊息。 |
|
收件者的類型不是MAPI_TO、MAPI_CC或MAPI_BCC。 未傳送任何訊息。 |
|
發生一或多個未指定的錯誤。 未傳送任何訊息。 |
|
記憶體不足，無法繼續。 未傳送任何訊息。 |
|
一或多個收件者無效或無法解析為任何位址。 |
|
沒有預設登入，而且使用者無法在顯示登入對話方塊時成功登入。 未傳送任何訊息。 |
|
訊息中的文字太大。 未傳送任何訊息。 |
|
檔案附件太多。 未傳送任何訊息。 |
|
收件者太多。 未傳送任何訊息。 |
|
指定MAPI_FORCE_UNICODE旗標，不支援 Unicode。
注意 這個值只能由 MAPISendMailW 傳回。
|
|
收件者未出現在通訊清單中。 未傳送任何訊息。 |
|
使用者取消了其中一個對話方塊。 未傳送任何訊息。 |
|
呼叫成功且已傳送訊息。 |
備註
MAPISendMailW (Unicode) 和MAPISendMail (ANSI) 函式都會傳送標準訊息，無論是否有任何使用者互動。 必須設定設定檔，讓任一函式可以開啟預設服務提供者，而不需要使用者互動。
MAPISendMailW和MAPISendMail都不需要來源類型收件者才能傳送郵件。
用戶端應用程式可以提供收件者名稱、主旨文字、檔案附件或郵件文字的完整或部分清單。 如果遺漏任何資訊，您呼叫的函式 (MAPISendMailW 或 MAPISendMail) 可以提示使用者輸入遺漏的資訊。
如果沒有遺漏任何資訊，則可以依原樣傳送訊息，或提示使用者確認資訊，並視需要變更值。
MAPISendMailW和MAPISendMail都與MAPISendDocuments函式不同，因為它們在訊息產生方面具有更大的彈性。
郵件內文
某些用戶端應用程式可以截斷太長或包含歸位字元、換行字元或表單摘要的主旨行。每個段落都應該以 CR (0x0d) 、LF (0x0a) 或 CRLF 配對 (0x0d0a) 終止。 MAPISendMailW和MAPISendMail會適當地換行行。
如果文字超過系統限制，函式會傳回 MAPI_E_TEXT_TOO_LARGE 值。
檔案附件
某些訊息系統中可以限制每個郵件的附件數目。 如果超過此限制，函式會失敗並傳回 MAPI_E_TOO_MANY_FILES 值。在函式傳回之前，檔案附件會複製到訊息;因此，稍後對檔案所做的變更不會影響訊息的內容。 檔案在複製時必須關閉。
請勿嘗試顯示郵件文字範圍以外的附件。
收件者
某些訊息系統可以限制每個郵件的收件者數目。 如果用戶端應用程式傳遞非Null 值，指出超過系統限制的收件者數目，則函式會失敗並傳回 MAPI_E_TOO_MANY_RECIPIENTS 值。如果您的用戶端應用程式將訊息傳送給一或多個自訂收件者，而且您想要避免解析這些收件者的名稱，您必須指定自訂收件者的位址。
若要在呼叫MAPISendMailW時指定收件者的位址，您必須將MapiRecipDescW結構的lpszAddress成員設定為自訂位址。 這個MapiRecipDescW結構包含在儲存在MapiMessageW結構的lpRecips成員中，由lpMessage參數傳遞至函式的收件者陣列中。
從函式成功傳回不一定表示收件者驗證。 郵件可能尚未傳送給所有收件者。 視傳輸提供者而定，收件者驗證可以是冗長的程式。
處理收件者資訊
MapiMessageW或MapiMessage結構的lpRecips成員可以包含專案識別碼、收件者的名稱、位址或名稱和位址組。 下表顯示函式如何處理每個案例。| 收件者資訊 | 動作 |
|---|---|
| 專案識別碼 | 沒有名稱解析;會忽略名稱和位址。 |
| 名稱 | 使用簡單 MAPI 解析規則解析的名稱。 |
| 位址 | 沒有名稱解析;address 用於郵件傳遞和顯示收件者名稱。 |
| 名稱和位址 | 沒有名稱解析;名稱僅用於顯示收件者名稱。 |
需求
| 最低支援的用戶端 | Windows 8 [僅限傳統型應用程式] |
| 最低支援的伺服器 | Windows Server 2012 [僅限傳統型應用程式] |
| 目標平台 | Windows |
| 標頭 | mapi.h |