更新记录

1.0.0（2021-08-25）

首次发布

平台兼容性

原生插件通用使用流程：

1. 购买插件，选择该插件绑定的项目。
2. 在HBuilderX里找到项目，在manifest的app原生插件配置中勾选模块，如需要填写参数则参考插件作者的文档添加。
3. 根据插件作者的提供的文档开发代码，在代码中引用插件，调用插件功能。
4. 打包自定义基座，选择插件，得到自定义基座，然后运行时选择自定义基座，进行log输出测试。
5. 开发完毕后正式云打包

付费原生插件目前不支持离线打包。
Android 离线打包原生插件另见文档 https://nativesupport.dcloud.net.cn/NativePlugin/offline_package/android
iOS 离线打包原生插件另见文档 https://nativesupport.dcloud.net.cn/NativePlugin/offline_package/ios

注意事项：使用HBuilderX2.7.14以下版本，如果同一插件且同一appid下购买并绑定了多个包名，提交云打包界面提示包名绑定不一致时，需要在HBuilderX项目中manifest.json->“App原生插件配置”->”云端插件“列表中删除该插件重新选择

安卓WiFi Direct原生插件

介绍

基于WiFi Direct标准实现无线网络中的设备无需通过无线路由器即可相互连接。支持WiFi Direct的功能包括：设备发现、服务注册与发现、一对一直连、一对多直连等。本插件封装了安卓android.net.wifi.p2p所有接口，对分散于各类的事件回调做统一的归整为一个监听回调方便应用处理事件。

限制

1. 只支持安卓。

使用场景

1. 在没有加入WiFi无线路由器网络的情况下实现设备的直接连接，手机与手机间自动互相发现建立连接，分享照片、音乐、视频、文件与交换信息等。
2. 零配置实现手机动态发现智能设备。不需要事先配置设备的信息，手机可动态发现同一服务类型的所有设备并选择需要的设备建立连接。

使用前注意事项

