API说明【C纯传输层SDK】
API接口
所有API接口定义均位于SDTerminalSdk.h文件中。
1、系统环境初始化，仅需调用一次
void SDTerminal_Enviroment_Init(const char * outputPath, int outputLevel)
参数：
@param: outputPath：日志文件输出的目录，若目录不存在，SDK将自动创建，支持相对路径或绝对路径。日志对于问题定位非常重要，建议开启。
@param: outputLevel：日志输出的级别，只有等于或者高于该级别的日志会输出到文件，日志级别取值见LOG_OUTPUT_LEVEL定义，有DEBUG、INFO、WARNING、ERROR、ALARM、FATAL、NONE几个级别可选，当指定为NONE时，将不会生成日志文件。
2、系统退出时调用一次反初始化
void SDTerminal_Enviroment_Free()
3、创建客户端SDK对象
void* SDTerminal_Create();
4、销毁客户端SDK对象
void SDTerminal_Delete(void** ppTerminal);
参数：
@ ppTerminal，模块指针的指针
::: caution
使用者应该做好与其他API之间的互斥保护。
:::
5、登录服务器
int SDTerminal_Online(
void* pTerminal,
char* strMediaServerIp,
unsigned int unDomainId,
unsigned int unUid,
unsigned int unRoomId,
USER_ONLINE_TYPE eUserType
);
参数：
@pTerminal，模块指针
@strMediaServerIp，服务器IP地址
@unDomainId，域ID，默认为1即可，具体含义请参考SRTP-Server服务器设计相关文档。
@unUid，表示当前客户端使用的唯一用户ID，需要由用户自行保障唯一性。要求非0。
@unRoomId，表示当前客户端进入的房间号，要求非0。
@eUserType，表示客户端的类型，定义如下
typedef enum USER_ONLINE_TYPE
{
//其他类型，保留
USER_ONLINE_TYPE_OTHER = 0,
//音视频收发类型
USER_ONLINE_TYPE_AV_SEND_RECV,
//仅接收音视频类型
USER_ONLINE_TYPE_AV_RECV_ONLY,
//仅发送音视频类型
USER_ONLINE_TYPE_AV_SEND_ONLY
} USER_ONLINE_TYPE;
用户根据自身业务选择合适的客户端类型，以获得资源的最低占用。
返回值：返回0表示登录成功，返回负数则为失败，负数值为其错误码。
::: caution
本API为阻塞式同步登录接口，登录失败的超时时间较长，请避免在UI线程中调用。若需要异步登录接口，请参考SDTerminal_OnlineAsync，后者即刻返回，并通过回调接口通知外层登录结果。
:::
6、下线服务器
void SDTerminal_Offline(void* pTerminal);
参数：
@pTerminal，模块指针
返回值：无
::: caution
下线服务器，若此时用户在音视频位置上，将同时从位置上下来（自动调用OffPosition）。
:::
7、请求上传音视频到指定位置
int SDTerminal_OnPosition(void* pTerminal, unsigned char *pucPosition);
参数：
@pTerminal，模块指针
@pucPosition，大于等于0，小于系统支持的最大位置数（宏 MAX_SUPPORT_POSITION_NUM
定义）。特殊值：当设置为255时表示由服务器分配当前空闲的位置，分配结果将写回本参数。本函数调用成功后，客户端将自动停止接收自己位置的音视频流（不看不听自己）。
返回值：
返回0表示请求发布成功，返回负数则为失败，负数值为其错误码。
::: caution
请在Online成功后调用才能生效
:::
8、请求从位置上下来
void SDTerminal_OffPosition(void* pTerminal);
参数：
@pTerminal，模块指针
返回值：无
调用OffPosition后，客户端将从服务器所在位置上下来并停止发送音视频数据，此时它仍然保持在线状态并能接收其他位置的音视频流。本函数调用成功后，将自动恢复接收自己之前位置的音视频流（可能有其他客户端加入该位置）。
::: caution
本接口只能在Online成功后调用。SDTerminal_Offline内部自带本API功能，客户端下线可以不用单独调用本API，直接调用SDTerminal_Offline即可。
:::
9、上传视频数据
void SDTerminal_SendVideoData(void* pTerminal, unsigned char *byBuf, unsigned int unLen, unsigned int unDts);
向请求的位置发送视频码流，一次传入一帧带起始码的码流。
参数：
@pTerminal，模块指针
@byBuf，码流存放区。
@unLen，码流长度。
@unDts, SDK默认使用内部时间戳，此时本参数将被忽略。当用户期望使用外部时间戳时，需调用
SDTerminal_SetUseInternalTimeStamp API来指定时间戳工作模式。
返回值：无
::: tip
发送视频码流，一次传入一帧带起始码(0x 00 00 00 01或0x00 00 01)的码流。
:::
10、上传音频数据
void SDTerminal_SendAudioData(void* pTerminal, unsigned char *byBuf, unsigned int unLen, unsigned int unDts);
向请求的位置发送音频码流，一次传一帧ADTS码流。
参数：
@pTerminal，模块指针
@byBuf，码流存放区。
@unLen，码流长度。
@unDts, SDK默认使用内部时间戳，此时本参数将被忽略。当用户期望使用外部时间戳时，需调用
SDTerminal_SetUseInternalTimeStamp API来指定时间戳工作模式。
返回值：无
::: tip
发送音频码流，一次传一帧ADTS码流。内部将校验ADTS头合法性。
:::
11、设置音视频下行掩码
void SDTerminal_SetAvDownMasks (void* pTerminal, unsigned int unAudioMask, unsigned int unVideoMask);
通过设置音视频下行掩码，可以选择从服务器接收哪几个位置的音视频数据。每一个bit对应一个位置，最低位对应0号位置，最高位对应31号位置。比如希望接收某个index位置的音视频时，可以设置其对应bit设置为1，否则设置为0。
允许接收某个index位置的音视频时，可以设置为：
UINT unMask = 0x1 << (index);
unAudioDownChannelsMask |= unMask;
unVideoDownChannelsMask |= unMask;
停止接收某个index位置的音视频时，可以设置为：
UINT unMask = 0x1 << (index);
unMask = ~unMask;
unAudioDownChannelsMask &= unMask;
unVideoDownChannelsMask &= unMask;
SDTerminal_SetAvDownMasks (pTerminal, unAudioDownChannelsMask, unVideoDownChannelsMask);
当本客户端仅发送音视频，不接收音视频时，设置音视频接收掩码全为0即可。
参数：
@pTerminal，模块指针
@unAudioMask，控制音频接收的掩码。
@unVideoMask，控制视频接收的掩码。
返回值：无
::: caution
请在Online成功后调用
:::
12、设置音视频传输参数
void SDTerminal_SetTransParams(void* pTerminal,
unsigned int unJitterBuffDelay, FEC_REDUN_TYPE eFecRedunMethod,
unsigned int unFecRedunRatio,
unsigned int unFecMinGroupSize, unsigned int unFecMaxGroupSize, BOOL bEnableNack);
参数：
@pTerminal，模块指针
@unJitterBuffDelay，本客户端接收码流时的内部缓存时间（毫秒）,范围0~600。设置为0时，将关闭内部接收JitterBuff功能。
@eFecRedunMethod，为上行FEC冗余度方法，包括AUTO_REDUN自动冗余度、FIX_REDUN固定冗余度。
@unFecRedunRatio，上行冗余比率，比如设置为30，则表示使用30%冗余。自动冗余度时以该冗余度作为上限，根据网络情况向下调整。
@unFecMinGroupSize，为上行FEC分组的下限值， 1Mbps以下建议设置为16，1Mbps~2Mbps建议设置24，2Mbps以上建议设置28。
@unFecMaxGroupSize，为上行FEC分组的上限值，根据终端CPU能力而定，最大不超过72，越大FEC所消耗的CPU越高，抗丢包能力也越强，建议性能足够的设备上设置为64。
@bEnableNack，是否启用NACK功能。
返回值：无
::: caution
本函数需在Online之前调用。
:::
13、获取当前SDK版本信息
UINT SDTerminal_GetVersion (void* pTerminal);
参数：
@pTerminal，模块指针
返回值：获得当前SDK的版本信息
14、获取当前丢包率数据
void SDTerminal_GetVideoAudioUpDownLostRatio(void* pTerminal, float *pfVideoUpLostRatio, float *pfVideoDownLostRatio, float *pfAudioUpLostRatio, float *pfAudioDownLostRatio);
参数：
@pTerminal，模块指针
@pfVideoUpLostRatio，获取视频上行丢包率
@pfVideoDownLostRatio，获取视频下行丢包率
@pfAudioUpLostRatio，获取音频上行丢包率
@pfAudioDownLostRatio，获取音频下行丢包率
返回值：内部已经乘100得到百分比
15、获取当前视频通道的实时RTT
unsigned int SDTerminal_GetCurrentRtt(void* pTerminal);
@pTerminal，模块指针
返回值：获得当前视频通道的实时RTT值
设置回调接口
内部状态、接收的远端音视频数据均通过回调函数的方式交给外层，SDK提供了相关的回调函数设置接口。
::: caution
1、通知型回调函数中应尽可能快的退出，不进行耗时操作。
2、数据型回调函数中允许进行解码处理
:::
1、设置系统状态通知回调
void SDTerminal_SetSystemStatusNotifyCallback(void* pTerminal, SystemStatusNotifyFunc pfStatusNotifyCallback, void* pObject);
参数：
@pTerminal，模块指针
@pfStatusNotifyCallback,回调函数指针
@ pObject，透传指针，将透传给回调函数。
返回值：无
2、设置视频数据接收回调
void SDTerminal_SetRecvRemoteVideoCallback(void* pTerminal, RecvRemoteVideoFunc pfRecvRemoteVideoCallback, void* pObject)
参数：
@pTerminal，模块指针
@pfRecvRemoteVideoCallback,回调函数指针
@pObject，透传指针，将透传给回调函数。
RecvRemoteVideoFunc的定义如下：
void (*RecvRemoteVideoFunc)(void* pObject, unsigned char ucPosition, unsigned char* data, unsigned int unLen, unsigned int unPTS, VideoFrameInfor* pFrameInfo);
其中，VideoFrameInfor提供了当前帧以及当前流的重要信息：
typedef struct VideoFrameInfor
{
unsigned int unWidth;
unsigned int unHeight;
unsigned int unFps;
BOOL bPacketLost;
BOOL bKeyFrame;
BOOL bInfoUpdated;
unsigned char bySps[512];
unsigned int unSpsSize;
unsigned char byPps[512];
unsigned int unPpsSize;
}VideoFrameInfor;
模块内部会获得当前码流的宽、高、帧率、SPS、PPS告知外层，当其中某些参数发生变更时将置位bInfoUpdated。另外bPacketLost与bKeyFrame变量可用于外层实现丢帧冻结机制，bPacketLost表示当前帧是否接收完整，若网络丢包且FEC未能恢复时，该标志将置位。bKeyFrame表示当前帧是否为IDR关键帧。如何使用这两个标志实现丢帧冻结可以联系技术支持获得帮助。需要说明的是，当没有丢包发生时，本函数的输出与对方调用SDTerminal_SendVideoData函数的输入完全一致。
返回值：无
::: caution
SDK内部是在独立于网络接收线程之外的线程中调用本接口，所以外层可以将一定耗时的操作（比如解码）放置在此。
:::
3、设置音频数据接收回调
void SDTerminal_SetRecvRemoteAudioCallback(void* pTerminal, RecvRemoteAudioFunc pfRecvRemoteAudioCallback, void* pObject);
参数：
@pTerminal，模块指针
@pfRecvRemoteVideoCallback,回调函数指针
@pObject，透传指针，将透传给回调函数。
RecvRemoteAudioFunc的定义如下：
void (*RecvRemoteAudioFunc)(void* pObject, unsigned char ucPosition, unsigned char* data, unsigned int unLen, unsigned int unPTS, AudioFrameInfor* pFrameInfo);
其中，AudioFrameInfor提供了当前帧以及当前流的重要信息：
typedef struct AudioFrameInfor
{
unsigned int unCodecType;
unsigned int unSampleRate;
unsigned int unChannelNum;
unsigned int unFrameNo;
BOOL bInfoUpdated;
}AudioFrameInfor;
音频帧为ADTS格式，其每个包头部均附带了采样率、通道数、编码格式等信息。
返回值：无
::: caution
SDK内部是在独立于网络接收线程之外的线程中调用本接口，所以外层可以将一定耗时的操作（比如解码）放置在此。
:::
4、设置远端请求IDR通知回调
void SDTerminal_SetRemoteIdrRequestNotifyCallback(void* pTerminal, RemoteIdrRequestNotifyFunc pfRemoteIdrRequestNotifyCallback, void* pObject);
参数：
@pTerminal，模块指针
@pfRemoteIdrRequestNotifyCallback,回调函数指针
@pObject，透传指针，将透传给回调函数。
RemoteIdrRequestNotifyFunc的定义如下：
BOOL (*RemoteIdrRequestNotifyFunc)(void* pObject);
当服务端接收失败时，即会通过本回调通知本端，本端可以尽快编码IDR帧以避免远端长时间画面冻结。
返回值：无
::: caution
注意SDK内部是在网络接收线程中调用本回调，因此外层不应在回调中执行耗时操作，应尽快返回。
:::
5、设置码率自适应通知回调
void SDTerminal_SetAutoBitrateNotifyCallback(void* pTerminal,
AUTO_BITRATE_TYPE eAutoBitrateMethod,
AutoBitrateNotifyFunc pfAutoBitrateNotifyCallback,void* pObject);
参数：
@pTerminal，模块指针
@eAutoBitrateMethod，码率自适应方法：AUTO_BITRATE_TYPE_ADJUST_DISABLE（关闭码率自适应，默认不调用本API时即关闭状态）、AUTO_BITRATE_TYPE_ADJUST_FRAME_FIRST（优先降低帧率，其次降低码率）、AUTO_BITRATE_TYPE_ADJUST_BITRATE_FIRST（优先降低码率，其次降低帧率）。
@pfAutoBitrateNotifyCallback,回调函数指针
@pObject，透传指针，将透传给回调函数。
AutoBitrateNotifyFunc的定义如下：
BOOL (*AutoBitrateNotifyFunc)(void* pObject, unsigned int unFrameDropInterval, float fBitrateRatio);
当使用模块的码率自适应评估时，评估结果由本接口送出，外层负责具体的实施。比如unFrameDropInterval=2表示每2帧丢1帧。unFrameDropInterval为0表示不丢帧。比如fBitrateRatio=0.8表示需要将码率降低为原始码率的0.8倍。外层需同时响应帧率调整和码率调整，当外层执行了码率自适应动作时，返回TRUE，否则返回FALSE。
返回值：无
::: caution
注意SDK内部是在网络接收线程中调用本回调，因此外层不应在回调中执行耗时操作，应尽快返回。
:::
最后修改时间： 1 年前
API接口
1、系统环境初始化，仅需调用一次
2、系统退出时调用一次反初始化
3、创建客户端SDK对象
4、销毁客户端SDK对象
5、登录服务器
6、下线服务器
7、请求上传音视频到指定位置
8、请求从位置上下来
9、上传视频数据
10、上传音频数据
11、设置音视频下行掩码
12、设置音视频传输参数
13、获取当前SDK版本信息
14、获取当前丢包率数据
15、获取当前视频通道的实时RTT
设置回调接口
1、设置系统状态通知回调
2、设置视频数据接收回调
3、设置音频数据接收回调
4、设置远端请求IDR通知回调
5、设置码率自适应通知回调