本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。
制作者 SDK 回调
亚马逊 Kinesis Video Streams Producer SDK 中的类和方法不维护自己的进程。相反，它们使用传入的函数调用和事件来安排用于与应用程序通信的回调。
应用程序可以使用两种回调模式来与开发工具包交互：
-
CallbackProvider— 此对象向应用程序公开来自平台独立代码 (PIC) 组件的每个回调。此模式允许使用全部功能，但这也意味着实施必须处理 C++ 层中的所有公有 API 方法和签名。 -
StreamCallbackProvider和ClientCallbackProvider— 这些对象公开了特定于流和特定于客户端的回调，而 SDK 的 C++ 层则公开了其余的回调。这是用于与创建者开发工具包交互的首选回调模式。
下图说明了回调对象的对象模型：
在上图中，DefaultCallbackProvider 派生自 CallbackProvider（后者公开 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(...);
事件 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 函数 | 描述 | 类型 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
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： |
通知 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
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 纳秒为单位）。
重试直播的回调实现
Kinesis Video Producer 开发工具包通过回调函数提供流式处理的状态。我们建议您实现以下回调机制，以从流式传输过程中遇到的任何短暂网络问题中恢复。
-
直播延迟压力回调-当 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 服务（上行链路）发送数据但无法及时获得确认（缓冲 ACK）时，将启动此回调（默认值为 60 秒）。根据网络设置，可以启动直播延迟压力回调或直播过时回调，或者两者都可启动。与流延迟压力回调重试实施相似，典型实施是重置连接并启动新的连接以进行流式处理。你可以在以下位置使用示例实现https://github.com/awslabs/amazon-kinesis-video-streams-producer-c/blob/master/src/sourConnectionStaleStateMachine.c
根据需要。 -
直播错误回调-当 SDK 在调用 KVS API 服务调用期间遇到网络连接超时或其他错误时，将启动此回调。
-
丢帧回调-此回调会在存储容量已满时启动，这可能是由于网络速度慢或流式传输错误。如果网络速度导致丢帧，则可以增加存储大小、减小视频帧大小或帧速率以匹配网络速度。