共用方式為

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

父視窗 handle 或零。

如果 ulUIParam 參數包含父視窗的 handle ，則 handle 型別為 HWND（cast 到 ULONG_PTR）。

若通話期間未顯示對話框， 則忽略 ulUIParam 。

[in] lpMessage

類型： lpMapiMessageW

指標指向包含要傳送訊息的 MAPISendMailW 結構。

便條 對於 MAPISendMail 函式，此參數指向 一個 MapiMessage 結構。
 
當您致電該活動時，請注意以下關於訊息結構成員的資訊：
會員 註釋
lp檔案 當訊息沒有檔案附件時，將此成員設為 NULL 。
lpsz訊息類型 用於不處理人際訊息的應用程式。 如果你的應用程式處理人際訊息，請將 lpszMessageType 成員設為 NULL ，或指向空字串。
lpsz主體 NULL 值表示訊息主詞沒有文字。
lpsz備註文字 NULL 表示訊息正文中沒有文字。
lpRecips NULL 的值表示沒有接收者。 此外，當該成員為 NULL 時， nRecipCount 成員必須為零。
nRecipCount 值為零表示沒有接收者。 此外，當此成員為零時，lpRecips 成員必須為 NULL。
 
末 當你呼叫函式且沒有接收者時，必須設定 MAPI_DIALOG 標誌或 MAPI_DIALOG_MODELESS 標誌，以提示使用者輸入接收者資訊。
 
若 MAPI_DIALOG 或 MAPI_DIALOG_MODELESS 未設定，結構中的 nRecipCount 與 lpRecips 成員必須有效，才能成功傳遞訊息。 用戶端應用程式可以將 flFlags 成員設為 MAPI_RECEIPT_REQUESTED 以請求讀取報告。

欲了解更多關於此功能如何處理接收者資訊的細節，請參閱備註中的「處理接收者資訊」。

[in] flFlags

類型： FLAGS

選項標誌的位元遮罩。 可以設定以下旗標。

價值觀 Meaning
MAPI_DIALOG
0x00000008
 應顯示應用程式模式對話框，提示使用者接收者及其他發送選項。

若未設定 MAPI_DIALOG 或 MAPI_DIALOG_MODELESS ，則至少必須指定一位收件人。
MAPI_DIALOG_MODELESS
0x00000004 |MAPI_DIALOG
 在 Windows 上可於下一版 Office 使用：

應顯示無模式對話框，提示使用者提供收件人及其他發送選項。

如果設定MAPI_DIALOG_MODELESS，lhSession 參數應該設為零。 否則，如果此旗標被設定且 lhSession 未為零，Outlook 會觸發例外。

此外，若設定 MAPI_DIALOG_MODELESS ，系統會忽略 MAPI_NEW_SESSION 旗標。

若未設定 MAPI_DIALOG 或 MAPI_DIALOG_MODELESS ，則至少必須指定一位收件人。

末 要在 Windows 7 或更早版本使用此旗標，您必須同時安裝 Windows SDK for Windows 8 及下一版本 Office，且必須呼叫 MAPISendMailHelper 而非 MAPISendMailW。
 
MAPI_LOGON_UI
0x00000001
 應顯示一個對話框，提示使用者如有需要登入。

若未設定 MAPI_LOGON_UI 標誌，用戶端應用程式不會顯示登入對話框，若使用者未登入則回傳錯誤值。

若 lpszMessageID 參數為空，則忽略 MAPI_LOGON_UI 標誌。
MAPI_NEW_SESSION
0x00000002
 嘗試建立一個新的會話，而非取得環境的共享會話。 若未設定 MAPI_NEW_SESSION 標誌，函式將使用現有的共享會話。

如果你設定了 MAPI_NEW_SESSION 標誌（阻止共用工作階段的使用），而設定檔需要密碼，你也必須同時設定 MAPI_LOGON_UI 標誌，否則函式會失敗。 您的客戶端應用程式可以透過使用無密碼的預設設定檔或使用無密碼的明確設定檔來避免此故障。
MAPI_FORCE_UNICODE
0x00040000
 如果供應商不支援 Unicode，請勿將訊息轉換為 ANSI。
