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：說明時間戳記和其他與這個事件相關的標記。

CancelShutdownInProgress

void CancelShutdownInProgress(
  void
)

將 mShutdownInProgress 旗標設為 false。

CheckShouldRunWDM

bool CheckShouldRunWDM(
  void
)

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

函式的行為是透過 WEAVE_CONFIG_EVENT_LOGGING_BYTE_THRESHOLD 常數控制。如果系統自上次傳送 WDM 通知後寫入超過該數量，函式將指出應觸發 NotificationEngine。

詳細資料
傳回值
true
應卸載事件
false
其他情況

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 或記錄中的空間用盡為止。這個函式會終止在事件邊界寫入事件。

詳細資料
參數
[in] ioWriter
用於事件儲存的寫入者
[in] inImportance
待擷取事件的重要性
[in,out] ioEventID
在輸入時，緊接在要擷取的事件 ID。完成後，擷取的最後一個事件 ID。
傳回值
WEAVE_END_OF_TLV
函式的可用記錄項目已達指定重要性等級的結尾處
WEAVE_ERROR_NO_MEMORY
函式在 ioWriter 中用盡後，記錄中可使用更多事件。
WEAVE_ERROR_BUFFER_TOO_SMALL
函式在 ioWriter 中用盡後，記錄中可使用更多事件。

GetBytesWritten

uint32_t GetBytesWritten(
  void
) const

取得此記錄自執行個體執行個體化以來寫入的位元組總數 (涵蓋所有事件重要性)。

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

GetEventReader

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

這個輔助方法適用於檢查記憶體內記錄緩衝區。

詳細資料
參數
[in,out] ioReader
對讀取器的參照，將會使用事件記錄中的備份儲存空間初始化
[in] inImportance
讀者的起始重要性。請注意，在此情況下，起始重要性就好比符合直覺：除了其專屬的緩衝區外，更重要的事件會與較不重要的事件共用緩衝區。因此，傳入偵錯重要性時，讀取器會週遊最少的資料。
傳回
WEAVE_NO_ERROR 無條件。

GetFirstEventID

event_id_t GetFirstEventID(
  ImportanceType inImportance
)

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

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

GetLastEventID

event_id_t GetLastEventID(
  ImportanceType inImportance
)

擷取特定重要性等級的最近更新 ID。

詳細資料
參數
inImportance
重要性層級
傳回
針對該活動重要性使用 event_id_t 最近的活動 ID

IsShutdownInProgress

bool IsShutdownInProgress(
  void
)

檢查 mShutdownInProgress 旗標。

IsValid

bool IsValid(
  void
)

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

詳細資料
傳回值
true
執行個體有效 (已使用適當的備份儲存庫初始化)
false
其他情況

LoadEvents

WEAVE_ERROR LoadEvents(
  TLVReader & reader
)

載入先前保留的 Weave 事件。

LogEvent

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

透過回呼記錄事件，並提供選項。

該函式會記錄以 EventWriterFunct 表示的事件，以及應用程式專屬的 appData 情境。函式會寫入事件中繼資料，並使用 nl::Weave::TLV::TLVWriter 參照和 inAppData 結構定義呼叫 inEventWriter，如此一來，使用者程式碼就可以將事件資料直接發送到事件記錄中。這種形式的事件記錄會使記憶體用量降到最低，因為事件資料會直接序列化到目標緩衝區中。事件資料「必須」包含要在 inProfileID 和 inEventType 識別的結構定義中解讀的事件資料。系統會忽略第一個元素的標記。事件記錄系統就會換成 eventData 代碼。

如果結構定義重要性超過 LoggingConfiguration 中指定的記錄門檻，系統就會記錄事件。如果事件的重要性未達目前的門檻，系統就會捨棄該事件，且函式會傳回 0 做為產生的事件 ID。

此叫用的變體允許呼叫端設定任何 EventOptions 的組合：

  • 時間戳記 (如果 0 預設為呼叫時的目前時間)，
  • 「根」事件來源的區段 (事件來源和特徵 ID)；如果為 NULL，則預設為目前的裝置。事件會標示為與發出呼叫的裝置相關，
  • 用於分組事件 ID 的相關事件 ID；當相關事件 ID 為 0 時，該事件會標示為與任何其他事件無關；
  • 急迫性；預設為不會緊急

