プロデューサーSDKコールバック

Amazon Kinesis Video Streams プロデューサーのクラスとメソッドSDKは、独自のプロセスを維持しません。その代わり、受信した関数呼び出しとイベントを使用してコールバックをスケジュールし、アプリケーションと通信します。

アプリケーションが を操作するために使用できるコールバックパターンは 2 つありますSDK。

• CallbackProvider – このオブジェクトは、プラットフォームに依存しないコード (PIC) コンポーネントからのすべてのコールバックをアプリケーションに公開します。このパターンでは完全な機能を使用できますが、実装は C++ レイヤーのすべてのパブリックAPIメソッドと署名を処理する必要があることも意味します。

• StreamCallbackProvider および ClientCallbackProvider — これらのオブジェクトは、ストリーム固有およびクライアント固有のコールバックを公開し、 の C++ レイヤーは残りのコールバックをSDK公開します。これは、プロデューサー とやり取りするための優先コールバックパターンですSDK。

次の図は、コールバックオブジェクトのオブジェクトモデルです。

前の図では、 は CallbackProvider ( DefaultCallbackProvider のすべてのコールバックを公開するPIC) から取得され、 StreamCallbackProviderと が含まれますClientCallbackProvider。

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 – ストリームのアンダーフロー条件をレポートします。この関数は現在使用されておらず、将来の使用のために予約されています。

のソースコードについては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(...);

イベント

機能	説明	[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	クライアントが準備完了状態になると呼び出されます。	Notification
DroppedFrameReportFunc	フレームが削除されたときに報告されます。	Notification
DroppedFragmentReportFunc	フラグメントが削除されたときに報告されます。この関数は現在使用されておらず、将来の使用のために予約されています。	Notification
FragmentAckReceivedFunc	フラグメント ACK (バッファリング、受信、永続、エラー) が受信されると呼び出されます。	Notification
StorageOverflowPressureFunc	ストレージの使用率が STORAGE_PRESSURE_NOTIFICATION_THRESHOLD 値 (ストレージ全体のサイズの 5 パーセントとして定義) に下がると呼び出されます。	Notification
StreamClosedFunc	残りのフレームの最後のビットがストリーミングされたときに呼び出されます。	Notification
StreamConnectionStaleFunc	ストリームが古い接続状態になると呼び出されます。この状況では、プロデューサーはサービスにデータを送信していますが、送達確認を受信していません。	Notification
StreamDataAvailableFunc	ストリームデータが使用可能になったときに呼び出されます。	Notification
StreamErrorReportFunc	ストリームエラーが発生したときに呼び出されます。はこの条件下でストリームPICを自動的に閉じます。	Notification
StreamLatencyPressureFunc	ストリームがレイテンシー状態になったときに呼び出されます。蓄積されたバッファのサイズが max_latency 値より大きくなった場合です。詳細については、「StreamDefinition/StreamInfo」を参照してください。	Notification
StreamReadyFunc	ストリームが準備完了状態になると呼び出されます。	Notification
StreamUnderflowReportFunc	この関数は現在使用されておらず、将来の使用のために予約されています。	Notification
DeviceCertToTokenFunc	接続証明書をトークンとして返します。	プラットフォーム統合
GetCurrentTimeFunc	現在時刻を返します。	プラットフォーム統合
GetDeviceCertificateFunc	デバイス証明書を返します。この関数は現在使用されておらず、将来の使用のために予約されています。	プラットフォーム統合
GetDeviceFingerprintFunc	デバイスフィンガープリントを返します。この関数は現在使用されておらず、将来の使用のために予約されています。	プラットフォーム統合
GetRandomNumberFunc	0 から RAND_MAX までの乱数を返します。	プラットフォーム統合
GetSecurityTokenFunc	バックエンド と通信する関数に渡されるセキュリティトークンを返しますAPI。シリアル化された AccessKeyId、SecretKeyId、およびセッショントークンを指定して実装できます。	プラットフォーム統合
LogPrintFunc	タグとログレベルを伴うテキスト行をログ記録します。詳細については、「PlatformUtils.h」を参照してください。	プラットフォーム統合

前の表のプラットフォーム統合関数の最後のパラメータは ServiceCallContext 構造であり、以下のフィールドがあります。

• version: 構造のバージョン。

• callAfter: 関数を呼び出すまでの絶対時間。

• timeout: オペレーションのタイムアウト (100 ナノ秒単位)。

• customData: クライアントに返されるユーザー定義の値。

• pAuthInfo: 呼び出しの認証情報。詳細については、次の (__AuthInfo) 構造を参照してください。

認証情報は、__AuthInfo 構造を使用して提供されます。シリアル化された認証情報またはプロバイダー固有の認証トークンのいずれかを使用できます。この構造には次のフィールドがあります。

• version: __AuthInfo 構造のバージョン。

• type: 認証情報のタイプを定義する AUTH_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/master/kinesis-video-c-producer/src/source/StreamLatencyStateMachine.c で使用できます。ネットワークの停止により未配信のフレームを、バックフィル用のセカンダリストレージに保存することはできません。

• ストリームの古さコールバック - このコールバックは、プロデューサーが Amazon Kinesis Data Streams サービス (アップリンク) にデータを送信できるが、確認応答 (バッファされた ) を時間に戻すことができない (デフォルトは 60 秒ACK) ときに開始されます。ネットワーク設定に応じて、ストリームレイテンシープレッシャーコールバックまたはストリームの古さコールバックのいずれか、またはその両方が開始されます。ストリームのレイテンシープレッシャーコールバックの再試行の実装と同様に、一般的な実装として、接続をリセットし、ストリーミング用に新しい接続を開始します。必要に応じて、-https://github.com/awslabs/amazon-kinesis-video-streamsproducer-c/blob/master/src/source/ConnectionStaleStateMachine.c でサンプル実装を使用できます。

• ストリームエラーコールバック - このコールバックは、 KVS API がサービス呼び出しの呼び出し中にネットワーク接続でタイムアウトやその他のエラーSDKが発生したときに開始されます。

• ドロップフレームコールバック - このコールバックは、ネットワーク速度が遅いか、ストリームエラーが原因でストレージサイズがいっぱいになると開始されます。ネットワーク速度によってフレームがドロップされた場合は、ストレージサイズを増やすか、ビデオフレームサイズを減らすか、ネットワーク速度に合わせてフレームレートを下げることができます。