生產者 SDK 回呼 - Amazon Kinesis Video Streams

本文為英文版的機器翻譯版本,如內容有任何歧義或不一致之處,概以英文版為準。

生產者 SDK 回呼

Amazon Kinesis Video Streams 產生器開發套件中的類別和方法不會維護自己的程序。反之,他們會使用傳入的功能呼叫和事件來排程回呼與應用程式通訊。

有兩種呼模式應用程式可以使用與開發套件互動:

  • CallbackProvider— 此物件會將平台無關程式碼 (PIC) 元件的每個回呼公開至應用程式。此模式允許完整的功能,但也表示實作必須處理所有公有 API 方法和在 C++ 層的簽章。

  • StreamCallbackProviderClientCallbackProvider-這些對象公開了特定於流和客戶端特定的回調,並且 SDK 的 C ++ 層公開了其餘的回調。這是與製作者開發套件互動偏好的回呼模式。

下圖說明回呼物件的物件模型:

圖表顯示生產者和消費者在 Kinesis Video Streams 的互動。

在先前的圖表, DefaultCallbackProvider 從衍生的 CallbackProvider (公開在 PIC 的所有回呼) 和包含 StreamCallbackProviderClientCallbackProvider

ClientCallbackProvider

ClientCallbackProvider 用戶端層級回呼函數公開的物件。函數的詳細資訊說明在 ClientCallbacks 節。

回呼方法:

  • getClientReadyCallback— 報告用戶端的就緒狀態。

  • getStorageOverflowPressureCallback— 報告儲存空間溢位或壓力。此回呼稱為當儲存使用率低於 STORAGE_PRESSURE_NOTIFICATION_THRESHOLD 值,這是 5% 的整體儲存大小。如需詳細資訊,請參閱StorageInfo

StreamCallbackProvider

StreamCallbackProvider 串流層級回呼函數公開的物件。

回呼方法:

  • getDroppedFragmentReportCallback:報告捨棄的片段。

  • getDroppedFrameReportCallback— 報告丟棄的框架。

  • getFragmentAckReceivedCallback— 報告為流收到片段 ACK。

  • getStreamClosedCallback— 報告流關閉條件。

  • getStreamConnectionStaleCallback— 報告過時的連線狀況。在這種情況下,生產者正在向服務發送數據,但沒有收到確認。

  • getStreamDataAvailableCallback— 報告資料流中可用的資料。

  • getStreamErrorReportCallback— 報告串流錯誤情況。

  • getStreamLatencyPressureCallback— 報告串流延遲情況,也就是累積緩衝區大小大於max_latency值時。如需詳細資訊,請參閱StreamDefinition/StreamInfo

  • getStreamReadyCallback: — 報告資料流就緒條件。

  • getStreamUnderflowReportCallback— 報告資料流下溢狀況。此功能目前未使用,並保留供 future 使用。

如需的原始程式碼StreamCallbackProvider,請參閱 StreamCallbackProvider.h

ClientCallbacks 結構

ClientCallbacks 架構包含回呼函數進入點,當特定事件發生時的 PIC 呼叫。結構也包含版本資訊 CALLBACKS_CURRENT_VERSION 的欄位,以及 customData 欄位使用者定義資料回傳的個別回呼功能。

用戶端應用程式可以使用 this 指標 custom_data 欄位到對應成員函數的靜態 ClientCallback 函數在執行時間,如下列程式碼範例所示:

