MCBluetooth

概述

背景

在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/12/2