P2P音视频传输接口使用说明

        P2P（Point-to-Point）音视频传输技术,是为节省服务器带宽而设计的。我设计和开发的接口使用如下，供参考。最近几天我会整理一下P2P 开发常见问题。该技术目前主要在监控安防，宠物机，扫地机，楼宇对讲，等物联网相关行业中应用。以下接口目前支持安凯AK，海思HI，君正，安霸，瑞芯微，安卓，IOS等平台。有免费示例代码提供参考。

版本	日期	说明
2.01.04	2018.01.04	新增接口
1.09.22	2017.09.22	支持音视频文件加密传输
1.06.19	2017.6.28	修改订阅成功说明
1.05.20	2017.5.20	新增订阅返回值
1.04.21	2017.4.21	新增串口透传
1.405	2017.4.5	新增局域网广播接口
1.320.13	2017.3.20	新增2个透传接口
1.14.11	2017.1.14	新增文件读取
1.07.05	20160705	新增订阅成功失败
接口概要
XCloudLink API 支持 PC，Android，IOS,以及各种嵌入式设备连接XCloud云服务。 为用户透传信令和P2P多媒体数据服务。本协议一共 10 个接口，2个回调消息。提供4大功能。以动态库的方式提供服务支持。 一、系统初始化：对应 [1] CDK_InitXCloudLink 和 [2]CDK_UNInitXCloudLink。 二、XCloud云登录：[3]CDK_LogIn 和 [4]CDK_LogOut 。 三、指令透传：[5]CDK_Subscribe 和[6]CDK_PostXMessage。 四、P2P多媒体数据传输：[5]CDK_Subscribe,[7]CDK_HelloXMan,[8]CDK_OpenSession           [9]CDK_SendMediaData ,[10]CDK_CloseSession。 五、局域网广播接口 六、使用 G1视频会话流程图，G2串口数据透传流程图 见文档最后。

1、CDK XCloudLink 加载初始化
接口原型	int  CDK_InitXCloudLink(unsigned short nOpt, XCLOUDMSGCALLBACK  xMsgCallBack,                       XCLOUDMEDIACALLBACK  xMediaCallBack);
参数	nOpt	备用
	xMsgCallBack	接收命令消息，参考下面文档
	xMediaCallBack	接收多媒体数据，参考下面文档
返回值	-1 初始化失败

2、CDK_UNInitXCloudLink 卸载
接口原型	void CDK_UNInitXCloudLink();
参数	无
返回值	无

3、系统用户登录
接口原型	int  CDK_LogIn(const char srtID[],const char strPsw[], XHOSTInfo  hostInfo[]， unsigned short nhostCount);// APP int  CDK_LogIn(const char srtID[],const char strPsw[], XHOSTInfo  hostInfo[]， unsigned short nhostCount，unsigned short  nReset，const char *pCompanyKey);//设备端
参数	srtID	设备ID
	strPsw	密码
	hostInfo[]	服务器地址数组
	nhostCount	服务器地址个数
	nReset	密码复位。此参数只有设备库才有
	pCompanyKey	公司秘钥默认为NULL 。此参数只有设备库才有
返回值

4、系统用户注销
接口原型	int  CDK_LogOut();
参数

5、设备订阅
接口原型	int CDK_Subscribe(const  char * strDstID, const char * strAuth, unsigned int nOption);
参数	strDstID	目标设备ID
	strAuth	设备认证密码，用MD加密后的数据
	nOption	A、默认 0 B、100 代表取消订阅
返回值	-1 err 系统未初始化，或者登陆失败 //注意：设备的当前状态通过此接口回调返回。 //订阅成功回调消息 XCLOUDMSG_SUBSCRIBESUCCESS //订阅失败回调消息 XCLOUDMSG_SUBSCRIBEFAIL

6.1、主动发送消息(字符串)仅客户端使用
接口原型	int  CDK_PostXMessage(const  char strDstID[], unsigned short nMessage,                                                         const char pString[] );
参数	strDstID	目标地址
	nMessage	消息类型，默认0
	pString	透传数据
返回值	-1 err 发送失败。 ret > 0
6.2、主动发送消息(字符串)
接口原型	int  CDK_PostXMessageEX(unsigned int nDstID,unsigned short nMessage,                                                  const char pString[] );
参数	nDstID	目标地址
	nMessage	消息类型，默认0
	pString	透传数据
返回值	-1 err 发送失败。 ret > 0 设备主动发起呼叫调用： CDK_PostXMessage(0, XCLOUDMSG_TRANSALT,"Calling:hba0001#201");

