MAPIFINDNEXT 回呼函式 (mapi.h)

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

MAPIFindNext 函式會擷取下一個 (或第一個) 輸入訊息類型的訊息標識碼。

語法

MAPIFINDNEXT Mapifindnext;

ULONG Mapifindnext(
  [in]  LHANDLE lhSession,
  [in]  ULONG_PTR ulUIParam,
  [in]  LPSTR lpszMessageType,
  [in]  LPSTR lpszSeedMessageID,
  [in]  FLAGS flFlags,
        ULONG ulReserved,
  [out] LPSTR lpszMessageID
)
{...}

參數

[in] lhSession

代表簡單MAPI會話的會話句柄。 lhSession 參數的值必須代表有效的會話;它不能是零。

[in] ulUIParam

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

[in] lpszMessageType

識別要搜尋之訊息類別的字串指標。 若要尋找 IPM) (個人訊息，請在 lpszMessageType 參數中指定 NULL，或讓它指向空字串。 只有支援的訊息類別是 IPM 的傳訊系統可以忽略此參數。

[in] lpszSeedMessageID

字串的指標，其中包含要求的訊息標識碼種子。 如果 lpszSeedMessageID 參數為 NULL 或指向空字串， MAPIFindNext 會擷取符合 lpszMessageType 參數中指定的類型的第一則訊息。

[in] flFlags

選項旗標的位掩碼。 您可以設定下列旗標。

值 意義
MAPI_GUARANTEE_FIFO
傳回的訊息標識碼應該以接收的時間順序排列。 如果設定此旗標，MAPIFindNext 呼叫可能需要較長的時間。 某些實作無法接受此要求，並傳回MAPI_E_NO_SUPPORT值。
MAPI_LONG_MSGID
傳回的訊息標識碼可以長度為512個字元。 如果設定此旗標， lpszMessageID 參數必須夠大，才能容納 512 個字元。

舊版MAPI支援較小的訊息標識碼， (64個字節) ，但不包含此旗標。 只要 lpszMessageID 夠大，才能保留訊息標識碼，MAPIFindNext 就會成功，而未設定此旗標。 如果 lpszMessageID 無法保存訊息識別碼， MAPIFindNext 將會失敗。
MAPI_UNREAD_ONLY
應該只列舉指定型別的未讀取訊息。 如果未設定此旗標， MAPIFindNext 可以傳回指定類型的任何訊息。

ulReserved

保留;必須是零。

[out] lpszMessageID

傳回之訊息標識碼的指標。 呼叫端負責配置記憶體。 若要確保相容性，請配置 512 個字元，並在 flFlags 參數中設定MAPI_LONG_MSGID。 只有在傳回的訊息標識碼一律為64個字元或更少時，較小的緩衝區才足夠。

傳回值

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

傳回碼 Description
MAPI_E_FAILURE
符合訊息類型時發生一或多個未指定的錯誤。 在訊息類型比對發生之前，呼叫失敗。
MAPI_E_INSUFFICIENT_MEMORY
記憶體不足，無法繼續。 找不到訊息。
MAPI_E_INVALID_MESSAGE
lpszSeedMessageID 參數中傳遞了無效的訊息標識碼。 找不到訊息。
MAPI_E_INVALID_SESSION
lhSession 參數中傳遞了無效的會話句柄。 找不到訊息。
MAPI_E_NO_MESSAGES
找不到相符的訊息。
SUCCESS_SUCCESS
呼叫成功，並傳回訊息標識碼。

備註

MAPIFindNext 函式可讓用戶端應用程式列舉指定類型的訊息。 您可以重複呼叫此函式，以列出資料夾中的所有訊息。 從 MAPIFindNext 傳回的訊息識別碼可用於其他簡單 MAPI 呼叫，以擷取訊息內容和刪除訊息。 此函式用於處理傳入訊息，而不是用於管理已接收的訊息。

MAPIFindNext 會在傳遞指定類型之新訊息的資料夾中尋找訊息。 MAPIFindNext 呼叫只能在使用 MAPILogon 函式建立的有效 Simple MAPI 會話內容中進行。

當 lpszSeedMessageID 參數為 NULL 或指向空字串時， MAPIFindNext 會傳回 lpszMessageType 參數所指定類型第一則訊息的訊息識別符。 當 lpszSeedMessageID 包含有效的標識符時，函式會傳回 lpszMessageType 所指定類型的下一個相符訊息。 對 MAPIFindNext 的重複呼叫最終會導致傳回MAPI_E_NO_MESSAGES值，這表示列舉已完成。

訊息類型比對會針對訊息類別字串完成。 傳回名稱符合 (長度的所有訊息類型，最多會傳回 lpszMessageType) 中指定的長度。

由於訊息標識碼是訊息系統特定的訊息，而且可以隨時失效，因此訊息標識碼僅適用於目前的會話。 如果傳入 lpszSeedMessageID 的訊息標識碼無效， MAPIFindNext 會傳回MAPI_E_INVALID_MESSAGE值。

規格需求

需求 值
目標平台 Windows
標頭 mapi.h

另請參閱

MAPILogon

簡單MAPI

  • Last updated on