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
)

用於根據事件記錄通訊協定寫入事件標頭和資料的輔助函式。

詳細資料
參數
[in,out] aContext
EventLoadOutContext:以緩衝狀態的初始化方式初始化。BlitEvent 會使用這個結構定義更新並保留狀態。
[in] inSchema
結構定義:定義此事件的重要性、設定檔 ID 和結構類型。
[in] inEventWriter
要為事件資料序列化的叫用回呼。
[in] inAppData
回呼的應用程式內容。
[in] inOptions
EventOptions:說明與這個事件相關的時間戳記和其他標記。

取消關機作業進行中

void CancelShutdownInProgress(
  void
)

將 mShutdownInProgress 標記設為 false。

CheckRunRunDM

bool CheckShouldRunWDM(
  void
)

決定是否要依據未排定上傳的事件緩衝區位元組數,卸載事件。

函式的行為是由 WEAVE_CONFIG_EVENT_LOGGING_BYTE_THRESHOLD 常數控制。如果系統自上次傳送 WDM 通知後寫入的位元組數超過特定數量,函式就會指出觸發 NotificationEngine 的時間。

詳細資料
傳回值
true
應該卸載活動
false
其他情況

擷取事件自

WEAVE_ERROR FetchEventsSince(
  nl::Weave::TLV::TLVWriter & ioWriter,
  ImportanceType inImportance,
  event_id_t & ioEventID
)

這個函式可擷取指定事件 ID 之後指定指定事件的事件。

提供 nl::Weave::TLV::TLVWriter (重要性類型) 和事件 ID 後,函式就會擷取指定事件自指定事件以來發生的重要性。函式會持續擷取事件,直到 nl::Weave::TLV::TLVWriter 的空間不足或記錄中為止。函式會在事件邊界終止。

詳細資料
參數
[in] ioWriter
用於事件儲存空間的寫入者
[in] inImportance
擷取事件的重要性
[in,out] ioEventID
輸入內容時,系統會立即擷取事件 ID,緊接在擷取的 ID 之前。完成後,系統擷取到的最後一個事件編號。
傳回值
WEAVE_END_OF_TLV
這個函式已達到指定嚴重性等級的可用記錄項目結束
WEAVE_ERROR_NO_MEMORY
此功能在 ioWriter 中耗盡空間,在記錄中可用於更多事件。
WEAVE_ERROR_BUFFER_TOO_SMALL
此功能在 ioWriter 中耗盡空間,在記錄中可用於更多事件。

GetBytes 寫入

uint32_t GetBytesWritten(
  void
) const 

從這個執行個體執行個體化之後,擷取到這個記錄的位元組總數 (在所有事件重要性中)。

詳細資料
傳回
寫入記錄的位元組數。

取得事件讀取者

WEAVE_ERROR GetEventReader(
  nl::Weave::TLV::TLVReader & ioReader,
  ImportanceType inImportance
)

用來檢查記憶體內記錄緩衝區的輔助方法。

詳細資料
參數
[in,out] ioReader
這個讀取程式將使用事件記錄中的備份儲存空間進行初始化
[in] inImportance
讀取者的起始重要性。請注意,在這種情況下,起始重要性有些許明確:較重要的事件除了緩衝事件之外,還會透過較不重要的事件共用緩衝區。因此,當 Debug 重要性
傳回
WEAVE_NO_ERROR 無條件。

取得第一個事件 ID

event_id_t GetFirstEventID(
  ImportanceType inImportance
)

擷取目前儲存特定嚴重性等級的第一個事件 ID。

詳細資料
參數
inImportance
重要性層級
傳回
event_id_t 目前儲存的事件 ID 是該事件的重要性

取得最終活動 ID

event_id_t GetLastEventID(
  ImportanceType inImportance
)

針對特定重要性等級擷取最新的 ID。

詳細資料
參數
inImportance
重要性層級
傳回
event_id_t 最近根據該事件的重要性來更新事件 ID

停止執行中

bool IsShutdownInProgress(
  void
)

勾選 mShutdownInProgress 標記。

有效

bool IsValid(
  void
)

IsValid 會傳回 LoggingManagement 執行個體是否有效。

詳細資料
傳回值
true
執行個體有效 (已透過適當的備用存放區初始化)
false
其他情況

載入事件

WEAVE_ERROR LoadEvents(
  TLVReader & reader
)

載入先前持續的 Weave 事件。

記錄事件

event_id_t LogEvent(
  const EventSchema & inSchema,
  EventWriterFunct inEventWriter,
  void *inAppData,
  const EventOptions *inOptions
)

透過回呼記錄事件以及選項。

