UDP插件API文档(Uniapp)

关于版本

【源码授权版】和【普通授权版】功能上是完全一样的。
【源码授权版】适用于项目对外部插件源代码有要求或者需要基于插件源码进行二次开发和定制的场景。源码授权版支持使用标准基座进行运行调试。

关于插件

本插件为uniapp提供原生UDP通信能力。UDP通常用于进行局域网内设备发现、消息广播通知等场景。

支持在APP端建立UDP服务端链接，接收外部设备（通常是局域网设备）发送过来的消息。支持同时建立多个UDP服务端。支持单播、组播、广播功能。
支持在APP端建立UDP客户端链接连接到外部的UDP服务端进行通信，支持同时建立多个UDP客户端链接连接到不同的服务端。支持单播、组播、广播功能。

API文档

在线的API文档链接：插件API文档 API_SCREENSHOT

如何使用

基础概念

UDP单播（Unicast）: 一对一通信，数据从单个发送方传输到单个接收方。数据包通过目标IP地址和端口直接送达指定主机。
UDP多播（Multicast）: 一对多通信，发送方将数据发送到一个多播组地址（范围：224.0.0.0 ~ 239.255.255.255），加入该组的所有主机都能接收数据。
UDP广播（Broadcast）: 一对所有通信，数据发送到本地网络的所有主机（目标IP为广播地址，如255.255.255.255或子网广播地址192.168.1.255）。

引入

import { UtsUdpServer, UtsUdpClient, UtsErrorMessage } from '@/uni_modules/ts-udp-tool';

UDP服务端基本使用

使用UtsUdpServer建立UDP服务端

// 初始化【单播】UDP服务端
let unicastUdpServer : UtsUdpServer = new UtsUdpServer()
// 初始化服务
unicastUdpServer.initUdpSocket(
    // 配置
    {
        listenLocalPort: 20101,
        dataType: "text", // 接收的数据格式，支持：text-文本，hex-十六进制字符串，byte-二进制byte数组
        broadcastType: "unicast", // 支持：unicast-单播，multicast-组播，broadcast-广播
    },
    // 回调
    {
        // 接受到客户端发送过来的数据消息
        onReceivedData(session, message) {
            log("【单播-服务端】链接接收到消息:", session, message)
            // 对接收的消息进行处理
        },
        // 错误消息
        onErrorStr(errorMsg) {
            log("错误消息:", errorMsg)
        },
    }, 
    (errMsg : UtsErrorMessage) => {
        log("初始化UDP链路回调结果：", errMsg)
    }
)

// 初始化【广播】UDP服务端
let broadcastUdpServer : UtsUdpServer = new UtsUdpServer()
broadcastUdpServer.initUdpSocket(
    // 配置
    {
        listenLocalPort: 20101,
        dataType: "text", // 接收的数据格式，支持：text-文本，hex-十六进制字符串，byte-二进制byte数组
        broadcastType: "broadcast", // 支持：unicast-单播，multicast-组播，broadcast-广播
    },
    // 回调
    {
        // 接受到客户端发送过来的数据消息
        onReceivedData(session, message) {
            log("【广播-服务端】链接接收到消息:", session, message)
            // 对接收的消息进行处理
        },
        // 错误消息
        onErrorStr(errorMsg) {
            log("错误消息:", errorMsg)
        },
    }, 
    (errMsg : UtsErrorMessage) => {
        log("初始化UDP链路回调结果：", errMsg)
    }
)

// 初始化【组播】UDP服务端
let unicastUdpServer : UtsUdpServer = new UtsUdpServer()
unicastUdpServer.initUdpSocket(
    // 配置
    {
        listenLocalPort: 20101,
        dataType: "text", // 接收的数据格式，支持：text-文本，hex-十六进制字符串，byte-二进制byte数组
        broadcastType: "multicast", // 支持：unicast-单播，multicast-组播，broadcast-广播
        multicastGroup: "239.192.1.10" // 组播地址，必填。
    },
    // 回调
    {
        // 接受到客户端发送过来的数据消息
        onReceivedData(session, message) {
            log("【组播-服务端】链接接收到消息:", session, message)
            // 对接收的消息进行处理......
        },
        // 错误消息
        onErrorStr(errorMsg) {
            log("错误消息:", errorMsg)
        },
    }, 
    (errMsg : UtsErrorMessage) => {
        log("初始化UDP链路回调结果：", errMsg)
    }
)

