IMsgStore::Advise
適用於:Outlook 2013 |Outlook 2016
註冊以接收影響訊息存放區的指定事件通知。
HRESULT Advise(
ULONG cbEntryID,
LPENTRYID lpEntryID,
ULONG ulEventMask,
LPMAPIADVISESINK lpAdviseSink,
ULONG_PTR lpulConnection
);
參數
cbEntryID
[in] lpEntryID 參數所指向之專案標識碼中的位元組計數。
lpEntryID
[in]資料夾項目標識碼的指標,或應該產生通知的相關訊息指標,或 Null。 如果 lpEntryID 設定為 NULL, 建議 註冊整個訊息存放區的通知。
ulEventMask
[in]值的遮罩,指出呼叫端感興趣且應該包含在註冊中的通知事件類型。 有一個對應 的 NOTIFICATION 結構,與保存事件相關信息的每種事件類型相關聯。 以下是 ulEventMask 參數的有效值:
fnevCriticalError
註冊嚴重錯誤的相關通知,例如記憶體不足。
fnevExtended
註冊特定訊息存放區提供者特定事件的相關通知。
fnevNewMail
註冊新訊息抵達的相關通知。
fnevObjectCreated
註冊有關建立新資料夾或訊息的通知。
fnevObjectCopied
註冊資料夾或正在複製之訊息的相關通知。
fnevObjectDeleted
註冊資料夾或正在刪除之訊息的相關通知。
fnevObjectModified
註冊資料夾或正在修改之訊息的相關通知。
fnevObjectMoved
註冊資料夾或正在移動之訊息的相關通知。
fnevSearchComplete
註冊搜尋作業完成的相關通知。
lpAdviseSink
[in]建議接收物件的指標,以接收後續通知。 此建議必須已配置接收物件。
lpulConnection
[out]非零數位的指標,表示呼叫端的建議接收物件與會話之間的連接。
lpAdviseSink
[in]建議接收物件的指標,以接收後續通知。 此建議必須已配置接收物件。
lpulConnection
[out]非零連接編號的指標,表示呼叫端的建議接收對象與訊息存放區之間的連線。
傳回值
S_OK
註冊成功。
MAPI_E_NO_SUPPORT
訊息存放區提供者不支援透過訊息存放區註冊通知。
註解
IMsgStore::Advise 方法會在呼叫端的建議接收對象與訊息存放區或訊息存放區中的對象之間建立連線。 當 ulEventMask 參數中指定的一或多個事件發生在建議來源物件時,此聯機會用來將通知傳送至建議接收器。 當 lpEntryID 參數指向有效的專案識別碼時,建議來源就是此專案標識碼所識別的物件。 當 lpEntryID 為 NULL 時,建議來源是訊息存放區。
若要傳送通知,訊息存放區提供者或MAPI會呼叫已註冊的建議接收的 IMAPIAdviseSink::OnNotify 方法。 OnNotify 的其中一個參數,即通知結構,包含描述特定事件的資訊。
實作者注意事項
您不需MAPI的協助,都可以支援通知。 MAPI 有三種支持物件方法可協助服務提供者實作通知: IMAPISupport::Subscribe、 IMAPISupport::Unsubscribe 和 IMAPISupport::Notify。 如果您選擇使用MAPI支援方法,請在呼叫您的Advise方法時呼叫 Subscribe,並釋放 lpAdviseSink 指標。
如果您選擇自行支援通知,請呼叫 lpAdviseSink 參數所代表之建議接收的 IUnknown::AddRef 方法,以保留此指標的複本。 請維護此複本,直到呼叫您的 IMsgStore::Unadvise 方法以取消註冊為止。
不論您支援通知的方式為何,請將非零的連接號碼指派給通知註冊,然後在 lpulConnection 參數中傳回它。 在呼叫 Unadvise 並完成之前,請勿釋放此連接編號。
呼叫者注意事項
在支援多個執行線程的系統上, 對 OnNotify 的呼叫也可隨時在任何線程上進行。 如果您必須確定通知只會在特定線程的特定時間發生,請呼叫 HrThisThreadAdviseSink 函式,以產生您傳遞給 Advise 的建議接收物件。
在呼叫 [ 建議 ] 成功之後,以及在呼叫 Unadvise 取消註冊之前,請準備好讓建議接收物件釋出。 除非您有特定的長期用途,否則您應該在 [建議 ] 傳回之後釋放建議接收物件。
如需通知程式的詳細資訊,請參閱 MAPI 中的事件通知。
如需處理通知的詳細資訊,請參閱 處理通知。
MFCMAPI 參考
如需 MFCMAPI 範例程式代碼,請參閱下表。
檔案 | Function | Comment |
---|---|---|
BaseDialog.cpp |
CBaseDialog::OnNotificationsOn |
MFCMAPI 會使用 IMsgStore::Advise 方法來註冊整個訊息存放區的通知。 |