mapIREADMAIL 回呼函式 (mapi.h)

發行項
08/24/2023

[不建議使用此函式。在後續版本的 Windows 中，可能會變更或無法使用。

MAPIReadMail函式會擷取要讀取的訊息。

語法

MAPIREADMAIL Mapireadmail;

ULONG Mapireadmail(
  [in]  LHANDLE lhSession,
  [in]  ULONG_PTR ulUIParam,
  [in]  LPSTR lpszMessageID,
  [in]  FLAGS flFlags,
        ULONG ulReserved,
        lpMapiMessage *lppMessage
)
{...}

參數

[in] lhSession

簡單 MAPI 會話的控制碼。 lhSession參數的值必須代表有效的會話;不能為零。

[in] ulUIParam

父視窗控制碼或零，表示如果顯示對話方塊，則為應用程式強制回應。如果 ulUIParam 參數包含父視窗控制碼，則其類型為 HWND (轉換成ULONG_PTR) 。如果在呼叫期間未顯示任何對話方塊， 則會忽略 ulUIParam 。

[in] lpszMessageID

要讀取之訊息的訊息識別碼字串指標。字串是由呼叫端所配置。

[in] flFlags

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

值	意義
MAPI_BODY_AS_FILE	MAPIReadMail 應該將郵件文字寫入暫存檔案，並將它新增為附件清單中的第一個附件。
MAPI_ENVELOPE_ONLY	MAPIReadMail 應該唯讀取郵件標頭。檔案附件不會複製到暫存檔案，也不會寫入暫存檔案名稱或郵件內文。設定此旗標可增強效能。
MAPI_PEEK	MAPIReadMail 不會將訊息標示為已讀取。將訊息標示為讀取會影響其在使用者介面中的外觀，並產生讀取回條。如果訊息系統不支援此旗標， MAPIReadMail 一律會將訊息標示為已讀取。如果 MAPIReadMail 發生錯誤，則會讓訊息保持未讀取。
MAPI_SUPPRESS_ATTACH	MAPIReadMail 不應該複製檔案附件，但應該將郵件內文寫入 MapiMessage 結構。如果呼叫的應用程式已設定MAPI_ENVELOPE_ONLY旗標，MAPIReadMail會忽略此旗標。設定MAPI_SUPPRESS_ATTACH旗標可增強效能。

ulReserved

保留;必須是零。

lppMessage

傳回值

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

傳回碼	描述
MAPI_E_ATTACHMENT_WRITE_FAILURE	無法將附件寫入暫存檔案。檢查目錄許可權。
MAPI_E_DISK_FULL	因為磁片上沒有足夠的空間，所以無法將附件寫入暫存檔。
MAPI_E_FAILURE	讀取訊息時發生一或多個未指定的錯誤。
MAPI_E_INSUFFICIENT_MEMORY	記憶體不足，無法讀取訊息。
MAPI_E_INVALID_MESSAGE	lpszMessageID參數中傳遞了不正確訊息識別碼。
MAPI_E_INVALID_SESSION	在 lhSession 參數中傳遞不正確會話控制碼。未擷取任何訊息。
MAPI_E_TOO_MANY_FILES	郵件中有太多檔案附件。無法讀取訊息。
MAPI_E_TOO_MANY_RECIPIENTS	郵件收件者太多。無法讀取訊息。
SUCCESS_SUCCESS	呼叫成功且已讀取訊息。

備註

MAPIReadMail函式會傳回一則訊息，將訊息內容分成MAPISendMail函式中使用的相同參數和結構。 MAPIReadMail 會以包含訊息元素的 MapiMessage 結構填滿記憶體區塊，例如主旨、郵件類別、傳遞時間和寄件者。檔案附件會儲存至暫存檔案，並將名稱傳回至訊息結構中的呼叫端。 MAPIReadMail回到呼叫端之前，會先從郵件複製收件者、附件和內容，因此稍後對檔案所做的變更不會影響郵件的內容。

系統會提供旗標，以指定只傳回來自呼叫的信封資訊。 MapiMessage結構 (另一個旗標) 指定訊息是否標示為已傳送或未傳送。

呼叫端負責釋放 MapiMessage 結構，方法是呼叫 MAPIFreeBuffer 函式，並刪除與訊息隨附附件相關聯的任何檔案。

在呼叫 MAPIReadMail之前，請使用 MAPIFindNext 函式來確認要讀取的訊息是否為您想要讀取的訊息。由於訊息識別碼是系統專屬且不透明，而且可以隨時失效， 因此 MAPIReadMail 會將訊息識別碼視為僅適用于目前的簡單 MAPI 會話。