发送（单播、广播、组播）消息，支持多种数据格式

/////////// 不同UDP链接发送消息示例 ///////////
// 单播服务端发送消息
unicastUdpServer.sendUdpMessage({
    dataType: "text",
    data:  "hello, world",
    destAddress: "192.168.50.130",
    destPort: 30101
},(errMsg : UtsErrorMessage) => {
    log("发送消息回调结果：", errMsg)
})

// 广播服务端发送消息
broadcastUdpServer.sendUdpMessage({
    dataType: "hex",
    data: "68656C6C6F2C2062726F616463617374", // hello, broadcast
    // 192.168.50.255代表192.168.50.x网段的子网的广播，"255.255.255.255"代表全网广播。iOS平台对全网广播限制很严格需要申请证书才能使用
    destAddress: "192.168.50.255", 
    destPort: 30102
},(errMsg : UtsErrorMessage) => {
    log("发送消息回调结果：", errMsg)
})

// 组播服务端发送消息
multicastUdpServer.sendUdpMessage({
    dataType: "text",
    data: "hello, multicast", // hello, multicast
    destAddress: "239.192.1.10", // 需要和初始化链接的时候指定的一致
    destPort: 30103
},(errMsg : UtsErrorMessage) => {
    log("发送消息回调结果：", errMsg)
})

/////////// 支持多种数据格式示例 ///////////
// 发送文本消息
unicastUdpServer.sendUdpMessage({
    dataType: "text",
    data:  "hello, world",
    destAddress: "192.168.50.130",
    destPort: 30101
},(errMsg : UtsErrorMessage) => {
    log("发送消息回调结果：", errMsg)
})

// 发送byte字节消息
unicastUdpServer.sendUdpMessage({
    dataType: "byte",
    byteData: [0x68, 0x65, 0x6c, 0x6c, 0x6f, 0x2c, 0x31, 0x32, 0x33], // hello,123
    destAddress: "192.168.50.130",
    destPort: 30101
},(errMsg : UtsErrorMessage) => {
    log("发送消息回调结果：", errMsg)
})

// 发送hex字符串消息
unicastUdpServer.sendUdpMessage({
    dataType: "hex",
    data: "68656c6c6f2c313233", // hello,123
    destAddress: "192.168.50.130",
    destPort: 30101
},(errMsg : UtsErrorMessage) => {
    log("发送消息回调结果：", errMsg)
})

关闭链接

unicastUdpServer.closeUdpSocket()

UDP客户端基本使用

使用UtsUdpClient建立UDP客户端

// 初始化【单播】UDP客户端
let unicastUdpClient : UtsUdpClient = new UtsUdpClient()
unicastUdpClient.initUdpSocket(
    // 配置
    {
        dataType: "text", // 接收的数据格式，支持：text-文本，hex-十六进制字符串，byte-二进制byte数组
        broadcastType: "unicast", // 支持：unicast-单播，multicast-组播，broadcast-广播
        destAddress: "192.168.50.130", // 目标地址
        destPort: 30101 // 目标端口
    },
    // 回调
    {
        // 接受消息，如果不需要接收消息可以去掉
        onReceivedData(session, message) {
            log("【单播-客户端】链接接收到消息:", session, message)
        },
        // 错误消息
        onErrorStr(errorMsg) {
            log("错误消息:", errorMsg)
        },
    }, 
    (errMsg : UtsErrorMessage) => {
        log("创建UDP链路回调结果：", errMsg)
    }
)

