制作人 SDK 回调

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

应用程序可以使用两种回调模式来与开发工具包交互：

• CallbackProvider— 此对象公开了从独立于平台的代码 (PIC) 组件到应用程序的所有回调。此模式允许使用全部功能，但这也意味着实施必须处理 C++ 层中的所有公有 API 方法和签名。

• StreamCallbackProvideran ClientCallbackProvider d — 这些对象公开了特定于流和客户端特定的回调，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	在客户端进入就绪状态时调用。	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 遇到直播延迟情况时启动。这在累计缓冲区大小大于 MAX_LATENCY 值时发生。在创建流后，流式处理应用程序会将 MAX_LATENCY 设置为 60 秒（默认值）。此回调的典型实施是重置连接。你可以根据需要在 https://github.com/awslabs/ amazon-kinesis-video-streams-producer-sdk-cpp /blob/master/ /src/src/sroce/ kinesis-video-c-producer .c 上使用示例实现。StreamLatencyStateMachine请注意，无法将由于网络中断而未交付的帧存储到辅助存储器中进行回填。

• 直播失效回调 ——当创建者可以向 Amazon Kinesis Data Streams 服务（上行链路）发送数据，但无法及时获取确认（缓冲后的 ACK）（默认为 60 秒）时，就会启动此回调。根据网络设置，可以启动直播延迟压力回调或直播陈旧回调，或者两者兼而有之。与流延迟压力回调重试实施相似，典型实施是重置连接并启动新的连接以进行流式处理。你可以根据需要使用 https://github.com/awslabs/ amazon-kinesis-video-streams-producer-c/blob/master/src/src/ ConnectionStaleStateMachine surce/ .c 上的示例实现。

• 直播错误回调-当 SDK 在调用 KVS API 服务时遇到网络连接超时或其他错误时，将启动此回调。

• 丢帧回调-当由于网络速度慢或直播错误导致存储空间已满时，会启动此回调。如果网络速度导致丢帧，则可以增加存储大小、减小视频帧大小或帧速率以匹配网络速度。