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

版本

日期

说明

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 帧