這個函式會記錄以 EventWriterFunct 表示的應用程式事件,以及應用程式專屬的 appData 結構定義。此函式會寫入事件中繼資料,並呼叫 inEventWriter 搭配 nl::Weave::TLV::TLVWriter 參考資料和 inAppData 結構定義,讓使用者程式碼可以將事件資料直接發送到事件紀錄中。這種事件紀錄功能可以盡量減少記憶體用量,因為事件資料會直接序列化為目標緩衝區。事件資料「必須」包含由 inProfileIDinEventType 所識別的結構定義來解釋的內容標記。系統會忽略第一個元素的標記,而事件記錄系統則會替換成 eventData 標記。

如果架構重要性超過 LoggingConfiguration 中指定的記錄門檻,系統就會記錄這個事件。如果事件的重要性不符合目前的門檻,系統就會予以捨棄,函式會傳回 0 做為產生的事件 ID。

這個叫用的變化版本允許呼叫者設定 EventOptions 的任意組合:

  • 時間戳記,當 0 預設為呼叫點的目前時間時,
  • 「活動根」部分 (事件來源和特性 ID) 區段;如果為 NULL,則預設為目前的裝置。該事件已標示為與呼叫呼叫的裝置相關,
  • 用來將事件 ID 分組的相關事件;如果相關事件 ID 為 0,系統就會將事件標示為與任何其他事件無關;
  • 急迫性;預設為不強制。

詳細資料
參數
[in] inSchema
結構定義:定義此事件的重要性、設定檔 ID 和結構類型。
[in] inEventWriter
實際叫用事件資料的回呼
[in] inAppData
回呼的應用程式內容。
[in] inOptions
事件中繼資料的選項。可能是 NULL。
傳回
event_id_t 事件:如果事件寫入到紀錄,則為 0;

記錄管理

 LoggingManagement(
  nl::Weave::WeaveExchangeManager *inMgr,
  size_t inNumBuffers,
  const LogStorageResources *const inLogStorageResources
)

LoggingManagement 建構函式。

使用 LogStorageResources 陣列初始化 LoggingManagement。陣列必須為每個有效重要性等級提供一項資源,陣列的元素必須提高數值的重要性 (同時降低重要性);陣列的第一個元素對應到最重要事件分配的資源,最後一個元素則對應到最不重要的事件。

詳細資料
參數
[in] inMgr
要搭配這個記錄子系統使用的 WeaveExchangeManager
[in] inNumBuffers
inLogStorageResources 陣列中的元素數量
[in] inLogStorageResources
每個重要性等級的 LogStorageResources 陣列。

記錄管理

 LoggingManagement(
  void
)

LoggingManagement 預設建構函式。

主要是為了讓編譯器能夠滿足您的需求。

詳細資料
傳回

MarkShutdownInProgress

void MarkShutdownInProgress(
  void
)

將 mShutdownInProgress 標記設為 true。

通知事件已傳送

void NotifyEventsDelivered(
  ImportanceType inImportance,
  event_id_t inLastDeliveredEventID,
  uint64_t inRecipientNodeID
)

註冊事件呼叫迴路

WEAVE_ERROR RegisterEventCallbackForImportance(
  ImportanceType inImportance,
  FetchExternalEventsFunct inFetchCallback,
  NotifyExternalEventsDeliveredFunct inNotifyCallback,
  NotifyExternalEventsEvictedFunct inEvictedCallback,
  size_t inNumEvents,
  event_id_t *outLastEventID
)

用於登錄一組外部儲存的公用 API。

註冊 FetchExternalEventsFunct 格式的回呼。此平台要求平台知道註冊時的事件數量。內部作業也需保持一致。這個 API 不允許平台註冊特定事件 ID,因此能避免平台持續儲存事件 (至少具有不重複的事件 ID)。

每當有使用者嘗試擷取範圍內的事件 ID 時,系統就會呼叫回呼,直到取消註冊為止。

如果外部供應商想要通知事件已傳送給訂閱者,以及外部事件物件遭到撤銷,則應使用此函式變體。

事件傳送完畢後,外部供應商會收到相關通知,同時附上收件者的節點 ID 以及最後傳送給該收件者的最終活動 ID。請注意,外部服務供應商可能會收到多次活動 ID 通知。處理常式沒有特定限制,特別是該處理常式可以取消註冊外部事件 ID。

如果從記錄緩衝區移除外部事件物件,系統會通知外部提供者,同時附上外部事件物件的副本。

失敗時,ExternalEvents 結構的指針將會是 NULL,否則會填入指派給回呼的開始和結束事件 ID。此指標應用於取消註冊事件集。

如要進一步瞭解回呼必須實作哪些項目,請參閱 FetchExternalEventsFunct 的說明文件。