// 初始化【广播】UDP客户端
let broadcastUdpClient : UtsUdpClient = new UtsUdpClient()
broadcastUdpClient.initUdpSocket(
    // 配置
    {
        dataType: "text", // 接收的数据格式，支持：text-文本，hex-十六进制字符串，byte-二进制byte数组
        broadcastType: "broadcast", // 支持：unicast-单播，multicast-组播，broadcast-广播
        destAddress: "192.168.50.255", // 目标广播地址。广播地址主要分为子网广播、全网广播。全网广播地址255.255.255.255需要所在网络支持。
        destPort: 30101 // 目标广播端口
    },
    // 回调
    {
        // 接受消息，如果不需要接收消息可以去掉
        onReceivedData(session, message) {
            log("【广播-客户端】链接接收到消息:", session, message)
        },
        // 错误消息
        onErrorStr(errorMsg) {
            log("错误消息:", errorMsg)
        },
    }, 
    (errMsg : UtsErrorMessage) => {
        log("创建UDP链路回调结果：", errMsg)
    }
)

// 初始化【组播】UDP客户端
let multicastUdpClient : UtsUdpClient = new UtsUdpClient()
multicastUdpClient.initUdpSocket(
    // 配置
    {
        dataType: "text", // 接收的数据格式，支持：text-文本，hex-十六进制字符串，byte-二进制byte数组
        broadcastType: "multicast", // 支持：unicast-单播，multicast-组播，broadcast-广播
        destAddress: "239.192.1.10" // 目标组播地址。主要分为局域网组播、跨网段组播。跨网段组播需要所在网络支持。
        destPort: 30101 // 目标组播端口
    },
    // 回调
    {
        // 接受消息，如果不需要接收消息可以去掉
        onReceivedData(session, message) {
            log("【组播-客户端】链接接收到消息:", session, message)
        },
        // 错误消息
        onErrorStr(errorMsg) {
            log("错误消息:", errorMsg)
        },
    }, 
    (errMsg : UtsErrorMessage) => {
        log("创建UDP链路回调结果：", errMsg)
    }
)

发送消息给服务器

// 发送文本消息
unicastUdpClient.sendUdpMessage({
    dataType: "text",
    data:  "hello, world"
},(errMsg : UtsErrorMessage) => {
    log("发送消息回调结果：", errMsg)
})

// 发送二进制byte消息
unicastUdpClient.sendUdpMessage({
    dataType: "byte",
    byteData: [0x68, 0x65, 0x6c, 0x6c, 0x6f, 0x2c, 0x31, 0x32, 0x33], // hello,123
},(errMsg : UtsErrorMessage) => {
    log("发送消息回调结果：", errMsg)
})

// 发送hex十六进制字符串消息
unicastUdpClient.sendUdpMessage({
    dataType: "hex",
    data: "68656c6c6f2c313233" // hello,123
},(errMsg : UtsErrorMessage) => {
    log("发送消息回调结果：", errMsg)
})

关闭客户端链接

unicastUdpClient.closeUdpSocket()

权限要求

安卓Android权限

需要增加以下权限

<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name="android.permission.CHANGE_WIFI_MULTICAST_STATE" />

苹果iOS权限

需要增加以下权限

    <key>NSLocalNetworkUsageDescription</key>
    <string>需要扫描本地网络设备以提供服务</string>
    <key>NSMulticastServiceUsageDescription</key>
    <string>需要加入多播组以实现群组通信</string>
    <!-- 申请更广泛的网络访问权限，本地网络查找 -->
    <key>NSAllowsLocalNetworking</key>
    <true/>
    <!-- 后台网络使用，应用需要在后台运行服务器 -->
    <key>UIBackgroundModes</key>
    <array>
        <string>network</string>
    </array>

鸿蒙Harmony权限

需要增加以下权限

    "requestPermissions": [
      {
        "name": "ohos.permission.INTERNET"
      }
    ]

UDP插件API文档(Uniapp)

关于版本

关于插件

API文档

如何使用

基础概念

引入

UDP服务端基本使用

UDP客户端基本使用

权限要求

安卓Android权限

苹果iOS权限

鸿蒙Harmony权限

显示设置

目录