便條 此旗幟僅供 MAPISendMailW 使用。
 

ulReserved

類型： ULONG

保留的;必須是零。

返回值

類型： ULONG

此函式會傳回下列其中一個值。

傳回碼/值 Description
MAPI_E_AMBIGUOUS_RECIPIENT
21
 一位收件人與多個收件人描述符結構相符，且MAPI_DIALOG未被設定。 沒有發送任何訊息。
MAPI_E_ATTACHMENT_NOT_FOUND
11
 未找到指定的附件。 沒有發送任何訊息。
MAPI_E_ATTACHMENT_OPEN_FAILURE
12
 指定的附件無法打開。 沒有發送任何訊息。
MAPI_E_ATTACHMENT_TOO_LARGE
28
 指定的附件太大了。 沒有發送任何訊息。
MAPI_E_BAD_RECIPTYPE
15
 受獎者類型不是MAPI_TO、MAPI_CC或MAPI_BCC。 沒有發送任何訊息。
MAPI_E_FAILURE
2
 發生一或多個未指定的錯誤。 沒有發送任何訊息。
MAPI_E_INSUFFICIENT_MEMORY
5
 記憶體不足以繼續。 沒有發送任何訊息。
MAPI_E_INVALID_RECIPS
25
 一位或多位收件人無效或未結算至任何地址。
MAPI_E_LOGIN_FAILURE
3
 沒有預設登入，且當登入對話框顯示時，使用者未能成功登入。 沒有發送任何訊息。
MAPI_E_TEXT_TOO_LARGE
18
 訊息裡的文字太大了。 沒有發送任何訊息。
MAPI_E_TOO_MANY_FILES
9
 檔案附件太多了。 沒有發送任何訊息。
MAPI_E_TOO_MANY_RECIPIENTS
10
 收件人太多了。 沒有發送任何訊息。
MAPI_E_UNICODE_NOT_SUPPORTED
二十七
 MAPI_FORCE_UNICODE 旗標已被指定，且不支援 Unicode。
便條 此值僅可由 MAPISendMailW 回傳。
 
MAPI_E_UNKNOWN_RECIPIENT
14
 收件人未出現在地址清單中。 沒有發送任何訊息。
MAPI_E_USER_ABORT
1
 使用者取消了其中一個對話框。 沒有發送任何訊息。
SUCCESS_SUCCESS
0
 通話成功，訊息也被發送出去。

備註

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 參數傳遞給函式的接收者陣列中。

便條 在呼叫 MAPISendMail 時，若要指定收件人地址，請依照前述 MAPISendMailW 的指示，但可將 MapiRecipDesc 和 MapiMessage 結構替換。

 

函式成功返回不一定代表接收者獲得驗證。 訊息可能沒有寄給所有收件人。 依運輸業者不同，收件人驗證過程可能相當冗長。

處理收件人資訊

MapiMessageW 或 MapiMessage 結構中的 lpRecips 成員可以包含條目識別碼、收件人姓名、地址，或名稱與地址對。 下表展示了該函數如何處理每個情況。
收件人資訊 行動
條目識別碼 沒有命名決議;名字和地址都被忽略了。
名字 名稱依照 Simple MAPI 解析規則解決。
地址 沒有命名決議;地址同時用於訊息傳遞及收件人姓名顯示。
名稱與地址 沒有命名決議;名稱僅用於顯示收件人姓名。

需求

Requirement 價值觀
最低支援的用戶端 Windows 8 [僅限傳統型應用程式]
支援的最低伺服器 Windows Server 2012 [僅限傳統型應用程式]
目標平臺 窗戶
Header 馬皮·H

另請參閱

MAPISendMailHelper

Windows SDK for Windows 8

  • Last updated on