詳細資料
參數
[in] inSchema
結構定義用來定義這項事件的重要性、設定檔 ID 和結構類型。
[in] inEventWriter
此回呼會叫用以實際序列化事件資料
[in] inAppData
回呼的應用程式結構定義。
[in] inOptions
事件中繼資料的選項。可以是空值。
傳回
event_id_t 事件 ID (如果事件寫入記錄)，否則為 0。

LoggingManagement

 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

 LoggingManagement(
  void
)

LoggingManagement 預設建構函式。

主要目的是讓編譯器很滿意。

詳細資料
傳回

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」說明文件。

詳細資料
參數
[in] inImportance
重要性層級
[in] inFetchCallback
註冊以擷取外部事件的回呼
[in] inNotifyCallback
用於登錄運送通知的回呼
[in] inEvictedCallback
用於註冊撤銷通知的回呼
[in] inNumEvents
這個組合中的事件數量
[out] outLastEventID
指向 event_id_t；成功註冊外部事件時，函式會儲存與外部事件區塊的最後一個事件 ID 相對應的事件 ID。參數可以是空值。
傳回值
WEAVE_ERROR_NO_MEMORY
如果沒有其他可用的回呼運算單元。
WEAVE_ERROR_INVALID_ARGUMENT
空值函式回呼函式或沒有可註冊的事件。
WEAVE_NO_ERROR
成功時。

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」說明文件。

詳細資料
參數
[in] inImportance
重要性層級
[in] inCallback
註冊以擷取外部事件的回呼
[in] inNotifyCallback
用於登錄運送通知的回呼
[in] inNumEvents
這個組合中的事件數量
[out] outLastEventID
指向 event_id_t；成功註冊外部事件時，函式會儲存與外部事件區塊的最後一個事件 ID 相對應的事件 ID。參數可以是空值。
傳回值
WEAVE_ERROR_NO_MEMORY
如果沒有其他可用的回呼運算單元。
WEAVE_ERROR_INVALID_ARGUMENT
空值函式回呼函式或沒有可註冊的事件。
WEAVE_NO_ERROR
成功時。

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」說明文件。

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

ScheduleFlushIfNeeded

WEAVE_ERROR ScheduleFlushIfNeeded(
  bool inFlushRequested
)

排定記錄檔卸載工作。

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

安排清除時間的原因取決於三個因素：

清除緩衝區的明確要求

事件緩衝區的狀態，以及尚未與事件取用端同步的資料量

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

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

一般而言，自動清除作業會安排在事件緩衝區含有足夠資料，以便啟動新的卸載。視卸載策略而定，系統可能還會將卸載間隔時間的最短和最長時間等觸發納入考量。

事件記錄的待處理狀態會以 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

SetLoggingEndpoint

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

SkipEvent

void SkipEvent(
  EventLoadOutContext *aContext
)

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

詳細資料
參數
[in,out] aContext
EventLoadOutContext，使用緩衝區的有狀態資訊初始化。BlitEvent 會使用這個結構定義更新及保留狀態。

ThrottleLogger

void ThrottleLogger(
  void
)

ThrottleLogger 將有效記錄等級提升到實際工作環境等級。

UnregisterEventCallbackForImportance

void UnregisterEventCallbackForImportance(
  ImportanceType inImportance,
  event_id_t inEventID
)

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

取消註冊回呼可避免 LoggingManagement 呼叫一組事件的回呼。LoggingManagement 不會再將這些事件 ID 傳送給訂閱者。

使用意圖是讓單一函式一次提供一組事件。如要使用相同函式登錄一組新的事件，請先取消註冊回呼，然後再重新註冊。這表示系統無法再擷取原本的事件組合。

這個函式會無條件執行。如果回呼從未註冊或未註冊，即免人工管理。

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

UnthrottleLogger

void UnthrottleLogger(
  void
)

UnthrottleLogger 將有效記錄等級還原為已設定的記錄層級。

公開的靜態函式

CreateLoggingManagement

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 陣列。

DestroyLoggingManagement

void DestroyLoggingManagement(
  void
)

執行關機時所需的任何操作。

GetInstance

LoggingManagement & GetInstance(
  void
)