翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。

# プロデューサー SDK コールバック
<a name="producer-reference-callbacks"></a>

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

アプリケーションが SDK とやり取りするために使用できるコールバックパターンは 2 つあります。
+ `CallbackProvider` – このオブジェクトは、プラットフォームに依存しないコード (PIC) コンポーネントからのすべてのコールバックをアプリケーションに公開します。このパターンではすべての機能を使用できますが、実装では C\+\+ レイヤーにあるすべてのパブリック API メソッドと署名を処理する必要があります。
+ [StreamCallbackProvider](#producer-reference-callbacks-streamcallbackprovider) および [ClientCallbackProvider](#producer-reference-callbacks-clientcallbackprovider) – これらのオブジェクトは、ストリーム固有およびクライアント固有のコールバックを公開し、SDK の C\+\+ レイヤーは残りのコールバックを公開します。これは、プロデューサー SDK とやり取りするために推奨されるコールバックパターンです。

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

![Kinesis Video Streams のプロデューサーとコンシューマーとのインタラクションを示す図表。](http://docs.aws.amazon.com/ja_jp/kinesisvideostreams/latest/dg/images/callbacks-10.png)


前の図の `DefaultCallbackProvider` は `CallbackProvider` (PIC のすべてのコールバックを公開します) から派生し、`StreamCallbackProvider` および `ClientCallbackProvider` が含まれます。

**Topics**
+ [ClientCallbackProvider](#producer-reference-callbacks-clientcallbackprovider)
+ [StreamCallbackProvider](#producer-reference-callbacks-streamcallbackprovider)
+ [ClientCallbacks 構造](#producer-reference-callbacks-clientcallbacks)
+ [ストリーミングを再試行するためのコールバック実装](#producer-reference-callbacks-retry)

## ClientCallbackProvider
<a name="producer-reference-callbacks-clientcallbackprovider"></a>

`ClientCallbackProvider` オブジェクトはクライアントレベルのコールバック関数を公開します。関数の詳細は「[ClientCallbacks 構造](#producer-reference-callbacks-clientcallbacks)」に記載されています。

**コールバックメソッド:**
+ `getClientReadyCallback` – クライアントの準備完了状態をレポートします。
+ `getStorageOverflowPressureCallback` – ストレージのオーバーフローまたはプレッシャーを報告します。このコールバックは、ストレージの使用率が以下の `STORAGE_PRESSURE_NOTIFICATION_THRESHOLD` 値 (ストレージ全体のサイズの 5 パーセント) に下がると呼び出されます。詳細については、「[StorageInfo](producer-reference-structures-producer.md#producer-reference-structures-producer-storageinfo)」を参照してください。

## StreamCallbackProvider
<a name="producer-reference-callbacks-streamcallbackprovider"></a>

`StreamCallbackProvider` オブジェクトはストリームレベルのコールバック関数を公開します。

**コールバックメソッド:**
+ `getDroppedFragmentReportCallback`: 削除されたフラグメントを報告します。
+ `getDroppedFrameReportCallback` – ドロップされたフレームをレポートします。
+ `getFragmentAckReceivedCallback` – ストリームのフラグメント ACK が受信されたことをレポートします。
+ `getStreamClosedCallback` – ストリームのクローズ状態を報告します。
+ `getStreamConnectionStaleCallback` – 古い接続条件を報告します。この条件では、プロデューサーは サービスにデータを送信していますが、確認を受信していません。
+ `getStreamDataAvailableCallback` – データがストリームで利用可能であることをレポートします。
+ `getStreamErrorReportCallback` – ストリームエラー状態を報告します。
+ `getStreamLatencyPressureCallback` – ストリームレイテンシー条件を報告します。これは、累積バッファサイズが `max_latency`値より大きい場合です。詳細については、「[StreamDefinition/StreamInfo](producer-reference-structures-stream.md#producer-reference-structures-stream-streaminfo)」を参照してください。
+ `getStreamReadyCallback`: – ストリーム準備完了状態を報告します。
+ `getStreamUnderflowReportCallback` – ストリームのアンダーフロー条件をレポートします。この関数は現在使用されておらず、将来の使用のために予約されています。

`StreamCallbackProvider` のソースコードについては、[StreamCallbackProvider.h](https://github.com/awslabs/amazon-kinesis-video-streams-producer-sdk-cpp/blob/d1684599a141785752582c16264e3123866f3cf8/kinesis-video-producer/src/StreamCallbackProvider.h) を参照してください。

## ClientCallbacks 構造
<a name="producer-reference-callbacks-clientcallbacks"></a>

`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(...);
```


**Events**  

| 関数 | 説明 | タイプ | 
| --- | --- | --- | 
| 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](producer-reference-structures-stream.md#producer-reference-structures-stream-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 ナノ秒単位)。

## ストリーミングを再試行するためのコールバック実装
<a name="producer-reference-callbacks-retry"></a>

Kinesis Video プロデューサー 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](https://github.com/awslabs/amazon-kinesis-video-streams-producer-c/blob/master/src/source/StreamLatencyStateMachine.c) のサンプル実装を使用することができます。ネットワーク停止による未配信のフレームを、バックフィル用のセカンダリストレージに保存することはできません。
+ **ストリームの古さコールバック** - このコールバックは、プロデューサーが Amazon Kinesis Data Streams サービス (アップリンク) にデータを送信できるが、確認応答 (バッファされた ACK) を時間に戻すことができない (デフォルトは 60 秒) 場合に開始されます。ネットワーク設定に応じて、ストリームレイテンシープレッシャーコールバックまたはストリームの古さコールバック、またはその両方が開始されます。ストリームのレイテンシープレッシャーコールバックの再試行の実装と同様に、一般的な実装として、接続をリセットし、ストリーミング用に新しい接続を開始します。必要に応じて、[https://github.com/awslabs/amazon-kinesis-video-streams-producer-c/blob/master/src/source/ConnectionStaleStateMachine.c](https://github.com/awslabs/amazon-kinesis-video-streams-producer-c/blob/master/src/source/ConnectionStaleStateMachine.c) のサンプル実装を使用することができます。
+ **ストリームエラーコールバック** - このコールバックは、SDK が KVS API サービスコールの呼び出し中にネットワーク接続でタイムアウトやその他のエラーが発生したときに開始されます。
+ **ドロップフレームコールバック** - このコールバックは、ネットワーク速度が遅いか、ストリームエラーが原因でストレージサイズがいっぱいになると開始されます。ネットワーク速度によってフレームがドロップされた場合は、ストレージサイズを大きくするか、ビデオフレームサイズを小さくするか、ネットワーク速度に合わせてフレームレートを小さくすることができます。