MCBluetooth

startAdvertising stopAdvertising disconnect getCurrentPeers sendString sendFile startBrowsing invitePeer stopBrowsing

概述

背景

在iOS7中，引入了一个全新的框架——Multipeer Connectivity（多点连接）。利用Multipeer Connectivity框架，即使在没有连接到WiFi（WLAN）或移动网络（xG）的情况下，距离较近的Apple设备（iMac/iPad/iPhone）之间可基于蓝牙和WiFi（P2P WiFi）技术进行发现和连接实现近场通信。

Multipeer Connectivity扩充的功能与利用AirDrop传输文件非常类似，可以将其看作AirDrop不能直接使用的补偿，代价是需要自己实现。手机不联网也能跟附近的人聊得火热的FireChat和See You Around等近场聊天App、近距离无网遥控交互拍照神器拍咯App就是基于Multipeer Connectivity框架实现。

相比AirDrop，Multipeer Connectivity在进行发现和会话时并不要求同时打开WiFi和蓝牙，也不像AirDrop那样强制打开这两个开关，而是根据条件适时选择使用蓝牙或（和）WiFi。 本段介绍引自 MultipeerConnectivity.framework框架

了解

本插件封装了 iOS 端 Multipeer Connectivity 框架的相关接口。 Multipeer Connectivity Framework是iOS 7 推出的众多新框架的一种，是一个使附近设备通过Wi-Fi网络、P2P Wi-Fi以及蓝牙个人局域网进行通信的框架。它拓宽了操作系统中应用的范围。其目的是使开发者可以创建通过Wi-Fi或蓝牙在近距离建立连接的应用。是在近距离设备间建立互动，交换数据和其他资源的很好的简单工具。

原理

其中通讯的原理，是利用节点来进行广播服务（标示符），其他节点可以通过服务（标示符）发现广播。并对此节点进行连接。在项目中可以将广播和发现放在一起实现，这样既可以发现并连接到其他节点，同时也可以被其他节点所搜索链接。服务的命名规则为由ASCII字母、数字和“-”组成的短文本串，最多15个字符。通常，一个服务的名字应该由应用程序的名字开始，后边跟“-”和一个独特的描述符号。

MCBluetooth 插件封装了 iOS 端系统的蓝牙功能，使用此插件可实现两台 iOS 设备间无缝传输数据。可传输字符串、图片、视频、文件等各种数据。使用此插件需打开设备蓝牙或Wi-Fi功能。

配置 Info.plist

使用本插件需在云编译时申请访问本地网络权限。且需要配置 Info.plist 文件。有关 Info.plist 文件的说明参考论坛。

本功能配置示例如下：

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict> 
    <key>NSBonjourServices</key>
    <array>
        <string>_serviceType._tcp</string> 
    </array>
</dict>
</plist>

注意：其中的 serviceType 是 startAdvertising 接口中 serviceType 参数配置的对应的值。

注意：

只能用于 iOS 设备且为同一个应用程序之间的连接。适合发送较小的数据。对其它蓝牙设备的连接请使用插件 ble。 startAdvertising、stopAdvertising、getCurrentPeers 为服务器端接口，disconnect、sendString、sendFile 为公共接口，startBrowsing、invitePeer、stopBrowsing 为客户端接口。

startAdvertising

开始广播

startAdvertising({params}, callback(ret))

params

serviceType：

  • 类型：字符串
  • 描述：服务的类型标示符，是由ASCII字母组成的短文本串，最多15个字符。

callback(ret, err)

ret：

  • 类型：JSON 对象
  • 内部字段：
{
    eventType:	 //字符串类型；交互事件类型；取值范围：
                  //receiveInvitation：收到连接邀请
                  //error：发生错误
                  //connected：建立链接
                  //connecting：正在建立连接
                  //notConnected：断开
    peerName:     //字符串类型；设备名称，当 error 时无此值
    errorMsg:     //字符串类型；错误信息，仅当 error 有值
}

示例代码

var MCBluetooth = api.require('MCBluetooth');
MCBluetooth.startAdvertising({
    serviceType: 'nearByContent',
}, function(ret) {
    if (ret) {
        api.alert({msg:JSON.stringify(ret)});
    } 
});

可用性

iOS系统

可提供的 1.0.0 及更高版本

stopAdvertising

停止广播

stopAdvertising()

示例代码

var MCBluetooth = api.require('MCBluetooth');
MCBluetooth.stopAdvertising();

可用性

iOS系统

可提供的 1.0.0 及更高版本

disconnect

断开链接

disconnect()

示例代码

var MCBluetooth = api.require('MCBluetooth');
MCBluetooth.disconnect();

可用性

iOS系统

可提供的 1.0.0 及更高版本

getCurrentPeers

获取当前连接的设备列表

getCurrentPeers(callback(ret))

callback(ret, err)

ret：

  • 类型：JSON 对象
  • 内部字段：
{ 
    allPeers:     //数组类型；当前找到的新设备名 
}

示例代码

var MCBluetooth = api.require('MCBluetooth');
MCBluetooth.getCurrentPeers(function(ret) {
    if (ret) {
        api.alert({msg:JSON.stringify(ret)});
    } 
});

可用性

iOS系统

可提供的 1.0.0 及更高版本

