制作人SDK回调 - Amazon Kinesis Video Streams
ClientCallbackProviderStreamCallbackProviderClientCallbacks用于重试直播的回调实现

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

制作人SDK回调

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

应用程序可以使用两种回调模式与之交互SDK：

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

  • StreamCallbackProvideran ClientCallbackProvider d — 这些对象公开了特定于流和客户端特定的回调，而的 C++ 层SDK公开了其余的回调。这是与制作人交互的首选回调模式SDK。

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

该图显示了 Kinesis Video Streams 中制作人和消费者的互动。

在上图中，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(...);
事件
函数 描述 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。 通知
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 视频制作器通过回调函数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 中的示例实现。请注意，无法将由于网络中断而未交付的帧存储到辅助存储器中进行回填。

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

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

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