使用前需对WiFi Direct的功能及网络模型有基本的了解，WiFi Direct只负责发现设备与服务，并在两者之间建立WiFi的直连网络（可以是一对一或一对多），连接建立后怎么传输数据就跟WiFi Direct无关了。可以在WiFi Direct的网络连接上使用任何基于以太网的协议，如TCP、UDP或是应用层协议http, ftp, WebSocket等。 WiFi Direct网络是基于星形模型，连接建立之前首先建立一个群组，群里有一个群主，其他都是组员，组员都与群主连接。如果群里只有两个成员，其中一个是群主另一个是组员。群组没有建立之前设备可互相发现（可看到WiFi网络发射范围内支持WiFi Direct的设备），设备可发布提供的服务描述信息方便在建立连接之前选择设备进行连接。设备发现后可知道对方的设备地址(MAC地址）加上服务描述信息（如果对方有发布）。设备选定后发起连接，连接建立时会自动创建群组。群主可由系统自动指定或是先表明是否要成为群主。连接建立后双方都可知道自己是否为群主以及群主的IP地址。

使用方法

以下是基本用法，简单介绍插件的大概使用方法。实际应用要复杂许多。

1. 加载插件

// 加载WiFi Direct插件
// 插件名称为'zodiac-wfd'
const wfd = uni.requireNativePlugin('zodiac-wfd');
// 加载事件监听插件
const globalEvent = uni.requireNativePlugin('globalEvent');

2. 初始化

// 初始化插件，可在页面onLoad()中调用
wfd.init();

3. 注册事件监听回调

// 可在页面onLoad()中调用
// 'wfdStatusChange'为默认的事件名称
globalEvent.addEventListener('wfdStatusChange', (e) => {
    // 在此处理事件的相应逻辑
    // 参数e为事件的详细内容，格式请参考“事件格式”章节
    this.handleWfdStatusChange(e);
});

4. 寻找WiFi网络覆盖范围内的设备

// ret为1表示调用接口成功,0表示调用接口失败
// 注意：插件大部分接口都是异步的，调用接口的返回成功并不表示设备发现任务已经成功启动，
// 任务启动是成功或失败需要在事件监听回调里才知道
// 调用接口失败则不会收到任何事件通知了
const ret = wfd.discoverPeers();

5. 在事件监听回调处理寻找设备结果

// 处理所有WiFi Direct的事件
handleWfdStatusChange(e) {
    const status = e.status;
    if (status == 50) {
        // 设备发现任务已成功启动
    } else if (status == 51) {
        // 设备发现任务已经终止
    } else if (status == 52) {
        // 已发现设备，详细信息在e.data
        this.deviceList = e.data;
    } else if (status == 109) {
        // 设备发现任务启动失败
    }
}

6. 连接设备

// ret为1表示调用接口成功,0表示调用接口失败
// 注意：插件大部分接口都是异步的，调用接口的返回成功并不表示连接已经完成，
// 连接是否完成或失败需要在事件监听回调里才知道
// 调用接口失败则不会收到任何事件通知了
const ret = wfd.connect({
    // 设备地址，调用wfd.discoverPeers()后，在事件监听回调里获得的
    deviceAddress: this.deviceList[0].deviceAddress, 
    groupOwnerIntent: -1 // 表示是否想成为群主的意愿，-1为系统自动指定
});

7. 在事件监听回调处理连接结果

// 处理所有WiFi Direct的事件
handleWfdStatusChange(e) {
    const status = e.status;
    if (status == 61) {
        // 通知连接结果
        if (e.data.groupFormed) {
            // 群组已建立，连接成功
            // e.data.isGroupOwner => 是否为群主
            // e.data.ip => 群主IP地址
            // e.data.bindIp => 本机IP地址（本机IP地址安卓API没有提供，是插件提供的）
        }
        else {
            // 无法建立群组，连接失败
        }
    } else if (status == 111) {
        // 连接发生错误
    } 
}

8. 移除群组（断开所有连接）

// ret为1表示调用接口成功,0表示调用接口失败
// 注意：插件大部分接口都是异步的，调用接口的返回成功并不表示移除群组已经完成，
// 群组是否移除完成或失败需要在事件监听回调里才知道
// 调用接口失败则不会收到任何事件通知了
const ret = wfd.removeGroup();

9. 在事件监听回调处理移除群组结果

// 处理所有WiFi Direct的事件
handleWfdStatusChange(e) {
    const status = e.status;
    if (status == 21) {
        // 群组成功移除
        // 连接中断信息在status = 61里获得
    } else if (status == 108) {
        // 移除群组失败
    } 
}

10. 释放资源

// 当插件不再使用时调用
// 可在页面的onUnload()里调用
wfd.cleanUp();

方法

init

用途 初始化插件。可在页面onLoad()中调用。

限制及注意事项 需在调用插件其他方法之前调用。

输入值 无

返回值 数字类型，1表示初始化成功。0示初始化失败，此时不可再调用插件其他方法。

reset

用途 重置插件到初始化状态。释放所有资源，并重新创建。

限制及注意事项 init()方法在整个插件生命周期只能调用一次，reset可调用多次。

输入值 无

返回值 数字类型，1表示重置成功。0表示重置失败，此时不可再调用插件其他方法（除了cleanUp()方法）。

addServiceRequest

用途 增加服务搜索条件。调用成功后插件会根据搜索条件寻找符合条件的服务。

限制及注意事项

1. 调用此方法后并不会马上启动搜索，需要调用discoverServices()方法才会启动服务搜索。
2. 此方法是异步的，调用接口的返回成功并不表示增加服务搜索条件已经完成，搜索条件是否已经新增成功或失败需要在事件监听回调里才知道。调用接口失败则不会收到任何事件通知了。
3. 增加DNS-SD服务搜索条件时，如果只给serviceType没有给instanceName，只会收到status=82的事件（事件data为dnsSdService对象）。如果要收到status=81的事件（事件data为dnsSdTxtRecord对象），则instanceName必需给值。

输入值 要增加的服务发现搜索条件描述，Object类型，格式如下：

{
    serviceDiscoveryType: 1,
    instanceName: 'myInstance', //DNS-SD服务属性
    serviceType: '_http._tcp', //DNS-SD服务属性
    st: 'upnp:rootdevice' //UPnP服务属性
}

如果所有属性都不赋值需要传入空Object {}。如下示例：

// 发现所有默认服务发现类型(DNS-SD)的服务
wfd.addServiceRequest({});

返回值 数字类型，0表示调用失败。1表示调用成功。

相关事件

removeServiceRequest

用途 移除一个服务发现的搜索条件。

限制及注意事项

1. 此方法是异步的，调用接口的返回成功并不表示搜索条件已经移除完成，搜索条件是否已经移除成功或失败需要在事件监听回调里才知道。调用接口失败则不会收到任何事件通知了。

输入值 要移除的服务发现搜索条件描述，Object类型，格式与addServiceRequest()方法一样。调用addServiceRequest()传入什么值，这里就传入同样的值移除对应的搜索条件。

返回值 数字类型，0表示调用失败。1表示调用成功。

相关事件

clearServiceRequests

用途 移除所有已经加入的服务发现搜索条件。

限制及注意事项

1. 此方法是异步的，调用接口的返回成功并不表示搜索条件已经移除完成，搜索条件是否已经移除成功或失败需要在事件监听回调里才知道。调用接口失败则不会收到任何事件通知了。

输入值 无。

返回值 数字类型，0表示调用失败。1表示调用成功。

相关事件

discoverServices

用途 根据已经加入的服务发现搜索条件寻找服务。服务发现搜索条件是调用addServiceRequest()方法加入的。

限制及注意事项

1. 此方法是异步的，调用接口的返回成功并不表示寻找服务已经开始，寻找服务是否已经开始或失败需要在事件监听回调里才知道。调用接口失败则不会收到任何事件通知了。

输入值 无

返回值 数字类型，0表示调用失败。1表示调用成功。

相关事件

discoverPeers

用途 寻找WiFi网络覆盖范围内支持WiFi Direct的设备。

限制及注意事项

1. 此方法是异步的，调用接口的返回成功并不表示寻找设备已经开始，寻找设备是否已经开始或失败需要在事件监听回调里才知道。调用接口失败则不会收到任何事件通知了。

输入值 无

返回值 数字类型，0表示调用失败。1表示调用成功。

相关事件

stopPeerDiscovery

用途 停止寻找设备。

限制及注意事项

1. 此方法是异步的，调用接口的返回成功并不表示停止寻找设备已经成功停止，停止寻找设备是否已经成功或失败需要在事件监听回调里才知道。调用接口失败则不会收到任何事件通知了。

输入值 无

返回值 数字类型，0表示调用失败。1表示调用成功。

相关事件

requestPeers

用途 请求目前已经发现的设备清单。

限制及注意事项

1. 此方法是异步的，调用接口返回成功只表示已经开始请求设备清单，设备清单会在事件监听回调里返回。调用接口失败则不会收到任何事件通知了。

输入值 无

返回值 数字类型，0表示调用失败。1表示调用成功。

相关事件

connect

用途 连接设备，建立网络连接。如果发起连接的设备当前没有加入群组，则connect()会与被连接的设备协调建立群组。如果发起连接的设备已经建立了群组或是已经加入了群组，connect()会邀请被连接的设备加入群组。

限制及注意事项

1. 此方法是异步的，调用接口的返回成功并不表示设备已连接成功，设备是否已经连接成功或失败需要在事件监听回调里才知道。调用接口失败则不会收到任何事件通知了。
2. 安卓10.0（不含）以下版本只支持输入值属性deviceAddress、groupOwnerIntent、wps等基本属性，如果使用了基本属性以外的属性则忽略，deviceAddress必需赋值。安卓10.0或以上版本可使用全部属性。
3. 安卓10.0或以上版本也可以只使用基本属性，此时passphrase属性不能赋值（不要出现passphrase属性），deviceAddress必需赋值。
4. 安卓10.0或以上版本如果要使用基本属性以外的属性，passphrase及networkName必需赋值且不能为空字符串。

输入值 Object类型，格式如下：

{
    deviceAddress: '00-E9-3A-A9-06-09',
    groupOwnerIntent: -1,
    wps: {
        BSSID: '00-E9-3A-A9-06-09',
        pin: '12345',
        setup: 0
    },
    persistent: false,
    band: 0,
    frequency: 2400,
    networkName: 'DIRECT-xY-XXX',
    passphrase: 'xxx'
}

返回值 数字类型，0表示调用失败。1表示调用成功。

相关事件

cancelConnet

用途 取消连接设备。

限制及注意事项

1. 此方法是异步的，调用接口的返回成功并不表示连接已经成功取消，取消连接设备是否已经成功或失败需要在事件监听回调里才知道。调用接口失败则不会收到任何事件通知了。
2. 只有在调用connect()分法还没完成前(还没返回status=61或status=111的事件)生效。如果连接已经建立或连接失败，则无法取消连接。

输入值 无

返回值 数字类型，0表示调用失败。1表示调用成功。

相关事件

requestConnectionInfo

用途 请求目前的连接信息。

限制及注意事项

1. 此方法是异步的，调用接口返回成功只表示已经开始请求连接信息，连接信息会在事件监听回调里返回。调用接口失败则不会收到任何事件通知了。

输入值 无

返回值 数字类型，0表示调用失败。1表示调用成功。

相关事件

requestDeviceInfo

用途 请求本机设备信息。

限制及注意事项

1. 此方法是异步的，调用接口返回成功只表示已经开始请求本机设备信息，本机设备信息会在事件监听回调里返回。调用接口失败则不会收到任何事件通知了。
2. 需要安卓10.0或以上版本才有效，否则调用时返回0（调用失败）。

输入值 无

返回值 数字类型，0表示调用失败。1表示调用成功。

相关事件

requestP2pState

用途 请求目前的WiFi Direct状态(是否可用)。

限制及注意事项

1. 此方法是异步的，调用接口返回成功只表示已经开始请求WiFi Direct状态，WiFi Direct状态会在事件监听回调里返回。调用接口失败则不会收到任何事件通知了。
2. 需要安卓10.0或以上版本才有效，否则调用时返回0（调用失败）。

输入值 无

返回值 数字类型，0表示调用失败。1表示调用成功。

相关事件

addLocalService

用途 注册服务。服务注册成功后则可以被发现。

限制及注意事项

1. 此方法是异步的，调用接口的返回成功并不表示服务已经成功注册，服务是否已经成功注册或失败需要在事件监听回调里才知道。调用接口失败则不会收到任何事件通知了。

输入值 要注册的服务描述，Object类型，格式如下：

{
    serviceDiscoveryType: 1,
    instanceName: 'myInstance', //DNS-SD服务属性
    serviceType: '_http._tcp', //DNS-SD服务属性
    txtRecordMap: { //DNS-SD服务属性
        key1: 'value1',
        key2: 'value2'
    },
    uuid: '6859dede-8574-59ab-9332-123456789012', //UPnP服务属性
    device: 'urn:schemas-upnp-org:device:MediaServer:1', //UPnP服务属性
    services: ['urn:schemas-upnp-org:service:ContentDirectory:1'] //UPnP服务属性
}

返回值 数字类型，0表示调用失败。1表示调用成功。

相关事件

removeLocalService

用途 移除已注册的服务。服务注册移除成功后则不会被发现。

限制及注意事项

1. 此方法是异步的，调用接口的返回成功并不表示服务注册已经成功移除，服务注册是否已经成功移除或失败需要在事件监听回调里才知道。调用接口失败则不会收到任何事件通知了。

输入值 要移除注册的服务描述，Object类型，格式同addLocalService()方法。

返回值 数字类型，0表示调用失败。1表示调用成功。

相关事件

clearLocalServices

用途 移除所有已注册的服务。服务注册移除成功后则不会被发现。

限制及注意事项

1. 此方法是异步的，调用接口的返回成功并不表示服务注册已经成功移除，服务注册是否已经成功移除或失败需要在事件监听回调里才知道。调用接口失败则不会收到任何事件通知了。

输入值 无。

返回值 数字类型，0表示调用失败。1表示调用成功。

相关事件

createGroup

用途 创建群组。如果要保证本机在建立连接后是群主身份，则需先创建群组，由其他设备连接本机。群组创建后会建立一个WiFi热点让没有WiFi Direct支持的设备也可以接入。

限制及注意事项

1. 此方法是异步的，调用接口的返回成功并不表示群组已经创建成功，群组是否已经创建成功或失败需要在事件监听回调里才知道。调用接口失败则不会收到任何事件通知了。
2. 如果输入值不是空对象{}需要安卓10.0或以上版本才有效。安卓10.0以下版本，如果输入值不是空对象{}，则忽略输入值属性，用默认参数创建群组。
3. 此方法一般不使用，除非想保证本机在群组中是群主身份，让其他设备加入此群组，或是建立一个WiFi热点让没有WiFi Direct支持的设备也可以接入。

输入值 要创建群组的描述，Object类型，格式如下：

{
    persistent: false,
    band: 0,
    frequency: 2400,
    networkName: 'DIRECT-xY-XXX',
    passphrase: 'xxx'
}

如果所有属性都不赋值需要传入空Object {}。如下示例：

// 用默认参数创建群组
wfd.createGroup({});

返回值 数字类型，0表示调用失败。1表示调用成功。

相关事件

removeGroup

用途 移除群组。移除群组后，所有此群组内的连接将中断。

限制及注意事项

1. 此方法是异步的，调用接口的返回成功并不表示群组已经成功移除，群组是否已经成功移除或失败需要在事件监听回调里才知道。调用接口失败则不会收到任何事件通知了。

输入值 无。

返回值 数字类型，0表示调用失败。1表示调用成功。

相关事件

requestGroupInfo

用途 请求群组信息。

限制及注意事项

1. 此方法是异步的，调用接口返回成功只表示已经开始请求群组信息，群组信息会在事件监听回调里返回。调用接口失败则不会收到任何事件通知了。

输入值 无。

返回值 数字类型，0表示调用失败。1表示调用成功。

相关事件

getEventName

用途 获取插件发布事件时的事件名称。默认值为'wfdStatusChange'。

限制 无

输入值 无

返回值 字符串类型的事件名称。

setEventName

用途 设定插件发布事件时的事件名称。默认值为'wfdStatusChange'。调用此方法后插件发布事件的事件名称将会更改，一般在调用globalEvent.addEventListener()方法之前调用setEventName()。

一般情况不需要变更事件名称，除非默认的事件名称与其他插件所用的事件名称冲突。

限制 setEventName()方法一般在调用init()方法之后及调用globalEvent.addEventListener()方法之前调用，如下例：

// 可在页面onLoad()中调用
// 初始化插件
wfd.init();
// 变更事件名称
wfd.setEventName('myEventName');
// 注册事件监听回调，监听事件名称为'myEventName'的事件
globalEvent.addEventListener('myEventName', (e) => {
    // 在此处理事件的相应逻辑
    // 参数e为事件的详细内容，格式请参考“事件格式”章节
});

输入值 字符串类型的事件名称。

返回值 无

cleanUp

用途 释放插件占用资源。可在页面的onUnload()里调用。

限制 当不再使用插件时必需调用。

输入值 无

返回值 无

事件格式

在注册事件监听回调时，如下例：

globalEvent.addEventListener('wfdStatusChange', (e) => {
    // 在此处理事件的相应逻辑
    // 参数e为事件的详细内容
});

第一个参数'wfdStatusChange'为事件名称，第二个参数为回调函数，回调函数入参e格式为：

{
    status: 1,
    eventType: 'info',
    data: {},
    reason: 1
}

groupInfo对象

device对象

connectionInfo对象

upnpService对象

dnsSdTxtRecord对象

dnsSdService对象

DNS-SD服务

DNS-SD全名为DNS Service Discovery，是一种利用标准DNS协议(包括程序界面、服务器、网络封包格式)来寻找网络上服务的方法。RFC 6763对DNS-SD有完整的描述。DNS-SD兼容mDNS，但不依赖mDNS。本插件支持DNS-SD服务的注册与发现，注册DNS-SD服务的信息包括实例名称（instanceName），服务类型（serviceType）及TXT Record。注册服务时需指定instanceName及serviceType，TXT Record为可选。

实例名称（instanceName）

instanceName为服务的显示名称，instanceName除了不能包含ASCII的控制字符（0x00-0x1F及0x7F）没有其他限制，instanceName可以包含unicode字符。instanceName是以UTF-8编码存储，存储的总长度限制为63bytes，每个UTF-8编码需要1-4byte空间，因此最差情况能容纳15个unicode字符。

服务类型（serviceType）

服务类型可理解为设备提供服务所使用的网络协议，例如www服务使用基于tcp的http网络协议，服务类型为'_http._tcp'。已注册的服务类型可参考Service Name and Transport Protocol Port Number Registry。服务类型的格式为：

_<Service Name>._<Transport Protocol>

<Service Name>及<Transport Protocol>可在上述的已注册的服务类型网页里查找。

TXT Record

TXT Record用来描述服务的详细信息，以名值对（key/value）的方式呈现。 key必需是可打印的US-ASCII字符（0x20-0x7E不包括等号"="），长度最少是1个字符最多是9个字符。key是大小写无关（大写小写视为相同）。key在TXT Record中不能重复。 value的值没有什么限制，可包含任何unicode字符。value的长度不能超过245 bytes。 TXT Record由多个名值对组成，所有名值对加起来的总长度一般在200 bytes以下（所有key+value的byte数），最多不要超过500 bytes。 按RFC 6763的建议，名值对要包含版本标签并且放在TXT Record的第一个名值对。版本标签key为"txtvers"，value为从1开始的整数往上递增，如1，2，3等。

UPnP服务

UPnP全名为Universal Plug and Play，主要的目的让设备可以零配置的连接网络并被自动发现，包括设备可以动态加入网络、获取设备IP地址、发布设备名称及规格参数等。本插件支持UpnP服务的注册与发现，注册UpnP服务的信息包括uuid、device及services。

uuid

符合RFC 4122所规范的唯一标识。

device

device为一字符串表示注册服务的设备，device的格式请参考UPnP™ Device Architecture 1.1。

services

services为一数组包含要注册的service，service为一字符串表示要注册的服务，service的格式请参考UPnP™ Device Architecture 1.1。

其他注意事项

1. 在发现DNS-SD服务时会返回两种事件，事件status=81，data为dnsSdTxtRecord对象及事件status=81，data为dnsSdService对象。dnsSdTxtRecord对象包含自定义的服务属性，dnsSdService对象包含instanceName及registrationType（serviceType + ".local."）。如果按照DNS-SD规范中规定，服务的IP地址及端口应该存放在DNS的SRV记录，应该是放在dnsSdService对象中返回，但是调用addLocalService()方法时并没法给IP地址及端口，这是因为WiFi Direct是在设备加入群组建立连接之后才会获得IP地址，因此没法在注册服务时就同时注册IP地址及端口。为了发布服务的IP地址及端口，只能在设备加入群组建立连接之后调用removeLocalService()方法将之前注册的服务移除，重新注册服务，将IP地址及端口放在TXT Record中。
2. 本插件暂不支持设定及查询WiFi Display信息。