詳細資料
參數
[in] inImportance
重要性層級
[in] inFetchCallback
註冊以擷取外部事件
[in] inNotifyCallback
註冊以傳送貨品交付通知
[in] inEvictedCallback
召回註冊移除通知
[in] inNumEvents
這個事件中的事件數
[out] outLastEventID
指向 event_id_t 的函式;成功註冊外部事件時,函式會儲存與外部事件區塊上次活動 ID 相對應的事件 ID。此參數可能是 NULL。
傳回值
WEAVE_ERROR_NO_MEMORY
如果沒有其他可用的回呼運算單元,
WEAVE_ERROR_INVALID_ARGUMENT
空值函式或沒有可註冊的事件。
WEAVE_NO_ERROR
成功。

註冊事件呼叫迴路

WEAVE_ERROR RegisterEventCallbackForImportance(
  ImportanceType inImportance,
  FetchExternalEventsFunct inFetchCallback,
  NotifyExternalEventsDeliveredFunct inNotifyCallback,
  size_t inNumEvents,
  event_id_t *outLastEventID
)

用於登錄一組外部儲存的公用 API。

註冊 FetchExternalEventsFunct 格式的回呼。此平台要求平台知道註冊時的事件數量。內部作業也需保持一致。這個 API 不允許平台註冊特定事件 ID,因此能避免平台持續儲存事件 (至少具有不重複的事件 ID)。

每當有使用者嘗試擷取範圍內的事件 ID 時,系統就會呼叫回呼,直到取消註冊為止。

外部服務供應商希望在已向訂閱者發送事件時收到通知,但在外部活動物件遭到撤銷時,則應使用此函式變體。事件傳送完畢後,外部供應商會收到相關通知,同時附上收件者的節點 ID 以及最後傳送給該收件者的最終活動 ID。請注意,外部服務供應商可能會收到多次活動 ID 通知。處理常式沒有特定限制,特別是該處理常式可以取消註冊外部事件 ID。

失敗時,ExternalEvents 結構的指針將會是 NULL,否則會填入指派給回呼的開始和結束事件 ID。此指標應用於取消註冊事件集。

如要進一步瞭解回呼必須實作哪些項目,請參閱 FetchExternalEventsFunct 的說明文件。

詳細資料
參數
[in] inImportance
重要性層級
[in] inCallback
註冊以擷取外部事件
[in] inNotifyCallback
註冊以傳送貨品交付通知
[in] inNumEvents
這個事件中的事件數
[out] outLastEventID
指向 event_id_t 的函式;成功註冊外部事件時,函式會儲存與外部事件區塊上次活動 ID 相對應的事件 ID。此參數可能是 NULL。
傳回值
WEAVE_ERROR_NO_MEMORY
如果沒有其他可用的回呼運算單元,
WEAVE_ERROR_INVALID_ARGUMENT
空值函式或沒有可註冊的事件。
WEAVE_NO_ERROR
成功。

註冊事件呼叫迴路

WEAVE_ERROR RegisterEventCallbackForImportance(
  ImportanceType inImportance,
  FetchExternalEventsFunct inFetchCallback,
  size_t inNumEvents,
  event_id_t *outLastEventID
)

用於登錄一組外部儲存的公用 API。

註冊 FetchExternalEventsFunct 格式的回呼。此平台要求平台知道註冊時的事件數量。內部作業也需保持一致。這個 API 不允許平台註冊特定事件 ID,因此能避免平台持續儲存事件 (至少具有不重複的事件 ID)。

每當有使用者嘗試擷取範圍內的事件 ID 時,系統就會呼叫回呼,直到取消註冊為止。

外部供應商想要傳送通知時,不論是外部事件傳送,還是外部事件物件遭到撤銷時,都應使用這個函式的變體版本。

失敗時,ExternalEvents 結構的指針將會是 NULL,否則會填入指派給回呼的開始和結束事件 ID。此指標應用於取消註冊事件集。

如要進一步瞭解回呼必須實作哪些項目,請參閱 FetchExternalEventsFunct 的說明文件。

詳細資料
參數
[in] inImportance
重要性層級
[in] inCallback
註冊以擷取外部事件
[in] inNumEvents
這個事件中的事件數
[out] outLastEventID
指向 event_id_t 的函式;成功註冊外部事件時,函式會儲存與外部事件區塊上次活動 ID 相對應的事件 ID。此參數可能是 NULL。
傳回值
WEAVE_ERROR_NO_MEMORY
如果沒有其他可用的回呼運算單元,
WEAVE_ERROR_INVALID_ARGUMENT
空值函式或沒有可註冊的事件。
WEAVE_NO_ERROR
成功。

排程 FlushIfIf

WEAVE_ERROR ScheduleFlushIfNeeded(
  bool inFlushRequested
)

安排記錄卸載工作。

