中文简体    English

IvyIoT P2P SDK编程指南

1. 概述

  P2P SDK是由IvyIoT为第三方厂商的智能硬件设备和手机APP提供的软件开发包，用户通过在设备固件和手机APP中嵌入P2P SDK，可以方便的将硬件设备和手机APP接入IvyIoT云服务，支持APP和硬件设备之间快速建立P2P连接，最终实现APP和硬件设备之间的实时音视频数据传输。

P2P SDK以库文件的形式对外提供，整个SDK文件夹结构如下：
doc文件夹：存放和P2P SDK相关的文档，如接口说明文档、demo程序使用文档。
include文件夹：存放P2P SDK对外提供的头文件。
lib文件夹：存放P2P SDK对外提供的库文件。（基于不同硬件平台和系统环境）
sample文件夹：存放demo程序。（基于不同硬件平台和系统环境）

2. P2P SDK整体应用架构

  为了将P2P SDK嵌入到APP和设备固件，首先需要了解P2P SDK的整体应用架构。如下图所示，P2P SDK在运行的时候，内部存在两种工作模式：被动模式和主动模式。对于硬件设备的固件端，应该以被动模式运行P2P SDK；对于APP端，应该以主动模式运行P2P SDK。

  两端正常工作时，通过APP触发，两端P2P SDK之间会建立一条P2P传输通道。此时APP端的P2P SDK将工作在本地server模式，设备端P2P SDK将工作在本地client模式 如下图所示。

  为了实现APP和硬件设备之间的数据传输，设备固件必须以server方式工作。P2P连接建立成功后，设备端P2P_SDK以client方式通过socket连接到固件server。同理，APP必须以client方式工作，P2P连接建立成功后，APP以client方式通过socket连接本端P2P SDK内部的本地server。最终，P2P SDK是以一种传输代理的方式实现了APP和硬件设备之间的P2P数据传输。

3. P2P SDK接口调用的整体流程

  如上图所示，P2P SDK的很多调用接口都涉及到网络通信，为了保证执行效率，简化应用层软件设计的复杂度，这些接口函数都被设计为非阻塞模式，函数的执行结果总是以回调函数的形式异步通知到上层应用程序，这些回调函数的类型在P2P SDK的头文件中定义，具体的实现需要由用户应用程序完成并通过相关接口注册到P2P SDK内部。
  下面将以P2P SDK的C函数接口为例说明SDK接口的调用逻辑。对于Andriod平台，以JNI形式封装SDK接口，具体的接口说明可参考IvyP2PDemo程序中的P2PClient.class文件，以及本文的最后部分。

4. P2P SDK关键数据类型

5. 设备端函数接口详细说明

5.1 SDK初始化

5.2 查询空闲的P2P服务器

5.3 >P2P服务器查询结果回调函数

5.4 释放dispatcher对象

5.5 连接P2P服务器

5.6 P2P服务器连接结果回调函数

5.7 P2P服务器连接中断回调函数

5.8 主动断开与P2P服务器的连接

5.9 收到远端P2P连接请求的回调函数

5.10 SDK反初始化

6. APP端函数接口详细说明

6.1 SDK初始化（与设备端一致）

6.2 查询目标设备所属的P2P服务器

6.3 P2P服务器查询结果回调函数（与设备端一致）

6.4 释放dispatcher对象（与设备端一致）

6.5 连接P2P服务器（与设备端一致）

6.6 P2P服务器连接结果回调函数（与设备端一致）

6.7 P2P服务器连接中断回调函数（与设备端一致）

6.8 主动断开与P2P服务器的连接（与设备端一致）

6.9 向设备端发起P2P连接请求

6.10 P2P连接结果回调函数

6.11 P2P连接中断回调函数

6.12 主动断开指定的P2P连接

6.13 创建本地代理服务

6.14 销毁本地代理服务

6.15 SDK反初始化（与设备端一致）

7 Andriod平台接口详细说明

针对Andriod平台，P2P SDK采用JNI方式封装成java接口类，具体接口如下:

public class P2PClient {
    public P2PClient() {
    }

    public static native int init(); // SDK初始化
    public static native void uninit(); // SDK反初始化

    // 函数功能：连接P2P服务器
    // 返回值：P2PResult.result=0表示函数执行成功，否则表示失败
    //        P2PResult.value返回一个int类型的p2p_transport对象
    private static native P2PResult p2p_transport_create(
                        String server, // P2P服务器地址或域名
                        int port, // P2P服务器端口号
                        String user, // 设备UID，APP侧忽略
                        String password, // 设备KEY，APP侧忽略
                        int terminal_type, // APP侧固定为1
                        // 设备侧固定为0
                        int user_data, // 用户数据，缺省为0
                        int use_tcp_connect_srv, //忽略，缺省为0
                        String proxy_addr, // APP侧忽略，缺省为0
                                            // 设备侧需要指定固件SERVER的地址，例如“127.0.0.1:端口号”
                        Object cb); // 实现了回调函数的类对象

    // 连接P2P服务器，与上面的函数一致，二选一
    public static P2PResult p2p_transport_create(p2p_transport_cfg cfg) {
            return p2p_transport_create(cfg.server, cfg.port, cfg.user,
                            cfg.password, cfg.terminal_type, cfg.user_data,
                            cfg.use_tcp_connect_srv, cfg.proxy_addr, cfg.cb);
    }

    // 主动断开与P2P服务器的连接，释放p2p_transport对象
    public static native void p2p_transport_destroy(int transport);

