app.network - 网络信息 API

网络接口、WiFi、连通性和 DNS 信息。

方法

app.network.interfaces()

获取所有网络接口列表。

返回值: array<table> - 每项包含:

name (string) - 接口名（如 “en0”）
ip (string) - IP 地址
mac (string, 可选) - MAC 地址
type (string) - 类型: "wifi", "ethernet", "loopback", "vpn", "bridge", "other"
isUp (boolean) - 是否激活
family (string) - "ipv4" 或 "ipv6"

local ifaces = app.network.interfaces()
for _, iface in ipairs(ifaces) do
    app.log.info(iface.name .. ": " .. iface.ip .. " (" .. iface.type .. ")")
end

app.network.localIP()

获取本机局域网 IP 地址。

返回值: string|nil - 首个活跃的非回环 IPv4 地址

local ip = app.network.localIP()  -- "192.168.1.100"

app.network.wifiSSID()

获取当前连接的 WiFi 名称。

返回值: string|nil - WiFi SSID

local ssid = app.network.wifiSSID()  -- "MyNetwork"

app.network.wifiSignal()

获取 WiFi 信号强度。

返回值: number|nil - RSSI 值（负数，如 -45 表示信号良好）

local rssi = app.network.wifiSignal()  -- -42

app.network.isConnected()

检查互联网连通性。

返回值: boolean

if app.network.isConnected() then
    app.log.info("已联网")
end

app.network.externalIP()

获取公网 IP 地址（通过 api.ipify.org 查询）。

返回值: string, error

local ip, err = app.network.externalIP()  -- "203.0.113.1"

app.network.dns()

获取 DNS 服务器列表。

返回值: array<string>

local servers = app.network.dns()  -- {"8.8.8.8", "8.8.4.4"}

app.network.resolve(hostname)

同步解析主机名到 IP 地址列表（since 1.3.0）。同时返回 IPv4 与 IPv6，已去重。

参数:

hostname (string) - 主机名

返回值: array<string>, err

local ips, err = app.network.resolve("www.apple.com")
if ips then
    for _, ip in ipairs(ips) do app.log.info(ip) end
end

app.network.ping(host, opts?)

通过系统 /sbin/ping 测试连通性（since 1.3.0）。阻塞执行，结果包含 RTT 统计。

参数:

host (string) - 目标主机（IP 或域名）
opts (table, 可选)
- count (number) - ping 次数（默认 4，最大 30）
- timeout (number) - 整个 ping 的总超时秒数（默认 2，最大 30；到时 ping 自行退出）

返回值: table, err — 字段：

rtt_avg (number) - 平均延迟（ms）
rtt_min (number) - 最小延迟（ms）
rtt_max (number) - 最大延迟（ms）
loss (number) - 丢包率（百分比）
count (number) - 实际 ping 次数

local stats, err = app.network.ping("127.0.0.1", { count = 3 })
if stats then
    app.log.info(string.format("loss=%.1f%% avg=%.2fms", stats.loss, stats.rtt_avg))
end

事件监听

app.network.watch(event, callback)

监听网络状态变化事件。

参数:

event (string) - 事件名称（目前仅支持 "networkChanged"）
callback (function) - 回调函数，接收事件表:
- isConnected (boolean) - 是否已联网
- interfaceType (string) - 当前接口类型:
  - "wifi" - 无线网络
  - "wired" - 有线网络
  - "cellular" - 蜂窝网络
  - "other" - 其他类型
  - "none" - 无网络
- isExpensive (boolean) - 是否为计费连接（如热点共享）

返回值: string, error - watcher 句柄 ID

app.network.watch("networkChanged", function(e)
    if e.isConnected then
        app.log.info("网络已连接，类型: " .. e.interfaceType)
        if e.isExpensive then
            app.log.info("注意：当前为计费连接")
        end
    else
        app.log.info("网络已断开")
    end
end)

app.network.stopAllWatchers()

停止当前插件注册的所有网络事件监听器。