mapIADDRESS 回呼函式 (mapi.h)

發行項
08/24/2023

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

MAPIAddress函式會建立或修改一組通訊清單專案。

語法

MAPIADDRESS Mapiaddress;

ULONG Mapiaddress(
  [in]  LHANDLE lhSession,
  [in]  ULONG_PTR ulUIParam,
  [in]  LPSTR lpszCaption,
  [in]  ULONG nEditFields,
  [in]  LPSTR lpszLabels,
  [in]  ULONG nRecips,
  [in]  lpMapiRecipDesc lpRecips,
  [in]  FLAGS flFlags,
        ULONG ulReserved,
  [out] LPULONG lpnNewRecips,
        lpMapiRecipDesc *lppNewRecips
)
{...}

參數

[in] lhSession

代表簡單 MAPI 會話或零的會話控制碼。如果 lhSession 參數的值為零，MAPI 會登入使用者，並建立只在呼叫期間存在的會話。此暫存會話可以是現有的共用會話或新的會話。如有必要，會顯示登入對話方塊。

[in] ulUIParam

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

[in] lpszCaption

通訊清單對話方塊、Null或空字串標題指標。當lpszCaption參數為Null或指向空字串時，MAPIAddress會使用預設標題「Address Book」。

[in] nEditFields

應該出現在通訊清單中的編輯控制項數目。值 0 到 4 有效。如果 nEditFields 參數的值是 4，基礎傳訊系統所支援的每個收件者類別都有編輯控制項。如果 nEditFields 的值為零，則只能流覽通訊清單。值 1、2 或 3 可控制存在的編輯控制項數目。不過，如果 lpRecips 參數所指向陣列中的收件者類別數目大於 nEditFields的值， 則 lpRecips 中的類別數目是用來指出編輯控制項的數目，而不是 nEditFields的值。如果 nEditFields 的值為 1，且 lpRecips中存在一種以上的專案，則會忽略 lpszLabels 參數。針對不同控制項選取的專案會以傳回收件者結構中的 ulRecipClass 成員來區分。

[in] lpszLabels

要當做通訊清單對話方塊中編輯控制項標籤之字串的指標。當 nEditFields 參數設定為 1 以外的任何值時， 會忽略 lpszLabels 參數，而且應該是 Null 或指向空字串。此外，如果呼叫端需要預設控制項標籤「To」， lpszLabels 應該是 Null 或指向空字串。

[in] nRecips

陣列中 由 lpRecips 參數指示的專案數。如果 nRecips 參數的值為零，則會忽略 lpRecips 。

[in] lpRecips

MapiRecipDesc結構的陣列指標，定義要用來填入通訊清單對話方塊的初始收件者專案。專案不需要依收件者類別分組;它們會以陣列中MapiRecipDesc結構的ulRecipClass成員值來區分。如果不同的收件者類別數目大於 nEditFields 參數所指示的值，則會忽略 nEditFields 和 lpszLabels 參數。

[in] flFlags

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

值	意義
MAPI_LOGON_UI	應該顯示對話方塊，以提示使用者視需要登入。未設定MAPI_LOGON_UI旗標時，用戶端應用程式不會顯示登入對話方塊，而且如果使用者未登入，則會傳回錯誤值。
MAPI_NEW_SESSION	應該嘗試建立新的會話，而不是取得環境的共用會話。如果未設定MAPI_NEW_SESSION旗標， MAPIAddress 會使用現有的共用會話。

ulReserved

保留;必須是零。

[out] lpnNewRecips

lppNewRecips收件者輸出陣列中專案數的指標。如果 lpnNewRecips 參數的值為零， 則會忽略 lppNewRecips 參數。

lppNewRecips

傳回值

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

傳回碼	描述
MAPI_E_FAILURE	解決訊息時發生一或多個未指定的錯誤。未傳回收件者專案的清單。
MAPI_E_INSUFFICIENT_MEMORY	記憶體不足，無法繼續。未傳回收件者專案的清單。
MAPI_E_INVALID_EDITFIELDS	nEditFields參數的值超出 0 到 4 的範圍。未傳回收件者專案的清單。
MAPI_E_INVALID_RECIPS	通訊清單中的一或多個收件者無效。未傳回收件者專案的清單。
MAPI_E_INVALID_SESSION	不正確會話控制碼用於 lhSession 參數。未傳回收件者專案的清單。
MAPI_E_LOGIN_FAILURE	沒有預設登入，而且使用者無法在顯示登入對話方塊時成功登入。未傳回收件者專案的清單。
MAPI_E_NOT_SUPPORTED	基礎傳訊系統不支援此作業。
MAPI_E_USER_ABORT	使用者已取消其中一個對話方塊。未傳回收件者專案的清單。
SUCCESS_SUCCESS	呼叫成功，並傳回收件者專案清單。

備註

MAPIAddress函式會顯示標準通訊清單對話方塊，以顯示一組初始的零或多個收件者。使用者可以選擇要新增至集合的新專案，或對現有專案進行變更。無法隱藏此對話方塊，但呼叫端可以設定對話方塊特性。已變更的收件者集合會傳回給來電者。

在 MAPIAddress寫入新的或變更的收件者資訊之前，它必須為將包含資訊的結構陣列配置記憶體。不論寫入新的或變更的收件者資料，記憶體也會配置為預先載入通訊錄的一部分。用戶端應用程式必須呼叫 MAPIFreeBuffer 函式，才能在 MAPIAddress 傳回之後釋放此記憶體。如果發生任何錯誤，則不會配置任何記憶體，而且用戶端不需要呼叫 MAPIFreeBuffer。