STATUS TestStreamCallbackProvider::streamClosedHandler(UINT64 custom_data, STREAM_HANDLE stream_handle, UINT64 stream_upload_handle) { LOG_INFO("Reporting stream stopped."); TestStreamCallbackProvider* streamCallbackProvider = reinterpret_cast<TestStreamCallbackProvider*> (custom_data); streamCallbackProvider->streamClosedHandler(...);
事件
函數 Description (描述) Type
CreateDeviceFunc 目前並未在後端實作。從 Java 或 C++ 呼叫時發生故障。其他用戶端執行平台特定的初始化。 後端 API
CreateStreamFunc 建立串流時呼叫。 後端 API
DescribeStreamFunc 呼叫 DescribeStream 時已呼叫。 後端 API
GetStreamingEndpointFunc 呼叫 GetStreamingEndpoint 時已呼叫。 後端 API
GetStreamingTokenFunc 呼叫 GetStreamingToken 時已呼叫。 後端 API
PutStreamFunc 呼叫 PutStream 時已呼叫。 後端 API
TagResourceFunc 呼叫 TagResource 時已呼叫。 後端 API
     
CreateMutexFunc 建立同步互斥。 同步
FreeMutexFunc 釋放互斥。 同步
LockMutexFunc 鎖定同步互斥。 同步
TryLockMutexFunc 嘗試鎖定互斥。目前並未實作。 同步
UnlockMutexFunc 解除鎖定互斥。 同步
     
ClientReadyFunc 當用戶端進入就緒狀態時呼叫。 通知
DroppedFrameReportFunc 當影格已刪除時報告。 通知
DroppedFragmentReportFunc 當片段已刪除時報告。此功能目前未使用,並保留供 future 使用。 通知
FragmentAckReceivedFunc 當片段 ACK (緩衝、收到、保留和錯誤) 收到呼叫。 通知
StorageOverflowPressureFunc 當儲存使用率低於 STORAGE_PRESSURE_NOTIFICATION_THRESHOLD 值時呼叫,這是定義為 5% 的整體儲存大小。 通知
StreamClosedFunc 當呼叫最後位元串流的剩餘影格。 通知
StreamConnectionStaleFunc 當串流輸入過時連線狀態時呼叫。在這個條件,是製作者傳送資料到服務但未收到確認。 通知
StreamDataAvailableFunc 串流資料可用時呼叫。 通知
StreamErrorReportFunc 出現串流錯誤時呼叫。在這個條件下的 PIC 自動關閉串流。 通知
StreamLatencyPressureFunc 串流進入延遲條件時呼叫,這是當累計緩衝大小大於 max_latency 值。如需詳細資訊,請參閱StreamDefinition/StreamInfo 通知
StreamReadyFunc 當串流進入就緒狀態時呼叫。 通知
StreamUnderflowReportFunc 此功能目前未使用,並保留供 future 使用。 通知
     
DeviceCertToTokenFunc 傳回連線憑證為字符。 平台整合
GetCurrentTimeFunc 傳回目前的時間。 平台整合
GetDeviceCertificateFunc 傳回裝置憑證。此功能目前未使用,並保留供 future 使用。 平台整合
GetDeviceFingerprintFunc 傳回裝置指紋。此功能目前未使用,並保留供 future 使用。 平台整合
GetRandomNumberFunc 傳回一隨機編號介於 0 和 RAND_MAX之間。 平台整合
GetSecurityTokenFunc 傳回傳遞給與後端 API 通訊之函數的安全性權杖。此實作可指定序列化 AccessKeyIdSecretKeyId 以及工作階段字符。 平台整合
LogPrintFunc 文字行日誌與標籤和日誌層級。如需詳細資訊,請參閱PlatformUtils.h 平台整合

對於先前表格的平台整合功能,最後參數是一種 ServiceCallContext 架構,其中包含下列欄位:

  • version:此結構的版本。

  • callAfter:絕對時間之後的呼叫函數。

  • timeout:逾時在 100 奈米秒單位的操作。

  • customData:使用者定義的值傳回用戶端。

  • pAuthInfo:呼叫的登入資料。如需詳細資訊,請參閱下列 (__AuthInfo) 結構。

授權資訊提供使用的 __AuthInfo 結構,這可以是序列化登入資料或提供者特定身分驗證字符。此架構包含下列欄位:

  • version:此版本的 __AuthInfo 結構。

  • typeAUTH_INFO_TYPE 數值定義登入資料類型 (憑證或安全字符)。

  • data:位元組陣列包含身分驗證資訊。

  • size:參數 data 的大小。

  • expiration:登入資料在 100 奈米秒單位過期。

重試流式傳輸的回調實現

Kinesis Video Producer SDK 提供透過回呼函數串流的狀態。建議您實作下列回呼機制,以便從串流期間遇到的任何暫時網路問題中復原。

  • 串流延遲壓力回呼-當 SDK 遇到串流延遲條件時,就會啟動此回呼機制。累積的緩衝大小大於 MAX_LATENCY 值時,就會發生這種情況。建立串流時,串流應用程式會將 MAX_LATENCY 設為 60 秒的預設值。此回呼的典型實作是重設連線。您可以根據需要使用示例實現 https://github.com/awslabs/ amazon-kinesis-video-streams-producer-sdk-cpp /blob /主/ /src /源/ kinesis-video-c-producer .c。StreamLatencyStateMachine請注意,沒有選項可以將由於網絡中斷而未傳遞的幀存儲到輔助存儲中以進行回填。

  • 流失效回呼-當生產者可以將資料傳送至 Amazon Kinesis Data Streams 服務 (上行) 但無法及時取得確認 (緩衝 ACK) 時,便會啟動此回呼 (預設值為 60 秒)。視網路設定而定,串流延遲壓力回呼或串流失效回呼,或兩者皆可啟動。與串流延遲壓力回呼重試實作類似,典型實作是重設連線並開始新的串流連線。您可以根據需要在 https://github.com/awslabs/ amazon-kinesis-video-streams-生產者-C/B ConnectionStaleStateMachine lob/主/src /源/ .c 中使用示例實現。

  • 串流錯誤回呼-當 SDK 在呼叫 KVS API 服務呼叫期間遇到網路連線逾時或其他錯誤時,就會啟動此回呼。

  • 丟棄幀回調-當存儲大小已滿無論是因為網絡速度慢或流錯誤,這個回調被啟動。如果網路速度導致影格下降,您可以增加儲存大小、縮小視訊影格大小或影格速率以符合網路速度。