    // 函数功能：APP调用此接口向设备端发送P2P连接请求
    // 返回值：P2PResult.result=0表示函数执行成功，否则表示失败
    //        P2PResult.value:返回一个P2P连接ID，本地唯一
    public static native P2PResult p2p_transport_connect(
                                    int transport, // p2p_transport对象
                                    String user, // 目标IPC设备的UID
                                    int user_data); // 用户数据，缺省为0

    // APP调用此接口，断开指定的P2P连接
    public static native void p2p_transport_disconnect(int transport, int conn_id);

    // 函数功能：APP侧调用此接口，通知SDK内部创建一个代理服务对象
    // 参数说明：int transport：p2p_transport对象
    //          int conn_id：每个内部代理服务关联一条P2P连接ID
    //          int remote_listen_port：用户可以指定代理服务的工作端口（缺省输入0）
    // 返回值：P2PResult.result=0表示函数执行成功，否则表示失败
    //        P2PResult.value:返回内部代理服务的实际工作端口
    public static native P2PResult p2p_create_tcp_proxy(int transport, 
                                        int conn_id, int remote_listen_port);

    // 释放P2P SDK内部的代理服务对象
    public static native void p2p_destroy_tcp_proxy(int transport, 
                                        int conn_id, int local_proxy_port);

    // 一般不使用此接口
    public static native String p2p_strerror(int error);

    // 一般不使用此接口
    public static native int p2p_nat_type_detect(String server, 
                                int port,P2PClient.P2PDetectNatCallBack cb);

    public static native String p2p_get_conn_remote_addr(int transport, int conn_id);

    public static native String p2p_get_conn_local_addr(int transport, int conn_id);

    //  函数功能：设备侧调用此接口，查询一个空闲的P2P服务器
    //            查询得到的服务器信息以回调函数的方式返回。
    //  参数说明：String user：IPC设备的UID
    //            String password：IPC设备的KEY
    //            String ds_addr：IvyIoT云服务器地址或域名字符串
    //            int user_data：用户数据，缺省为0
    //            P2PClient.P2PClientDispatchCallBack cb：处理查询结果的回调函数
    // 返回值：0表示成功，其它表示失败
    public static native int p2p_request_dispatch_server(
                                                    String user,
                                                    String password,
                                                    String ds_addr,
                                                    int user_data,
                            P2PClient.P2PClientDispatchCallBack cb);

    //  函数功能：APP调用此接口，查询一个目标设备当前正在连接的P2P服务器
    //            查询得到的服务器信息以回调函数的方式返回。
    //  参数说明：String dest_user：目标设备的UID
    //            String ds_addr：IvyIoT云服务器地址或域名字符串
    //            int user_data：用户数据，缺省为0
    //            P2PClient.P2PClientDispatchCallBack cb：处理查询结果的回调函数
    // 返回值：0表示成功，其它表示失败 
    public static native int p2p_query_dispatch_server(
                                                String dest_user,
                                                String ds_addr,
                                                int user_data,
                            P2PClient.P2PClientDispatchCallBack cb);

    public static native int p2p_conn_set_buf_size(int transport, int conn_id, int opt, int size);

    // 回调函数接口
    public interface P2PClientCallBack {
        // 函数功能：此回调函数用于处理p2p_transport_create发起的P2P服务器连接结果
        // 参数说明：int transport：调用p2p_transport_create时，生成的p2p_transportd对象
        //           int status：0：表示连接P2P服务器成功，其它表示失败
        //           int user_data：调用p2p_transport_create时输入的用户数据
        void on_create_complete(int transport, int status, int user_data);

        // 函数功能：此回调函数用于处理p2p_transport_connect发起的P2P连接结果
        // 参数说明： int transport：调用p2p_transport_create时，生成的p2p_transportd对象
        //            int connection_id：调用p2p_transport_connect生成的P2P连接ID
        //            int status：0：表示P2P连接成功，其它表示失败
        //            int transport_user_data：调用p2p_transport_create时输入的用户数据
        //            int connect_user_data：调用p2p_transport_connect时输入的用户数据
        void on_connect_complete(int transport,
                                int connection_id,
                                int status,
                                int transport_user_data,
                                int connect_user_data);

        // 函数功能：APP与IPC之间的P2P连接断开时，此回调函数被调用
        // 参数说明：int transport：调用p2p_transport_create生成的p2p_transportd对象
        //           int connection_id：调用p2p_transport_connect生成的P2P连接ID
        //           int transport_user_data：调用p2p_transport_create时输入的用户数据
        //           int connect_user_data：调用p2p_transport_connect时输入的用户数据
        void on_connection_disconnect(int transport,
                                    int connection_id,
                                    int transport_user_data,
                                    int connect_user_data);

        // 函数功能：此回调函数只在IPC侧被调用，表示IPC侧成功建立一条新的P2P连接
        // 参数说明：int transport：调用p2p_transport_create生成的p2p_transportd对象
        //           int connection_id：P2P连接ID，本地唯一，标识一条P2P连接
        //           int transport_user_data：调用p2p_transport_create时输入的用户数据
        void on_accept_remote_connection(int transport,
                                        int connection_id,
                                        int transport_user_data);
    }

    public interface P2PClientDispatchCallBack {
        // 此回调函数作为p2p_request_dispatch_server()和p2p_query_dispatch_server()
        // 的输入参数，当上述函数发送的查询请求得到响应时，P2PSDK调用此回调函数将
        // 查询结果通知到应用层
        void on_dispatch_result(int status,
                                int user_data,
                                String server,
                                int port,
                                int server_id);
    }

    // 此接口已不使用
    public interface P2PDetectNatCallBack {
        void on_detect_nat(int status, int nat_type);
    }
}