6.3、主动发送消息（二进制数据）
接口原型	int  CDK_PostBMessage(unsigned int nDstID, unsigned short nMessage, const char *pBinBuffer, unsigned short nBinSize);
参数	nDstID	目标地址
	nMessage	消息类型，默认0
	pBinBuffer	透传数据
	nBinSize	数据格式大小
返回值	-1 err 发送失败。 ret > 0

6.4、主动发送消息（二进制数据）
接口原型	int  CDK_PostBMessageEX(const  char strDstID[], unsigned short nMessage, const char *pBinBuffer, unsigned short nBinSize);
参数	strDstID	目标地址
	nMessage	消息类型，默认0
	pBinBuffer	透传数据
	nBinSize	数据格式大小
返回值	-1 err 发送失败。 ret > 0

7、设备连接
接口原型	int CDK_HelloXMan(const  char strDstID[]);
参数	strDstID	目标设备ID
返回值	-1 err 系统未初始化，或者登陆失败 //  无回调消息

8、打开会话
接口原型	unsigned int CDK_OpenSession(const char strDstID[], unsigned short nResType,unsigned short nRW);
参数	strDstID	目标设备ID
	nResType	参考  _XCLOUDSIDRES_TYPE
	nRW	enum _XCLOUDRES_OPT {     _XCLOUDRES_OPT_READ = 0,     _XCLOUDRES_OPT_WRITE, };
返回值	Err:0 目标设备不支持 OK: 返回 SessionID

9、发送媒体数据
接口原型	int  CDK_SendMediaData(unsigned int nSID, unsigned short nResType, unsigned char iFreamType, unsigned short lparam, const char *pMediaBuffer, unsigned int nMediaBufferSize);
参数	nSID	SESSION ID , CDK_OpenSession 返回值
	nResType	参考  _XCLOUDSIDRES_TYPE
	iFreamType	参考
	lparam	帧间隔
	pMediaBuffer	媒体数据
	nMediaBufferSize	媒体数据长度
返回值	-1 err 发送失败。 ret > 0

10、关闭会话
接口原型	int CDK_CloseSession(unsigned int nSID, unsigned short nResType);
参数	nSID	CDK_OpenSessin 返回值
	nResType	参考  _XCLOUDSIDRES_TYPE
返回值	-1 err 已经关闭

