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

# 生產者開發套件回呼
<a name="producer-reference-callbacks"></a>

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

有兩種呼模式應用程式可以使用與開發套件互動：
+ `CallbackProvider` – 此物件會將平台獨立程式碼 (PIC) 元件的每個回呼公開給應用程式。此模式允許完整的功能，但也表示實作必須處理所有公有 API 方法和在 C\+\+ 層的簽章。
+ [StreamCallbackProvider](#producer-reference-callbacks-streamcallbackprovider) 和 [ClientCallbackProvider](#producer-reference-callbacks-clientcallbackprovider) – 這些物件公開串流特定和用戶端特定回呼，而 SDK 的 C\+\+ 層公開其餘回呼。這是與製作者開發套件互動偏好的回呼模式。

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

![圖表顯示 Kinesis Video Streams 中生產者和消費者的互動。](http://docs.aws.amazon.com/zh_tw/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(...);
```


**事件**  

| 函式 | 說明 | 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 | 當片段已刪除時報告。此函數目前未使用，並保留供日後使用。 | 通知 | 
| FragmentAckReceivedFunc | 當片段 ACK (緩衝、收到、保留和錯誤) 收到呼叫。 | 通知 | 
| StorageOverflowPressureFunc | 當儲存使用率低於 STORAGE\_PRESSURE\_NOTIFICATION\_THRESHOLD 值時呼叫，這是定義為 5% 的整體儲存大小。 | 通知 | 
| StreamClosedFunc | 當呼叫最後位元串流的剩餘影格。 | 通知 | 
| StreamConnectionStaleFunc | 當串流輸入過時連線狀態時呼叫。在這個條件，是製作者傳送資料到服務但未收到確認。 | 通知 | 
| StreamDataAvailableFunc | 串流資料可用時呼叫。 | 通知 | 
| StreamErrorReportFunc | 出現串流錯誤時呼叫。在這個條件下的 PIC 自動關閉串流。 | 通知 | 
| StreamLatencyPressureFunc | 串流進入延遲條件時呼叫，這是當累計緩衝大小大於 max\_latency 值。如需詳細資訊，請參閱[StreamDefinition/StreamInfo](producer-reference-structures-stream.md#producer-reference-structures-stream-streaminfo)。 | 通知 | 
| StreamReadyFunc | 當串流進入就緒狀態時呼叫。 | 通知 | 
| StreamUnderflowReportFunc | 此函數目前未使用，並保留供日後使用。 | 通知 | 
|   |   |   | 
| 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 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](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 服務呼叫期間遇到網路連線逾時或其他錯誤時，就會啟動此回呼。
+ **捨棄影格回呼** - 當儲存大小已滿時，由於網路速度緩慢或串流錯誤，會啟動此回呼。如果網路速度導致影格遺失，您可以增加儲存體大小、減少影片影格大小或影格速率以符合網路速度。