IMSProvider：：Logon
適用於：Outlook 2013 |Outlook 2016
將MAPI記錄到訊息存放區提供者的一個實例。
HRESULT Logon(
LPMAPISUP lpMAPISup,
ULONG_PTR ulUIParam,
LPSTR lpszProfileName,
ULONG cbEntryID,
LPENTRYID lpEntryID,
ULONG ulFlags,
LPCIID lpInterface,
ULONG FAR * lpcbSpoolSecurity,
LPBYTE FAR * lppbSpoolSecurity,
LPMAPIERROR FAR * lppMAPIError,
LPMSLOGON FAR * lppMSLogon,
LPMDB FAR * lppMDB
);
參數
lpMAPISup
[in]訊息存放區目前MAPI支援物件的指標。
ulUIParam
[in]這個方法所顯示之任何對話框或視窗之父視窗的句柄。
lpszProfileName
[in]字串的指標，其中包含用於市集提供者登入的配置檔名稱。 此字串可以顯示在對話框中、寫出至記錄檔，或只是略過。 如果在 ulFlags 參數中設定MAPI_UNICODE旗標，則必須是 Unicode 格式。
cbEntryID
[in] lpEntryID 參數所指向之專案標識碼的大小，以位元組為單位。
lpEntryID
[in]訊息存放區之項目標識碼的指標。 在 lpEntryID 中傳遞 Null 表示尚未選取訊息存放區，而且可以顯示可讓使用者選取訊息存放區的對話方塊。
ulFlags
[in]控制登入執行方式的旗標位掩碼。 您可以設定下列旗標：
MAPI_DEFERRED_ERRORS
即使呼叫實作無法使用基礎物件，呼叫仍可成功。 如果對象無法使用，後續對物件的呼叫可能會引發錯誤。
MAPI_UNICODE
傳入的字串是 Unicode 格式。 如果未設定MAPI_UNICODE，則字串會是 ANSI 格式。
MDB_NO_DIALOG
防止顯示登入對話框。 如果設定此旗標，則會在登入失敗時傳回錯誤值MAPI_E_LOGON_FAILED。 如果未設定此旗標，訊息存放區提供者可以提示使用者更正名稱或密碼、插入磁碟，或執行建立與存放區連線所需的其他動作。
MDB_NO_MAIL
郵件存放區不應該用於傳送或接收郵件。 旗標會發出MAPI訊號，通知MAPI多任務緩衝處理程式正在開啟此訊息存放區。 如果設定此旗標，且訊息存放區與傳輸提供者緊密結合，則提供者不需要呼叫 IMAPISupport：：SpoolerNotify 方法。
MDB_TEMPORARY
在存放區上記錄，以便以程序設計方式從配置檔區段擷取資訊，而不需要使用對話方塊。 此旗標會指示MAPI不要將存放區新增至訊息存放區數據表，而且存放區不能永久。 如果設定此旗標，訊息存放區提供者就不需要呼叫 IMAPISupport：：ModifyProfile 方法。
MDB_WRITE
要求讀取/寫入許可權。
lpInterface
[in]要登入之訊息存放區 (IID) 介面識別碼的指標。 傳遞 null 表示傳回 IMsgStore) ( 訊息存放區的 MAPI 介面。 lpInterface 參數也可以設定為訊息存放區 (的適當介面標識符，例如，IID_IUnknown或IID_IMAPIProp) 。
lpcbSpoolSecurity
[out]變數的指標，其中存放區提供者會傳回 lppbSpoolSecurity 參數中驗證數據的大小，以位元組為單位。
lppbSpoolSecurity
[out]傳回之驗證數據指標的指標。 提供此驗證數據，以便 IMSProvider：：SpoolerLogon 方法可以將 MAPI 多任務緩衝處理器記錄到與訊息存放區提供者相同的存放區。
lppMAPIError
[out]傳回 MAPIERROR 結構指標的指標，如果有的話，包含錯誤的版本、元件和內容資訊。 如果沒有 MAPIERROR 結構可傳回，lppMAPIError 參數可以設定為 null。
lppMSLogon
[out]要登入之MAPI之訊息存放區登入物件指標的指標。
lppMDB
[out]要登入之 MAPI 多任務緩衝處理器和用戶端應用程式之訊息存放區物件指標的指標。
傳回值
S_OK
呼叫成功，並傳回預期的值。
MAPI_E_FAILONEPROVIDER
此提供者無法登入，但此錯誤不應停用服務。
MAPI_E_LOGON_FAILED
無法建立登入工作階段。
MAPI_E_UNCONFIGURED
配置檔未包含足夠的資訊讓登入完成。 傳回此值時，MAPI 會呼叫訊息存放區提供者的訊息服務進入點函式。
MAPI_E_USER_CANCEL
使用者已取消作業，通常是按兩下對話框中的 [ 取消 ] 按鈕。
MAPI_E_UNKNOWN_CPID
伺服器未設定為支援客戶端的代碼頁。
MAPI_E_UNKNOWN_LCID
伺服器未設定為支援客戶端的地區設定資訊。
MAPI_W_ERRORS_RETURNED
呼叫成功，但訊息存放區提供者有可用的錯誤資訊。 傳回此警告時，應將呼叫視為成功處理。 若要測試此警告，請使用 HR_FAILED 宏。 如需詳細資訊，請 參閱使用宏進行錯誤處理。 若要從提供者取得錯誤資訊，請呼叫 IMAPISession：：GetLastError 方法。
註解
MAPI 會呼叫 IMSProvider：：Logon 方法來執行取得訊息存放區存取權所需的大部分處理。 訊息存放區提供者會驗證存取特定存放區所需的任何用戶認證，並在MAPI後台處理程式和用戶端應用程式可以登入的 lppMDB 參數中傳回訊息存放區物件。
除了傳回的用戶端和 MAPI 多任務緩衝處理程式使用的訊息存放區物件之外，提供者也會傳回訊息存放區登入物件，讓 MAPI 用來控制開啟的存放區。 訊息存放區登入物件和訊息存放區對象應該緊密連結在訊息存放區提供者內，讓每個物件都會影響另一個。 存放區物件和登入物件的使用應該相同;登入物件和存放區對象之間應該要有一對一的對應，讓物件如同公開兩個介面的一個對象一樣運作。 這兩個物件也應該一起建立並一起釋放。
MAPI 支援物件是由 MAPI 所建立，並在 lpMAPISup 參數中傳遞給提供者，可讓您存取提供者所需的 MAPI 中的函式。 其中包括儲存和擷取配置檔資訊、存取通訊簿等等的函式。 針對每個開啟的存放區， lpMAPISup 指標可能不同。 在登入之後處理訊息存放區的呼叫時，存放區提供者應該使用該存放區專屬的 lpMAPISup 變數。 對於開啟訊息存放區並成功建立訊息存放區登入物件的任何 Logon 呼叫，提供者必須將指標儲存至市集登入物件中的 MAPI 支援物件，而且必須呼叫 IUnknown：：AddRef 方法來新增支援對象的參考。
如果提供者在登入呼叫期間顯示對話框，則應該使用ulUIParam參數。 不過，如果 ulFlags 包含MDB_NO_DIALOG旗標，則不應該顯示對話框。 如果需要呼叫使用者介面，但 ulFlags 不允許，或因其他原因無法顯示使用者介面，則提供者應該傳回MAPI_E_LOGON_FAILED。 如果 [登入] 顯示對話方塊，而使用者取消登入，通常按兩下對話方塊的 [ 取消 ] 按鈕，則提供者應該會傳回MAPI_E_USER_CANCEL。
lpEntryID 參數可以是 Null，或指向此訊息存放區先前建立的未包裝存放區專案標識符。 如果 lpEntryID 指向未包裝的專案識別碼，則該專案識別碼可以來自數個位置的其中一個：
它可以是存放區提供者先前包裝並寫入至配置檔區段的專案標識碼，作為 PR_ENTRYID (PidTagEntryId) 屬性。
它可以是提供者先前包裝並傳回給呼叫端的專案標識符，做為 PR_STORE_ENTRYID (PidTagStoreEntryId) 屬性。
它可以是提供者先前包裝並傳回給呼叫用戶端的專案標識碼，做為訊息存放區物件 的PR_ENTRYID 屬性。
在上述任何情況下，專案標識碼可能會建立在不同於目前使用之計算機的計算機上。
當 lpEntryID 不是 Null 時，它應該包含識別和尋找訊息存放區所需的所有資訊。 這項資訊可以包括網路磁碟區名稱、電話號碼、用戶帳戶名稱等等。 如果無法使用專案標識碼中的數據建立與存放區的連接，存放區提供者應該會顯示對話框，讓用戶選取要開啟的存放區。 可能需要對話框，例如，如果伺服器已重新命名、帳戶名稱已變更，或部分網路無法使用。
當 lpEntryID 為 Null 時，尚未選取要使用的訊息存放區。 如果提供者支持進一步的方法來指定存放區，它仍然可以存取存放區，而不需要顯示對話方塊。 例如，提供者可以檢查其初始化檔案，也可以在組態中尋找放在其 或其訊息服務配置檔區段的其他屬性。
如果提供者發現所有必要的資訊都不在配置檔中，它應該會傳回MAPI_E_UNCONFIGURED。 MAPI 接著會呼叫提供者的訊息服務進入點函式，讓用戶能夠選取存放區，或甚至建立一個存放區，並視需要輸入帳戶名稱和密碼。 MAPI 會自動為新存放區建立新的配置檔區段;這個新的配置檔區段可以是暫時或永久的，視新增方式而定。 如果存放區提供者呼叫 IMAPISupport：：ModifyProfile 方法，新的配置檔區段會變成永久的，而且存放區會新增至 IMAPISession：：GetMsgStoresTable 方法傳回的訊息存放區清單。
lpInterface 參數會指定新開啟之存放區物件所需的介面 IID。 在 lpInterface 中傳遞 null 會指定需要 MAPI 訊息存放區介面 IMsgStore。 傳遞訊息存放區物件IID_IMsgStore也會指定需要 IMsgStore 。 如果在 lpInterface 中傳遞IID_IUnknown，提供者應該使用任何衍生自 IUnknown 的介面來開啟存放區，這同樣最適合提供者 (，這通常是 IMsgStore) 。 傳遞IID_IUnknown時，呼叫的實作會使用 IUnknown：：QueryInterface 方法，在存放區開啟作業成功之後選取介面。
IMSProvider：：Logon 呼叫應該會傳回足夠的資訊，例如存放區的路徑和存取存放區的認證，讓 MAPI 多任務緩衝處理程式可以登入存放區提供者未呈現對話框的相同存放區。 lpcbSpoolSecurity 和 lppbSpoolSecurity 參數可用來傳回此資訊。 提供者會將指標傳遞至 MSProviderInit 函式 的 lpfAllocateBuffer 參數中的緩衝區，以配置此數據的記憶體;提供者會將此緩衝區的大小放在 lpcbSpoolSecurity 中。
MAPI 會在適當時釋放此緩衝區。 如果可以單獨從配置檔區段中的資訊完成MAPI多任務緩衝處理程式登入存放區，則提供者可以在 lppbSpoolSecurity 中傳回 null，而在 lpcbSpoolSecurity 中傳回資訊大小為 0。 MAPI 多任務緩衝處理程式登入會在不同於市集登入的進程中進行;因為包含已傳遞資訊的緩衝區會在進程之間複製，所以它可能不在MAPI多任務緩衝處理程式進程與存放區提供者進程相同的位置記憶體中。 因此，提供者不應該將位址放入這個緩衝區。 如需MAPI多任務緩衝處理程式登入的詳細資訊，請參閱 IMSProvider：：SpoolerLogon 方法。
大部分的存放區提供者都會使用 lpMAPISup 參數中傳遞之支持物件的 IMAPISession：：OpenProfileSection 方法，以儲存和擷取使用者認證和選項。 OpenProfileSection 可讓存放區提供者將其他任意資訊儲存在配置檔區段中，並將它與特定資源產生關聯。 例如，存放區提供者可以儲存與資源相關聯的用戶帳戶名稱和密碼，以及存取該資源所需的任何路徑或其他資訊。
透過0x67FF 0x6600屬性標識符的屬性是提供者可用的安全屬性，可供提供者用來在配置檔區段中儲存私用數據。 如需在配置檔區段物件中使用屬性的詳細資訊，請參閱 IProfSect： IMAPIProp 方法。
除了透過0x67FF 0x6600標識碼的屬性中的任何私用數據之外，存放區提供者也應該在其配置檔區段中提供 PR_DISPLAY_NAME (PidTagDisplayName) 屬性的資訊。 它應該PR_DISPLAY_NAME提供者本身的顯示名稱 —例如，向使用者顯示的識別字元串 (“Microsoft個人資訊存放區”) ，讓他們可以區分此郵件存放區與可能有權存取的其他郵件存放區。 PR_DISPLAY_NAME 通常包含伺服器名稱、用戶帳戶名稱或路徑。
某些配置檔區段屬性會顯示在訊息存放區數據表中;其他專案則會在 MAPI 子系統的安裝、安裝和設定期間顯示。 提供者通常會針對新的配置檔區段提供這些可見屬性的資訊，其中尚不包含已儲存的認證或私人資訊，以及當它發現屬性資訊已變更時。 如需配置檔區段的詳細資訊，請參閱 IMAPISupport：：OpenProfileSection。
在成功登入用戶之後，以及在返回MAPI之前，存放區提供者應該為資源的狀態數據列建立屬性陣列，並呼叫 IMAPISupport：：ModifyStatusRow 方法。
開啟目前MAPI會話已開啟之訊息存放區的登入呼叫會略過先前所述的大部分處理。 這些呼叫不會建立狀態數據列、傳回訊息存放區登入物件、呼叫MAPI支援物件的 AddRef ，或傳回MAPI多任務緩衝處理程式登入的數據。 這些呼叫會傳回S_OK，並使用要求的介面傳回訊息存放區物件。
若要偵測這類呼叫，提供者應該在已針對這個提供者對象開啟之存放區的訊息存放區提供者對象中維護清單。 處理 登入 呼叫時，提供者應該掃描此開啟的存放區清單，並判斷要登入的存放區是否已開啟。 如果是，則不需要檢查用戶認證，而且應該盡可能避免顯示對話方塊。 如果必須顯示對話框，提供者應該檢查傳回的資訊，以查看是否已第二次開啟存放區。 此外，提供者應該在登入呼叫處理開始時使用 lpEntryID 來檢查是否有重複的開頭。
存取開啟存放區 之登入 呼叫的標準處理如下：
如果所要求的新介面與現有存放區的介面相同，則存放區提供者會呼叫現有存放區物件的 AddRef 。 否則，它會呼叫 QueryInterface 以取得新的介面。 如果存放區不支援新的介面，提供者應該傳回錯誤值MAPI_E_INTERFACE_NOT_SUPPORTED。
提供者會傳回 lppMDB 中現有存放區物件之必要介面的指標。
提供者會在 lppMSLogon 中傳回 null。
提供者不應該開啟呼叫中傳遞之支持物件的配置檔。 此外，它不應該註冊提供者唯一標識符、註冊狀態數據列，或傳回MAPI多任務緩衝處理程式登入數據。
提供者不應該呼叫支持物件的 AddRef ，因為它不需要物件的指標。
如果可能，提供者應該傳回登 入 呼叫的適當錯誤和警告字串，因為這樣做可大幅減輕使用者判斷為何無法運作的負擔。 若要傳回這些字串，提供者會設定 MAPIERROR 結構中的成員。 MAPI 會在提供者傳回 MAPIERROR 結構時，尋找、使用和釋放 MAPIERROR 結構。
此 MAPIERROR 結構的記憶體應該使用 MSProviderInit 呼叫上傳入 lpfAllocateBuffer 的緩衝區來配置。 如果在 LogonulFlags 中設定MAPI_UNICODE，傳回結構中包含的任何錯誤字串都應該是 Unicode 格式;否則，它們應該位於 ANSI 字元集中。
對於從 登入傳回的大部分錯誤值，MAPI 會停用失敗提供者所屬的訊息服務。 MAPI 不會在MAPI會話的存留期內呼叫屬於這些服務的任何提供者。 相反地，當 Logon 從其登入傳回MAPI_E_FAILONEPROVIDER錯誤值時，MAPI 不會停用提供者所屬的訊息服務。 如果登入遇到不保證在會話的存留期內停用整個服務的錯誤，則登入應該會傳回MAPI_E_FAILONEPROVIDER。 例如，當提供者不允許顯示使用者介面且無法使用必要的密碼時，可能會傳回此錯誤。
如果提供者從其登入傳回MAPI_E_UNCONFIGURED，MAPI 會呼叫提供者的訊息服務專案函式，然後重試登入。 MAPI 會傳遞MSG_SERVICE_CONFIGURE做為內容，讓服務有機會自行設定。 如果客戶端選擇允許登入上的使用者介面，服務可以呈現其組態屬性表，讓使用者可以輸入組態資訊。
另請參閱
IMAPISession：：GetMsgStoresTable