sendString

发送字符串

sendString({params},callback(ret))

params

data：

  • 类型：字符串
  • 描述：发送的字符串

toPeers：

  • 类型：数组
  • 描述：（可选项）要发送给的设备在连接列表里的索引组成的数组
  • 默认：给当前已连接设备全部发送

callback(ret, err)

ret：

  • 类型：JSON 对象
  • 内部字段：
{
    status:	    //布尔类型；是否发送成功 
    errorMsg:     //字符串类型；错误信息 
}

示例代码

var MCBluetooth = api.require('MCBluetooth');
MCBluetooth.sendString({
    data:"send from yy",
    //toPeers
},function(ret) {
    if (ret) {
        api.alert({msg:JSON.stringify(ret)});
    } 
});

可用性

iOS系统

可提供的 1.0.0 及更高版本

sendFile

发送文件

sendFile({params},callback(ret))

params

path：

  • 类型：字符串
  • 描述：发送的文件路径

resourceName：

  • 类型：字符串
  • 描述：资源名称

toPeerIndex：

  • 类型：数字
  • 描述：（可选项）要发送给的设备在连接列表里的索引
  • 默认：0

callback(ret, err)

ret：

  • 类型：JSON 对象
  • 内部字段：
{
    status:	    //布尔类型；是否发送成功 
    errorMsg:     //字符串类型；错误信息 
}

示例代码

var MCBluetooth = api.require('MCBluetooth');
MCBluetooth.sendFile({
    path:'widget://res/1.png',
    toPeerIndex:0
},function(ret) {
    if (ret) {
        api.alert({msg:JSON.stringify(ret)});
    } 
});

可用性

iOS系统

可提供的 1.0.0 及更高版本

addReceiveDataListener

添加收到字符串监听

addReceiveDataListener(callback(ret))

callback(ret, err)

ret：

  • 类型：JSON 对象
  • 内部字段：
{ 
    data:     //字符串类型；收到的字符串
    peerName: //字符串类型；发送字符串的设备名称
    index:    //数字类型；设备在列表中的下标
}

示例代码

var MCBluetooth = api.require('MCBluetooth');
MCBluetooth.addReceiveDataListener(function(ret) {
    if (ret) {
        api.alert({msg:JSON.stringify(ret)});
    } 
});

可用性

iOS 系统

可提供的 1.0.0 及更高版本

addReceiveFileListener

添加收到文件监听

addReceiveFileListener(callback(ret))

callback(ret, err)

ret：

  • 类型：JSON 对象
  • 内部字段：
{ 
    path:         //字符串类型；收到的文件路径
    peerName:     //字符串类型；发送字符串的设备名称
    resourceName: //字符串类型；收到的文件名称
    index:        //数字类型；设备在列表中的下标
}

示例代码

var MCBluetooth = api.require('MCBluetooth');
MCBluetooth.addReceiveFileListener(function(ret) {
    if (ret) {
        api.alert({msg:JSON.stringify(ret)});
    } 
});

可用性

iOS 系统

可提供的 1.0.0 及更高版本

startBrowsing

开始扫描附近的设备

startBrowsing({params},callback(ret))

params

serviceType：

  • 类型：字符串
  • 描述：服务的类型标示符，是由ASCII字母组成的短文本串，最多15个字符。

callback(ret)

ret：

  • 类型：JSON 对象
  • 内部字段：
{
    eventType:	 //字符串类型；交互事件类型；取值范围：
                  //foundPeer：找到新设备
                  //lostPeer：丢失设备
                  //error：发生错误
    allPeers:     //数组类型；当前找到的新设备名，仅当 foundPeer、lostPeer 有值
    errorMsg:     //字符串类型；错误信息，仅当 error 有值
}

示例代码

var MCBluetooth = api.require('MCBluetooth');
MCBluetooth.startBrowsing(function(ret) {
    if (ret) {
        api.alert({msg:JSON.stringify(ret)});
    } 
});

可用性

iOS系统

可提供的 1.0.0 及更高版本

stopBrowsing

停止扫描

stopBrowsing()

示例代码

var MCBluetooth = api.require('MCBluetooth');
MCBluetooth.stopBrowsing();

可用性

iOS系统

可提供的 1.0.0 及更高版本

invitePeer

邀请附近的设备发起连接

invitePeer({params}, callback(ret))

params

index：

  • 类型：数字
  • 描述：（可选项）所邀请的设备在已扫描新设备列表的下标，从0开始
  • 默认：0

timeout：

  • 类型：数字
  • 描述：（可选项）超时时间
  • 默认：10

callback(ret, err)

ret：

  • 类型：JSON 对象
  • 内部字段：
{
    eventType:	 //字符串类型；交互事件类型；取值范围：
                  //connected：建立链接
                  //connecting：正在建立连接
                  //notConnected：断开 
}

示例代码

var MCBluetooth = api.require('MCBluetooth');
MCBluetooth.invitePeer({
    index: 0,
    timeout:10
}, function(ret) {
    if (ret) {
        api.alert({msg:JSON.stringify(ret)});
    } 
});

可用性

iOS系统

可提供的 1.0.0 及更高版本

是否仍需要帮助？ 请保持联络！
最后更新于 2024/04/24