nl:: Weave:: Profiles:: DataManagement_Current:: LoggingManagement
#include <src/lib/profiles/data-management/Current/LoggingManagement.h>
用於管理記憶體事件記錄的類別。
摘要
建構函式和解構函式 |
|
---|---|
LoggingManagement(nl::Weave::WeaveExchangeManager *inMgr, size_t inNumBuffers, const LogStorageResources *const inLogStorageResources)
LoggingManagement 建構函式中。
|
|
LoggingManagement(void)
LoggingManagement 預設建構函式。
|
公用函式 |
|
---|---|
BlitEvent(EventLoadOutContext *aContext, const EventSchema & inSchema, EventWriterFunct inEventWriter, void *inAppData, const EventOptions *inOptions)
|
根據事件記錄通訊協定寫入事件標頭和資料的輔助函式。
|
CancelShutdownInProgress(void)
|
void
將 mShutdownInProgress 旗標設為 false。
|
CheckShouldRunWDM(void)
|
bool
依據未排定上傳的事件緩衝區中的位元組數,決定是否卸載事件。
|
FetchEventsSince(nl::Weave::TLV::TLVWriter & ioWriter, ImportanceType inImportance, event_id_t & ioEventID)
|
這個函式可用於擷取指定重要性事件 (從指定事件 ID 開始) 的函式。
|
GetBytesWritten(void) const
|
uint32_t
取得此記錄自執行個體化以來寫入的位元組總數 (涵蓋所有事件重要性)。
|
GetEventReader(nl::Weave::TLV::TLVReader & ioReader, ImportanceType inImportance)
|
一種輔助方法,可用於檢查記憶體內記錄緩衝區。
|
GetFirstEventID(ImportanceType inImportance)
|
擷取目前儲存特定重要性等級的第一個事件 ID。
|
GetLastEventID(ImportanceType inImportance)
|
擷取特定重要性等級的最新 ID。
|
IsShutdownInProgress(void)
|
bool
檢查 mShutdownInProgress 旗標。
|
IsValid(void)
|
bool
IsValid 會傳回 LoggingManagement 執行個體是否有效。
|
LoadEvents(TLVReader & reader)
|
載入先前保留的 Weave 事件。
|
LogEvent(const EventSchema & inSchema, EventWriterFunct inEventWriter, void *inAppData, const EventOptions *inOptions)
|
透過回呼記錄事件,並提供選項。
|
MarkShutdownInProgress(void)
|
void
將 mShutdownInProgress 標記設為 true。
|
NotifyEventsDelivered(ImportanceType inImportance, event_id_t inLastDeliveredEventID, uint64_t inRecipientNodeID)
|
void
|
RegisterEventCallbackForImportance(ImportanceType inImportance, FetchExternalEventsFunct inFetchCallback, NotifyExternalEventsDeliveredFunct inNotifyCallback, NotifyExternalEventsEvictedFunct inEvictedCallback, size_t inNumEvents, event_id_t *outLastEventID)
|
用於註冊一組外部儲存事件的公用 API。
|
RegisterEventCallbackForImportance(ImportanceType inImportance, FetchExternalEventsFunct inFetchCallback, NotifyExternalEventsDeliveredFunct inNotifyCallback, size_t inNumEvents, event_id_t *outLastEventID)
|
用於註冊一組外部儲存事件的公用 API。
|
RegisterEventCallbackForImportance(ImportanceType inImportance, FetchExternalEventsFunct inFetchCallback, size_t inNumEvents, event_id_t *outLastEventID)
|
用於註冊一組外部儲存事件的公用 API。
|
ScheduleFlushIfNeeded(bool inFlushRequested)
|
安排記錄檔卸載工作。
|
SerializeEvents(TLVWriter & writer)
|
將所有重要類型的 Weave 事件序列化。
|
SetBDXUploader(LogBDXUpload *inUploader)
|
void
|
SetExchangeManager(nl::Weave::WeaveExchangeManager *inMgr)
|
設定要與這個記錄子系統搭配使用的 WeaveExchangeManager。
|
SetLoggingEndpoint(event_id_t *inEventEndpoints, size_t inNumImportanceLevels, size_t & outLoggingPosition)
|
|
SkipEvent(EventLoadOutContext *aContext)
|
void
用於略過寫入與分配事件 ID 對應的事件的輔助函式。
|
ThrottleLogger(void)
|
void
ThrottleLogger 會將有效記錄層級提升至實際工作環境等級。
|
UnregisterEventCallbackForImportance(ImportanceType inImportance, event_id_t inEventID)
|
void
用於取消註冊一組外部儲存事件的公用 API。
|
UnthrottleLogger(void)
|
void
UnthrottleLogger 會將有效記錄層級還原至設定的記錄層級。
|
公開的靜態函式 |
|
---|---|
CreateLoggingManagement(nl::Weave::WeaveExchangeManager *inMgr, size_t inNumBuffers, const LogStorageResources *const inLogStorageResources)
|
void
建立 LoggingManagement 物件,並使用提供的資源初始化記錄管理子系統。
|
DestroyLoggingManagement(void)
|
void
執行關機所需的動作。
|
GetInstance(void)
|
公用函式
BlitEvent
WEAVE_ERROR BlitEvent( EventLoadOutContext *aContext, const EventSchema & inSchema, EventWriterFunct inEventWriter, void *inAppData, const EventOptions *inOptions )
根據事件記錄通訊協定寫入事件標頭和資料的輔助函式。
詳細說明 | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
參數 |
|
CancelShutdownInProgress
void CancelShutdownInProgress( void )
將 mShutdownInProgress 旗標設為 false。
CheckShouldRunWDM
bool CheckShouldRunWDM( void )
依據未排定上傳的事件緩衝區中的位元組數,決定是否卸載事件。
函式的行為會透過 WEAVE_CONFIG_EVENT_LOGGING_BYTE_THRESHOLD 常數控制。如果系統撰寫的位元組數超過上次傳送 WDM 通知的時間,函式就會指出觸發 NotificationEngine 的時間。
詳細說明 | |||||
---|---|---|---|---|---|
傳回值 |
|
FetchEventsSince
WEAVE_ERROR FetchEventsSince( nl::Weave::TLV::TLVWriter & ioWriter, ImportanceType inImportance, event_id_t & ioEventID )
這個函式可用於擷取指定重要性事件 (從指定事件 ID 開始) 的函式。
如果有 nl::Weave::TLV::TLVWriter、重要性類型和事件 ID,這個函式會從指定事件擷取指定重要性的事件。此函式將繼續擷取事件,直到 nl::Weave::TLV::TLVWriter 或記錄中的空間用盡為止。函式會在事件邊界終止事件寫入。
詳細說明 | |||||||
---|---|---|---|---|---|---|---|
參數 |
|
||||||
傳回值 |
|
GetBytesWritten
uint32_t GetBytesWritten( void ) const
取得此記錄自執行個體化以來寫入的位元組總數 (涵蓋所有事件重要性)。
詳細說明 | |
---|---|
傳回 |
寫入記錄的位元組數。
|
GetEventReader
WEAVE_ERROR GetEventReader( nl::Weave::TLV::TLVReader & ioReader, ImportanceType inImportance )
一種輔助方法,可用於檢查記憶體內記錄緩衝區。
詳細說明 | |||||
---|---|---|---|---|---|
參數 |
|
||||
傳回 |
WEAVE_NO_ERROR:無條件。
|
GetFirstEventID
event_id_t GetFirstEventID( ImportanceType inImportance )
擷取目前儲存特定重要性等級的第一個事件 ID。
詳細說明 | |||
---|---|---|---|
參數 |
|
||
傳回 |
event_id_t 優先儲存該事件重要性的事件 ID
|
GetLastEventID
event_id_t GetLastEventID( ImportanceType inImportance )
擷取特定重要性等級的最新 ID。
詳細說明 | |||
---|---|---|---|
參數 |
|
||
傳回 |
event_id_t 最近期該事件重要性的事件 ID
|
IsShutdownInProgress
bool IsShutdownInProgress( void )
檢查 mShutdownInProgress 旗標。
IsValid
bool IsValid( void )
LogEvent
event_id_t LogEvent( const EventSchema & inSchema, EventWriterFunct inEventWriter, void *inAppData, const EventOptions *inOptions )
透過回呼記錄事件,並提供選項。
這個函式會記錄以 EventWriterFunct 表示的事件,以及應用程式專屬的 appData
背景資訊。這個函式會寫入事件中繼資料,並呼叫 inEventWriter
參照 nl::Weave::TLV::TLVWriter 參照和 inAppData
結構定義,讓使用者程式碼直接將事件資料發至事件記錄檔。由於事件資料會直接序列化到目標緩衝區,因此這種形式的事件記錄功能可將記憶體用量降到最低。事件資料「必須」包含要解讀的結構定義標記 (由 inProfileID
和 inEventType
識別)。系統會忽略第一個元素的標記;事件記錄系統會用 eventData 代碼取代該標記。
如果結構定義重要性超過 LoggingConfiguration 中指定的記錄門檻,系統就會記錄事件。如果事件的重要性不符合目前的門檻,系統會捨棄該事件,且函式會傳回 0
做為產生的事件 ID。
這個叫用變數允許呼叫端設定任何 EventOptions
組合:
- 時間戳記,如果 0 預設為呼叫當下的目前時間,
- 事件來源 (事件來源和特徵 ID) 的「根」區段;如果為 NULL,則會預設為目前的裝置。事件會標示為與進行通話的裝置相關,
- 用來分組事件 ID 的相關事件 ID;當相關事件 ID 為 0 時,系統會將該事件標示為與任何其他事件無關;
- 緊急狀況;預設為非緊急。
詳細說明 | |||||||||
---|---|---|---|---|---|---|---|---|---|
參數 |
|
||||||||
傳回 |
event_id_t 事件 ID (如果事件寫入記錄中),則事件 ID 為 0。
|
LoggingManagement
LoggingManagement( nl::Weave::WeaveExchangeManager *inMgr, size_t inNumBuffers, const LogStorageResources *const inLogStorageResources )
LoggingManagement 建構函式中。
使用 LogStorageResources 陣列初始化 LoggingManagement。陣列必須為每個有效的重要性等級提供資源,陣列的元素必須依重要性數值提高重要性 (且重要性會降低);陣列中的第一個元素對應分配到最重要事件的資源,最後一個元素則對應到最不重要的事件。
詳細說明 | |||||||
---|---|---|---|---|---|---|---|
參數 |
|
LoggingManagement
LoggingManagement( void )
MarkShutdownInProgress
void MarkShutdownInProgress( void )
將 mShutdownInProgress 標記設為 true。
NotifyEventsDelivered
void NotifyEventsDelivered( ImportanceType inImportance, event_id_t inLastDeliveredEventID, uint64_t inRecipientNodeID )
RegisterEventCallbackForImportance
WEAVE_ERROR RegisterEventCallbackForImportance( ImportanceType inImportance, FetchExternalEventsFunct inFetchCallback, NotifyExternalEventsDeliveredFunct inNotifyCallback, NotifyExternalEventsEvictedFunct inEvictedCallback, size_t inNumEvents, event_id_t *outLastEventID )
用於註冊一組外部儲存事件的公用 API。
註冊 FetchExternalEventsFunct 表單的回呼。這個 API 要求平台必須取得註冊的事件數量。內部作業也會要求此數值為常數。這個 API 不允許平台登錄特定事件 ID,因此會導致平台無法保存事件 (至少含有不重複的事件 ID)。
只要訂閱者嘗試擷取範圍內的事件 ID 任意次數,直到取消註冊為止,系統就會呼叫回呼。
如果外部供應器想要在將事件傳送至訂閱者時收到通知,以及外部事件物件遭到撤銷時,則應使用該函式的變化版本。
事件傳送時,外部供應器會收到通知,以及接收者的節點 ID 和最終傳送給該收件者的事件 ID。請注意,系統可能會多次通知外部供應者使用相同的事件 ID。處理常式沒有特定的限制,具體而言,處理常式可能會取消註冊外部事件 ID。
如果記錄緩衝區移除了外部事件物件,系統就會通知外部供應器,並附上外部事件物件的副本。
失敗時,ExternalEvents 結構的指標為空值,否則將填入回呼的開始和結束事件 ID。這個指標應用於取消註冊一組事件。
如要進一步瞭解回呼必須實作的內容,請參閱 FetchExternalEventsFunct 文件。
詳細說明 | |||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|
參數 |
|
||||||||||||
傳回值 |
|
RegisterEventCallbackForImportance
WEAVE_ERROR RegisterEventCallbackForImportance( ImportanceType inImportance, FetchExternalEventsFunct inFetchCallback, NotifyExternalEventsDeliveredFunct inNotifyCallback, size_t inNumEvents, event_id_t *outLastEventID )
用於註冊一組外部儲存事件的公用 API。
註冊 FetchExternalEventsFunct 表單的回呼。這個 API 要求平台必須取得註冊的事件數量。內部作業也會要求此數值為常數。這個 API 不允許平台登錄特定事件 ID,因此會導致平台無法保存事件 (至少含有不重複的事件 ID)。
只要訂閱者嘗試擷取範圍內的事件 ID 任意次數,直到取消註冊為止,系統就會呼叫回呼。
如果外部供應器想要在事件傳送至訂閱者時收到通知,則應使用此函式的變化版本,但如果外部事件物件遭到撤銷,就不應該使用該函式變化版本。事件傳送時,外部供應器會收到通知,以及接收者的節點 ID 和最終傳送給該收件者的事件 ID。請注意,系統可能會多次通知外部供應者使用相同的事件 ID。處理常式沒有特定的限制,具體而言,處理常式可能會取消註冊外部事件 ID。
失敗時,ExternalEvents 結構的指標為空值,否則將填入回呼的開始和結束事件 ID。這個指標應用於取消註冊一組事件。
如要進一步瞭解回呼必須實作的內容,請參閱 FetchExternalEventsFunct 文件。
詳細說明 | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
參數 |
|
||||||||||
傳回值 |
|
RegisterEventCallbackForImportance
WEAVE_ERROR RegisterEventCallbackForImportance( ImportanceType inImportance, FetchExternalEventsFunct inFetchCallback, size_t inNumEvents, event_id_t *outLastEventID )
用於註冊一組外部儲存事件的公用 API。
註冊 FetchExternalEventsFunct 表單的回呼。這個 API 要求平台必須取得註冊的事件數量。內部作業也會要求此數值為常數。這個 API 不允許平台登錄特定事件 ID,因此會導致平台無法保存事件 (至少含有不重複的事件 ID)。
只要訂閱者嘗試擷取範圍內的事件 ID 任意次數,直到取消註冊為止,系統就會呼叫回呼。
當外部供應器需要通知,或外部事件物件遭到清除時,都應使用此函式的變體。
失敗時,ExternalEvents 結構的指標為空值,否則將填入回呼的開始和結束事件 ID。這個指標應用於取消註冊一組事件。
如要進一步瞭解回呼必須實作的內容,請參閱 FetchExternalEventsFunct 文件。
詳細說明 | |||||||||
---|---|---|---|---|---|---|---|---|---|
參數 |
|
||||||||
傳回值 |
|
ScheduleFlushIfNeeded
WEAVE_ERROR ScheduleFlushIfNeeded( bool inFlushRequested )
安排記錄檔卸載工作。
函式會決定是否安排工作卸載程序,如果是,則會排定在 Weave 執行緒上以非同步方式執行 LoggingFlushHandler
。
安排清除時間取決於三個因素:
清除緩衝區的明確要求
事件緩衝區的狀態,以及尚未與事件用戶端同步處理的資料量
是否有待處理的要求清除要求事件。
排程清除的明確要求會透過輸入參數傳遞。
系統通常會在事件緩衝區包含足夠資料時安排自動清除作業,以利開始新的卸載。視卸載策略而定,可能也會將其他觸發事件 (例如卸載之間的最短和最長時間) 納入考量。
事件記錄的待處理狀態會以 mUploadRequested
變數表示。這個函式可以由多個執行緒呼叫,因此 mUploadRequested
必須自動讀取及設定,以免在通知送出前排定冗餘的 LoggingFlushHandler
。
詳細說明 | |||||
---|---|---|---|---|---|
參數 |
|
||||
傳回值 |
|
SerializeEvents
WEAVE_ERROR SerializeEvents( TLVWriter & writer )
將所有重要類型的 Weave 事件序列化。
將 WeaveCircularTLVBuffer 中的事件和相關狀態序列化到提供的緩衝區。
這個方法適合在睡眠時未保留 RAM 的裝置使用,讓裝置可以在入睡前保留事件,從而避免事件遺失
SetBDXUploader
void SetBDXUploader( LogBDXUpload *inUploader )
SetExchangeManager
WEAVE_ERROR SetExchangeManager( nl::Weave::WeaveExchangeManager *inMgr )
設定要與這個記錄子系統搭配使用的 WeaveExchangeManager。
在某些平台上,這可能需要與上述 CreateLoggingManagement() 不同。
詳細說明 | |||
---|---|---|---|
參數 |
|
SetLoggingEndpoint
WEAVE_ERROR SetLoggingEndpoint( event_id_t *inEventEndpoints, size_t inNumImportanceLevels, size_t & outLoggingPosition )
SkipEvent
void SkipEvent( EventLoadOutContext *aContext )
用於略過寫入與分配事件 ID 對應的事件的輔助函式。
詳細說明 | |||
---|---|---|---|
參數 |
|
ThrottleLogger
void ThrottleLogger( void )
ThrottleLogger 會將有效記錄層級提升至實際工作環境等級。
UnregisterEventCallbackForImportance
void UnregisterEventCallbackForImportance( ImportanceType inImportance, event_id_t inEventID )
用於取消註冊一組外部儲存事件的公用 API。
取消註冊回呼後,LoggingManagement 就無法呼叫一組事件的回呼。LoggingManagement 不會再將這些事件 ID 傳送給訂閱者。
其用途是一次提供一組事件。如果必須使用相同函式註冊一組新事件,則必須先取消註冊回呼,然後重新註冊。這表示系統已無法擷取原始事件組合。
這個函式會無條件成功執行。如果回呼從未註冊或已取消註冊,則屬於免人工管理。
詳細說明 | |||||
---|---|---|---|---|---|
參數 |
|
UnthrottleLogger
void UnthrottleLogger( void )
UnthrottleLogger 會將有效記錄層級還原至設定的記錄層級。
公開的靜態函式
CreateLoggingManagement
void CreateLoggingManagement( nl::Weave::WeaveExchangeManager *inMgr, size_t inNumBuffers, const LogStorageResources *const inLogStorageResources )
建立 LoggingManagement 物件,並使用提供的資源初始化記錄管理子系統。
使用 LogStorageResources 陣列初始化 LoggingManagement。陣列必須為每個有效的重要性等級提供資源,陣列的元素必須依重要性數值提高重要性 (且重要性會降低);陣列中的第一個元素對應分配到最重要事件的資源,最後一個元素則對應到最不重要的事件。
詳細說明 | |||||||
---|---|---|---|---|---|---|---|
參數 |
|
DestroyLoggingManagement
void DestroyLoggingManagement( void )
執行關機所需的動作。