函式會決定是否要排定工作卸載程序。如果是的話,它會排定 LoggingFlushHandler 在 Weave 執行緒上以非同步的方式執行。

想安排清除時間的決定取決於下列三個因素:

清除緩衝區的明確要求

事件緩衝區的狀態,以及尚未與事件消費者同步的資料量

是否有待處理的要求清除要求事件。

可明確安排安排的清除要求是透過輸入參數傳遞。

當自動緩衝區包含足夠的資料可啟動新的卸載程序時,通常就會安排自動清除。視卸載策略而定,系統可能也會將其他觸發條件 (例如卸載的最短和最長時間) 納入考慮。

事件紀錄的待處理狀態會以 mUploadRequested 變數表示。由於此函式可由多個執行緒呼叫,因此必須以不可分割的方式讀取及設定 mUploadRequested,以避免在通知傳送之前排定多餘的 LoggingFlushHandler

詳細資料
參數
inRequestFlush
布林值值,用於指定是否應安排清除清除 (無論內部緩衝管理政策為何)。
傳回值
WEAVE_ERROR_INCORRECT_STATE
LoggingManagement 模組未完全初始化。
WEAVE_NO_ERROR
成功。

SerializeEvents

WEAVE_ERROR SerializeEvents(
  TLVWriter & writer
)

將所有重要類型的 Weave 事件序列化。

將 WeaveCircularTLVBuffer 中的事件和相關聯的狀態序列化為提供的緩衝區。

這種方法適合在睡眠時不保留 RAM 的裝置使用,讓裝置能在入睡前保留事件,避免活動遺失。

SetBDXUploader

void SetBDXUploader(
  LogBDXUpload *inUploader
)

SetExchangeManager

WEAVE_ERROR SetExchangeManager(
  nl::Weave::WeaveExchangeManager *inMgr
)

設定要搭配此記錄子系統使用的 WeaveExchangeManager

在某些平台上,這可能需要與上述 CreateLoggingManagement() 分開執行。

詳細資料
參數
[in] inMgr
要搭配這個記錄子系統使用的 WeaveExchangeManager

設定記錄端點

WEAVE_ERROR SetLoggingEndpoint(
  event_id_t *inEventEndpoints,
  size_t inNumImportanceLevels,
  size_t & outLoggingPosition
)

略過事件

void SkipEvent(
  EventLoadOutContext *aContext
)

輔助函式略過與已分配事件 ID 相對應的事件。

詳細資料
參數
[in,out] aContext
EventLoadOutContext:以緩衝狀態的初始化方式初始化。BlitEvent 會使用這個結構定義更新並保留狀態。

ThrottleLogger 購物中心

void ThrottleLogger(
  void
)

ThrottleLogger 可將有效的紀錄等級提升至正式版等級。

取消註冊註冊呼叫回呼

void UnregisterEventCallbackForImportance(
  ImportanceType inImportance,
  event_id_t inEventID
)

用於取消註冊一組外部儲存事件的公開 API。

取消註冊回呼會導致 LoggingManagement 無法呼叫一組事件的回呼。LoggingManagement 將不再傳送這些活動 ID 給訂閱者。

意圖是讓一項函式一次提供一組事件。如果需要使用相同函式註冊一組新的事件,請先取消註冊,然後再重新註冊。這表示系統已無法擷取原始事件。

這項條件是無條件地成功執行。如果回呼從未註冊或已取消註冊,則屬於無回應。

詳細資料
參數
[in] inImportance
重要性層級
[in] inEventID
與事件取消註冊時對應的外部事件區塊中的任何事件對應的事件 ID。

UnthrottleLogger 工具

void UnthrottleLogger(
  void
)

UnthrottleLogger 會將有效的記錄等級恢復為已設定的記錄層級。

公開的靜態函式

建立記錄管理

void CreateLoggingManagement(
  nl::Weave::WeaveExchangeManager *inMgr,
  size_t inNumBuffers,
  const LogStorageResources *const inLogStorageResources
)

建立 LoggingManagement 物件,並使用所提供的資源初始化記錄管理子系統。

使用 LogStorageResources 陣列初始化 LoggingManagement。陣列必須為每個有效重要性等級提供一項資源,陣列的元素必須提高數值的重要性 (同時降低重要性);陣列的第一個元素對應到最重要事件分配的資源,最後一個元素則對應到最不重要的事件。

詳細資料
參數
[in] inMgr
要搭配這個記錄子系統使用的 WeaveExchangeManager
[in] inNumBuffers
inLogStorageResources 陣列中的元素數量
[in] inLogStorageResources
每個重要性等級的 LogStorageResources 陣列。

刪除 Logging 管理

void DestroyLoggingManagement(
  void
)

執行必要的關閉作業。

GetInstance

LoggingManagement & GetInstance(
  void
)