支援事件通知
適用於：Outlook 2013 |Outlook 2016
由於支援事件通知可能很複雜，因此MAPI提供三種支持物件方法，可實作程式中最困難的部分。 這些方法可做為一個單位運作，而提供者必須全部使用這三種方法或全部都不使用。
MAPI 支援方法會使用通知密鑰來管理建議接收與產生通知之對象之間的連線。 通知密鑰是 NOTIFKEY 結構，其中包含可跨進程識別物件的二進位數據。 通知金鑰通常會從建議來源物件的長期項目標識碼複製。 如果用戶端已在 [ 建議] 呼叫中提供專案識別碼，您可以將它用於通知密鑰。 如果 [建議] 的 lpEntryID 參數是 NULL，請使用最外層可能容器物件的專案標識碼，例如訊息存放區。
若要使用支援方法，每當用戶端呼叫您的 Advise 方法來註冊通知時，請呼叫 IMAPISupport：：Subscribe。 配置 NOTIFKEY 結構，併為您的建議來源物件建立唯一的通知密鑰。 例如，當訊息接收到特定資料夾時，系統提示通知用戶端的訊息存放區提供者會建立該資料夾的通知金鑰。 在訂閱呼叫中傳遞 NOTIFKEY 結構的指標 ，以及客戶 端建議接收的指標。 Subscribe 會呼叫建議接收的 IUnknown：：AddRef 方法來遞增其參考計數，而 MAPI 會保留指標，直到取消註冊為止。
您可以將NOTIFY_SYNC旗標傳遞給 Subscribe ，以要求 Notify 以同步方式運作，而且在它對已註冊之建議接收器的 IMAPIAdviseSink：：OnNotify 方法進行所有呼叫之前，不會傳回。 僅針對您自己的內部用途設定此旗標。 當您回應客戶端 建議 呼叫時，請勿加以設定。 用戶端與提供者之間的事件通知一律是異步的。 也就是說，MAPI 保證發生事件的呼叫會在進行任何 OnNotify 呼叫之前傳回用戶端。
如果您設定NOTIFY_SYNC旗標，請勿對任何建議接收對象進行任何變更，而且不要將 HrThisThreadAdviseSink 所建立的包裝函式建議接收傳遞給 訂閱。 HrThisThreadAdviseSink 會建立建議接收的線程安全版本，僅供異步通知使用。
如果註冊同步通知的建議接收會在設定CALLBACK_DISCONTINUE旗標的情況下從 OnNotify 傳回， IMAPISupport：：Notify 會設定NOTIFY_CANCELED旗標並傳回，而不會對 OnNotify 進行任何呼叫。
一旦訂閱傳回，您就不再需要保留客戶端建議接收器的復本。 呼叫其 IUnknown：：Release 方法來釋放它。 Subscribe 會傳回您應該傳回給用戶端的非零連接編號。 連接編號代表建議來源與建議接收之間的連結。 在用戶端成功呼叫 Unadvise 之前，它會保持有效。
當用戶端準備好取消註冊時，它會呼叫您的 Unadvise 方法。 將 Unadvise 呼叫的連接號碼傳遞至 IMAPISupport：：Unsubscribe。 取消訂閱會 呼叫建議接收的 IUnknown：：Release 方法。 如同 Advise 和 Unadvise，訂閱和取消訂閱的呼叫必須配對。 您必須針對訂閱的每個呼叫，對取消訂閱進行一次呼叫。 不過，您不需要在每次呼叫 Advise 方法時呼叫 Subscribe。 相反地，您可以呼叫它來設定內部通知。
當事件發生時，請配置一或多個適用於事件之類型的 NOTIFICATION 結構，然後呼叫 IMAPISupport：：Notify。 [通知 ] 會針對每個已註冊的建議接收產生通知。 您應該將 NOTIFICATION 結構中所有未使用的成員設定為零。 這項初始化 NOTIFICATION 結構的技術可協助用戶端建立較小、更快且較不容易出錯的 OnNotify 實作。
請注意，每個事件都需要個別 的 NOTIFICATION 結構，即使是相同類型的多個事件也一樣。 例如，如果在特定數據表上註冊了三個用戶端的數據表通知，而且數據表中新增了五個數據列，您就必須為您的 Notify 呼叫建立五個OBJECT_NOTIFICATION結構。 這類批次通知會產生比呼叫 Notify 五次更好的效能。 針對每個 Notify 呼叫，MAPI 會呼叫每個已註冊建議接收器的 IMAPIAdviseSink：：OnNotify 方法。 如果沒有已註冊的建議接收，MAPI 會忽略呼叫。
傳送批次通知的服務提供者必須加以排序，才能從第一個通知解譯到最後一個通知。 當通知批次包含一系列事件時，特別需要此排序，例如TABLE_ROW_ADDED一個事件參考在相同批次中另一個事件中新增的先前數據列。