11、文件传输
接口原型	unsigned int CDK_OpenXCloudFile(const char  strDstID[], const char strFilename[],                          unsigned short nResType, unsigned short nRW);
参数	strDstID	目标ID
	strFilename	文件名，
	nResType	资源类型 _XCLOUDRES_FILE_1 .. _XCLOUDRES_FILE_VOD 为点播
	nRW	接收文件，发送文件{     _XCLOUDRES_OPT_READ = 0, //接收文件     _XCLOUDRES_OPT_WRITE,    //发送文件 };
返回值	成功返回 会话ID ，关闭时使用。 -1 err 已经关闭

12、关闭文件传输
接口原型	int CDK_CloseXCloudFile(unsigned int  nSID, unsigned short  nResType);
参数	nSID	CDK_OpenSessin 返回值
	nResType	参考  _XCLOUDSIDRES_TYPE
返回值	-1 err 已经关闭

13、打开局域网广播
接口原型	int  CDK_XBroadcastOpen(unsigned short  nRecePort, unsigned short nSndPort);
参数	nRecePort	APP 侧默认使用 3252  设备侧默认使用 3251
	nSndPort	APP 侧默认使用 3251 设备侧默认使用 3252
返回值	-1 err 初始化失败，检查端口是否已被占用
14、关闭局域网广播
接口原型	int  CDK_XBroadcastClose();
返回值	-1 关闭失败
15、发送局域网广播
接口原型	int CDK_XBroadcast(char *pBcastAddr, char *pBData,unsigned short nDataLen);
参数	pBcastAddr	广播地址，比如192.168.1.255 等有发送端网段的
	pBData	广播数据
	nDataLen	广播数据长度
返回值	-1 广播失败

消息回调
typedef  int (*XCLOUDMSGCALLBACK)( unsigned short nMsg,unsigned int hParam,unsigned int                                                                                                   lParam,char pString[],unsigned int nSize );
nMsg 参数说明		其他参数说明
XCLOUDMSG_XBROADCAST  110 收到局域网广播数据 *需要打开局域网广播接口*	hParam		0  //未使用
	lParam		0  //未使用
	pString		广播内容
	nSize		广播长度
XCLOUDMSG_LOGINFAIL  111 登录认证失败/连接掉线	hParam		LOGINSTATUS_CONERR = 0 //登录连接网络超时 LOGINSTATUS_UNKNOWERR=1, LOGINSTATUS_DBERR=2,      // DB 错误 LOGINSTATUS_PSSWDERR=3,   // 密码错误
	lParam		0  //未使用
	pString		NULL   //未使用
	nSize		0   //未使用
XCLOUDMSG_LOGINSUCCESS  112 登录成功	hParam		设备自身能力
	lParam		0:未使用
	pString		NULL  //未使用
	nSize		0     //未使用
XCLOUDMSG_MANOFFLINE 113 设备下线【状态改变】	hParam		0      //未使用
	lParam		0      //未使用
	pString		设备ID
	nSize		ID长度
XCLOUDMSG_MANONLINE 114 设备上线【状态改变】	hParam		0     //未使用
	lParam		0    //未使用
	pString		设备ID
	nSize		ID长度
XCLOUDMSG_SESSIONFAIL 115 会话失败	hParam		sessionid
	lParam		mediatype
	pString		enum SESSION_ERR {SR_Capacity_Err=1, //设备缺少相应能力值 SR_Open_Again, //重复打开同一个资源 SR_RecFile_Lock, //录像文件被其他用户锁定 SR_Hello_Timeout, //链路超时 SR_Internal_Err SR_NotFound = 404,};
	nSize		长度
XCLOUDMSG_SESSIONSUCCESS 116 会话成功	hParam		sessionid
	lParam		mediatype
	pString		{    "sessions_number" : 12       "p2p_mode":1 }//会话数
	nSize		pString  长度。
XCLOUDMSG_TRANSALT  119 透传	hParam		fromID
	lParam		0 //未使用
	pString		Transalt buf
	nSize		Transalt buflen
XCLOUDMSG_ALARM 120 报警消息	hParam		fromID
	lParam		Alarmtype
	pString		Data,time...
	nSize		Size
XCLOUDMSG_CONTROL 121 控制指令	hParam		fromID
	lParam		0  //未使用
	pString		NULL  //未使用
	nSize		0 //未使用
XCLOUDMSG_SESSION_WRITE_START  122 开始打开媒体资源，并可以CDK_SendMediaData	hParam		sessionid
	lParam		mediatype
	pString		NULL //未使用
	nSize		0 //未使用
XCLOUDMSG_SESSION_WRITE_STOP 123 关闭写资源	hParam		sessionid
	lParam		mediatype
	pString		NULL //未使用
	nSize		0 //未使用
XCLOUDMSG_SESSION_READ_START 124 开始接收对应的媒体数据	hParam		sessionid
	lParam		mediatype
	pString		NULL //未使用
	nSize		0 //未使用
XCLOUDMSG_SESSION_READ_STOP 125 停止接收对应的媒体数据	hParam		sessionid
	lParam		mediatype
	pString		NULL //未使用
	nSize		0//未使用
XCLOUDMSG_SUBSCRIBEFAIL 126 设备订阅失败	hParam		0 //未使用
	lParam		0 //未使用
	pString		{    "error_code" : 1,    "product_status" : true,    "product_uid" : "*" } 错误码对应 enum SUBSCRIBE_ERR { Subscribe_PWD_Err=1, //密码错误，可能原因是，订阅密码未用MD5加密 Subscribe_UID_Inactive //设备未激活，查找不到 };
	nSize		ID长度
XCLOUDMSG_SUBSCRIBESUCCESS 127 设备订阅成功	hParam		设备能力描述
	lParam		formID  //
	pString		设备ID，设备能力，设备状态 json格式 {    "product_capability" : ,    "product_id" : ,    "product_status" :,    "product_type" :,    "product_uid" : "",    "reset_times" : 4 }
	nSize		ID长度
XCLOUDMSG_TRANSALT_BIN 128 收到透传二进制格式内容	hParam		fromID
	hParam		0//未使用
	lParam		0 //未使用
	pString		二进制内容
	nSize		长度
XCLOUDMSG_TRANSALT_A 129 收到透文本数据	hParam		fromID
	hParam		0//未使用
	lParam		0 //未使用
	pString		文本内容
	nSize		长度
XCLOUDMSG_TRANSALT_COMA 130 串口透传文本数据	hParam		fromID
	hParam		0//未使用
	lParam		0 //未使用
	pString		文本内容
	nSize		长度
XCLOUDMSG_TRANSALT_COMB 131 串口透传二进制数据	hParam		fromID
	hParam		0//未使用
	lParam		0 //未使用
	pString		二进制数据
	nSize		长度

多媒体数据回调
typedef  void(*XCLOUDMEDIACALLBACK)( unsigned int nSID,unsigned short MediaType,unsigned short hParam,unsigned short lParam,char pBuf[],unsigned int nBuflen );
参数说明
nSID
MediaType
hParam
lParam
pBuf
nBuflen

结构体
typedef struct _XHOSTInfo {     unsigned short nPort;     unsigned short hProto;      char aryIP[255]; } XHOSTInfo;	NETTCPIP_UDP=11, NETTCPIP_TCPCLI = 12,
enum _XCLOUDRES_TYPE {          _XCLOUDRES_IM = 0,          _XCLOUDRES_PCMa = 10,          _XCLOUDRES_PCMu,          _XCLOUDRES_G711a,          _XCLOUDRES_G711u,          _XCLOUDRES_G726,          _XCLOUDRES_XAUDIO,          _XCLOUDRES_AAC,          _XCLOUDRES_H264_1 = 20,          _XCLOUDRES_H264_2,          _XCLOUDRES_H264_XVIDEO1,          _XCLOUDRES_H264_XVIDEO2,          _XCLOUDRES_H264_5,          _XCLOUDRES_H264_6,          _XCLOUDRES_H264_7,          _XCLOUDRES_H264_8,          _XCLOUDRES_H265_1,          _XCLOUDRES_H265_2,          _XCLOUDRES_H265_3,          _XCLOUDRES_MPEG4,          _XCLOUDRES_MJPEG,          _XCLOUDRES_FILE_1 = 50,          _XCLOUDRES_FILE_2,          _XCLOUDRES_FILE_3,          _XCLOUDRES_FILE_4,          _XCLOUDRES_FILE_5,          _XCLOUDRES_FILE_6,          _XCLOUDRES_FILE_7,          _XCLOUDRES_FILE_JPEG,          _XCLOUDRES_FILE_VODAUDIO,          _XCLOUDRES_FILE_VODVIDEO,          _XCLOUDRES_FILE_XDATA1,          _XCLOUDRES_FILE_XDATA2,          _XCLOUDRES_FILE_XDATA3,          _XCLOUDRES_FILE_XDATA4,            _XCLOUDRES_END, };	多媒体类型             _XCLOUDRES_XAUDIO _XCLOUDRES_H264_XVIDEO1 _XCLOUDRES_H264_XVIDEO2 _XCLOUDRES_FILE_XDATA1 _XCLOUDRES_FILE_XDATA2 _XCLOUDRES_FILE_XDATA3 _XCLOUDRES_FILE_XDATA4 加密通道
enum _XCLOUDMSG {     XCLOUDMSG_LOGINFAIL=111,     XCLOUDMSG_LOGINSUCCESS=112,     XCLOUDMSG_MANOFFLINE=113,     XCLOUDMSG_MANONLINE=114,     XCLOUDMSG_SESSIONFAIL=115,     XCLOUDMSG_SESSIONSUCCESS=116,     XCLOUDMSG_OPENSESSION=117,     XCLOUDMSG_CLOSESESSION=118,     XCLOUDMSG_TRANSALT=119,   //透传     XCLOUDMSG_ALARM=120,     XCLOUDMSG_CONTROL=121,     XCLOUDMSG_SESSION_WRITE_START=122,     XCLOUDMSG_SESSION_WRITE_STOP=123,     XCLOUDMSG_SESSION_READ_START=124,     XCLOUDMSG_SESSION_READ_STOP=125,          XCLOUDMSG_SUBSCRIBEFAIL=126,     XCLOUDMSG_SUBSCRIBESUCCESS=127,     XCLOUDMSG_TRANSALT_BIN=128,     XCLOUDMSG_TRANSALT_A=129,     XCLOUDMSG_TRANSALT_COMA = 130,     XCLOUDMSG_TRANSALT_COMB = 131,     XCLOUDMSG_MESSAGE_PUSH = 132,     XCLOUDMSG_MESSAGE_SYSTEM = 133,  };
enum _XCLOUDEFRM_TYPE {      XCLOUDEFRM_FRAMEI = 1,           XCLOUDEFRM_FRAMEP = 2,      XCLOUDEFRM_NORMAL = 3, };	针对视频 I 帧和 P 帧

六、

G1、视频会话流程图

G2、串口透传流程图：