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結構的指標，其中包含要傳送的訊息。

注意 針對 MAPISendMail 函式，此參數會指向 MapiMessage 結構。
 
當您呼叫 函式時，請注意下列訊息結構成員的相關資訊：
成員 備註
lpFiles 當郵件沒有檔案附件時，請將此成員設定為 Null 。
lpszMessageType 由未處理個人訊息的應用程式所使用。 如果您的應用程式處理個人訊息，請將 lpszMessageType 成員設定為 Null ，或將它設定為指向空字串。
lpszSubject Null值表示訊息的主旨沒有文字。
lpszNoteText Null值表示訊息本文中沒有文字。
lpRecips Null值表示沒有收件者。 此外，當此成員為 Null時， nRecipCount 成員必須是零。
nRecipCount 值為零表示沒有收件者。 此外，當這個成員為零時， lpRecips 成員必須是 Null。
 
提示 當您呼叫 函式且沒有任何收件者時，您必須設定 MAPI_DIALOG 旗標或 MAPI_DIALOG_MODELESS 旗標，以提示使用者提供收件者資訊。
 
如果未設定 MAPI_DIALOG 或 MAPI_DIALOG_MODELESS ，結構的 nRecipCount 和 lpRecips 成員必須有效，才能成功傳遞訊息。 用戶端應用程式可以將 flFlags 成員設定為 MAPI_RECEIPT_REQUESTED 以要求讀取報表。

For more details about how the function handles recipient information, see Handling Recipient Information in Remarks.

[in] flFlags

類型： FLAGS

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

值 意義
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 8 和下一版 Office 的 Windows SDK，而且您必須呼叫 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

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

傳回碼/值 描述
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
27
 指定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成員可以包含專案識別碼、收件者的名稱、位址或名稱和位址組。 下表顯示函式如何處理每個案例。
收件者資訊 動作
專案識別碼 沒有名稱解析;會忽略名稱和位址。
名稱 使用簡單 MAPI 解析規則解析的名稱。
位址 沒有名稱解析;address 用於郵件傳遞和顯示收件者名稱。
名稱和位址 沒有名稱解析;名稱僅用於顯示收件者名稱。

需求

   
最低支援的用戶端 Windows 8 [僅限傳統型應用程式]
最低支援的伺服器 Windows Server 2012 [僅限傳統型應用程式]
目標平台 Windows
標頭 mapi.h

另請參閱

MAPISendMailHelper

Windows SDK for Windows 8