本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

# 制作人 SDK 回调
<a name="producer-reference-callbacks"></a>

亚马逊 Kinesis Video Streams Video Streams Producer SDK 中的类和方法不维护自己的流程。相反，它们使用传入的函数调用和事件来安排用于与应用程序通信的回调。

应用程序可以使用两种回调模式来与开发工具包交互：
+ `CallbackProvider`— 此对象公开了从独立于平台的代码 (PIC) 组件到应用程序的所有回调。此模式允许使用全部功能，但这也意味着实施必须处理 C\$1\$1 层中的所有公有 API 方法和签名。
+ [StreamCallbackProvider](#producer-reference-callbacks-streamcallbackprovider)an [ClientCallbackProvider](#producer-reference-callbacks-clientcallbackprovider) d — 这些对象公开了特定于流和客户端特定的回调，SDK 的 C\$1\$1 层公开了其余的回调。这是用于与创建者开发工具包交互的首选回调模式。

下图说明了回调对象的对象模型：

![\[该图显示了 Kinesis Video Streams 中制作人和消费者的互动。\]](http://docs.aws.amazon.com/zh_cn/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**  

| 函数 | 说明 | Type | 
| --- | --- | --- | 
| CreateDeviceFunc | 目前未在后端实施。在从 Java 或 C\$1\$1 调用时，此调用将失败。其他客户端执行特定于平台的初始化。 | 后端 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\$1PRESSURE\$1NOTIFICATION\$1THRESHOLD 值（该值定义为总体存储大小的 5%）以下时调用。 | 通知 | 
| StreamClosedFunc | 在流式处理其余帧的最后几个比特时调用。 | 通知 | 
| StreamConnectionStaleFunc | 在流进入过时连接状态时调用。在这种情况下，创建者会向服务发送数据，但收不到确认。 | 通知 | 
| StreamDataAvailableFunc | 在流数据可用时调用。 | 通知 | 
| StreamErrorReportFunc | 在出现流错误时调用。在这种情况下，PIC 会自动关闭流。 | 通知 | 
| StreamLatencyPressureFunc | 在流进入延迟状况（即累积缓冲区大小大于 max\$1latency 值时）调用。有关更多信息，请参阅 [StreamDefinition/StreamInfo](producer-reference-structures-stream.md#producer-reference-structures-stream-streaminfo)。 | 通知 | 
| StreamReadyFunc | 在流进入就绪状态时调用。 | 通知 | 
| StreamUnderflowReportFunc | 此函数目前未使用，保留供将来使用。 | 通知 | 
|   |   |   | 
| DeviceCertToTokenFunc | 以令牌形式返回连接证书。 | 平台集成 | 
| GetCurrentTimeFunc | 返回当前时间。 | 平台集成 | 
| GetDeviceCertificateFunc | 返回设备证书。此函数目前未使用，保留供将来使用。 | 平台集成 | 
| GetDeviceFingerprintFunc | 返回设备指纹。此函数目前未使用，保留供将来使用。 | 平台集成 | 
| GetRandomNumberFunc | 返回 0 和 RAND\$1MAX 之间的随机数。 | 平台集成 | 
| 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 遇到直播延迟情况时启动。这在累计缓冲区大小大于 MAX\$1LATENCY 值时发生。在创建流后，流式处理应用程序会将 MAX\$1LATENCY 设置为 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 秒）时，就会启动此回调。根据网络设置，可以启动直播延迟压力回调或直播陈旧回调，或者两者兼而有之。与流延迟压力回调重试实施相似，典型实施是重置连接并启动新的连接以进行流式处理。您可以根据需要使用-pro [c/blob/master/src/source/ConnectionStaleStateMachineducer https://github.com/awslabs/ amazon-kinesis-video-streams-.c](https://github.com/awslabs/amazon-kinesis-video-streams-producer-c/blob/master/src/source/ConnectionStaleStateMachine.c) 上的示例实现。
+ **直播错误回调**-当 SDK 在调用 KVS API 服务时遇到网络连接超时或其他错误时，将启动此回调。
+ **丢帧回调**-当由于网络速度慢或直播错误导致存储空间已满时，会启动此回调。如果网络速度导致丢帧，则可以增加存储大小、减小视频帧大小或帧速率以匹配网络速度。