使用网络服务

项目
09/27/2024

重要

这是 Azure Sphere（旧版）文档。 Azure Sphere（旧版）将于 2027 年 9 月 27 日停用，用户此时必须迁移到 Azure Sphere（集成）。 使用位于 TOC 上方的版本选择器查看 Azure Sphere（集成）文档。

Azure Sphere 可以运行静态 IP 地址、动态主机配置协议 (DHCP) 服务器和用于网络接口的简单网络时间协议 (SNTP) 服务器。 Azure Sphere 应用程序可以通过 DHCP 服务器在网络上为外部设备配置网络参数。外部设备可以使用 SNTP 服务器将其时间与 Azure Sphere 同步。

网络配置

可以配置以太网和 Wi-Fi 网络接口，以便在 Azure Sphere 设备上同时运行。以太网和 Wi-Fi 网络接口可以连接到公共（已连接 Internet）或专用网络。至少一个接口必须连接到公用网络。一次只能配置一个以太网接口。

专用和公用网络接口

如果同时使用公用和专用网络接口，例如具有公共 Wi-Fi 的专用以太网，则 Azure Sphere 设备将不会充当路由器。它不会自动将以太网上收到的数据包传递到 Wi-Fi 网络，反之亦然。应用程序必须实现在两种网络上发送和接收信息的所有逻辑。

双公用网络接口

如果使用启用了动态 IP 寻址的两个网络接口，OS 会在选择用于主机名解析的 DNS 服务器地址时尝试使用连接到网络的第一个接口。如果接口与网络断开连接，则会自动使用来自其他连接接口的 DNS 服务器地址。

静态 IP 地址

可以在以太网或 Wi-Fi 接口上配置静态 IP 地址。若要设置静态 IP 地址配置，应用程序必须使用 applibs networking API，且应用程序清单必须启用 NetworkConfig 功能。

配置静态 IP 地址时，还必须设置自定义 DNS ，以确保 Azure Sphere OS 继续按预期运行。

专用网络服务示例演示了如何将 Azure Sphere 连接到专用网络，以及如何使用多个网络服务。

此代码片段演示如何使用静态 IP 地址配置网络接口。

在app_manifest.json文件的“功能”部分中包含以下行，如下所示：

"Capabilities": {
  "NetworkConfig": true
}

在应用程序中包括以下头文件：

#include <arpa/inet.h>
#include <errno.h>
#include <string.h>
#include <applibs/log.h>
#include <applibs/networking.h>

为 IP 配置设置 IP 地址、子网掩码和网关。

static const char staticIpInDotNotation[] = "yourStaticIp"; // Your static IP in x.x.x.x notation.
static const char subnetMaskInDotNotation[] =
    "yourSubnetMask"; // Your subnet mask in x.x.x.x notation.
static const char gatewayIpInDotNotation[] = "yourGatewayIp"; // Your gateway IP in x.x.x.x notation.

指定要配置的网络接口：

static const char networkInterfaceToConfigure[] = "yourNetworkInterface"; // Your network interface.

将网络地址转换为整数，并将其应用于指定的网络接口。

struct in_addr staticIpAddress;
struct in_addr subnetMask;
struct in_addr gatewayIpAddress;

Networking_IpConfig ipConfig;

// Convert the addresses from the numbers-and-dots notation into integers.
if (inet_pton(AF_INET, staticIpInDotNotation, &staticIpAddress) != 1) {
    Log_Debug("ERROR: Invalid static IP address or address family specified.\n");
    return -1;
}
if (inet_pton(AF_INET, subnetMaskInDotNotation, &subnetMask) != 1) {
    Log_Debug("ERROR: Invalid subnet mask or address family specified.\n");
    return -1;
}
if (inet_pton(AF_INET, gatewayIpInDotNotation, &gatewayIpAddress) != 1) {
    Log_Debug("ERROR: Invalid gateway IP address or address family specified.\n");
    return -1;
}

Networking_IpConfig_Init(&ipConfig);
Networking_IpConfig_EnableStaticIp(&ipConfig, staticIpAddress, subnetMask, gatewayIpAddress);

int result =
    Networking_IpConfig_EnableCustomDns(&ipConfig, dnsServers, numOfDnsServerAddressSpecified);

if (result != 0) {
    Log_Debug("ERROR: Networking_IpConfig_EnableCustomDns: %d (%s)\n", errno, strerror(errno));
    Networking_IpConfig_Destroy(&ipConfig);
    return -1;
}

int result = Networking_IpConfig_Apply(networkInterfaceToConfigure, &ipConfig);
Networking_IpConfig_Destroy(&ipConfig);

if (result != 0) {
    Log_Debug("ERROR: Networking_IpConfig_Apply: %d (%s)\n", errno, strerror(errno));
    return -1;
}

静态 DNS 地址

如果已配置具有静态 IP 的设备，并且需要名称解析，应用程序必须设置静态 DNS 地址。使用 Networking_IpConfig_EnableCustomDns 并设置一个或多个有效的 DNS 解析程序。如果设置了多个解析程序，将全部查询这些解析程序，并且第一个有效的 DNS 响应将满足查询。如果通过 DHCP 设置当前解析程序，也可以使用Networking_IpConfig_EnableCustomDns替代当前解析程序。

若要配置具有自定义 DNS 服务器的网络接口，应用程序清单必须启用 NetworkConfig 功能。

在app_manifest.json文件的“功能”部分中包含以下行，如下所示：

"Capabilities": {
  "NetworkConfig": true
}

此代码片段演示如何使用自定义 DNS 服务器配置网络接口。

在应用程序中包括以下头文件：

#include <arpa/inet.h>
#include <errno.h>
#include <string.h>
#include <applibs/log.h>
#include <applibs/networking.h>

指定 DNS 服务器数。最多可以指定三个 DNS 服务器。以下代码设置要使用的三个 DNS 服务器 IP 地址的数组。

// A maximum of 3 DNS server addresses can be specified.
static const size_t numOfDnsServerAddressSpecified = 3;
static const char *dnsServerIpAddress[] = {
    "yourDnsServer1", "yourDnsServer2", "yourDnsServer3"}; // Your DNS servers in x.x.x.x notation.

指定要配置的网络接口。

static const char networkInterfaceToConfigure[] = "yourNetworkInterface"; // Your network interface.

将网络地址转换为整数并应用配置。此 DNS 配置替代 DHCP 指定的任何 DNS 服务器。

Networking_IpConfig ipConfig;

// Convert the addresses from the numbers-and-dots notation into integers.
struct in_addr dnsServers[numOfDnsServerAddressSpecified];
for (int i = 0; i < numOfDnsServerAddressSpecified; i++) {
    if (inet_pton(AF_INET, dnsServerIpAddress[i], &dnsServers[i]) != 1) {
        Log_Debug("ERROR: Invalid DNS server address or address family specified.\n");
        return -1;
    }
}

Networking_IpConfig_Init(&ipConfig);

int result =
    Networking_IpConfig_EnableCustomDns(&ipConfig, dnsServers, numOfDnsServerAddressSpecified);

if (result != 0) {
    Log_Debug("ERROR: Networking_IpConfig_EnableCustomDns: %d (%s)\n", errno, strerror(errno));
    Networking_IpConfig_Destroy(&ipConfig);
    return -1;
}

result = Networking_IpConfig_Apply(networkInterfaceToConfigure, &ipConfig);
Networking_IpConfig_Destroy(&ipConfig);

if (result != 0) {
    Log_Debug("ERROR: Networking_IpConfig_Apply: %d (%s)\n", errno, strerror(errno));
    return -1;
}

DHCP 服务器

必须为通过以太网接口连接到 Azure Sphere 的外部客户端设备分配一个 IP 地址和其他网络参数，使其能够与 Azure Sphere 设备上的服务器应用程序通信。但是，某些外部设备不支持配置这些参数。 Azure Sphere 支持某个 DHCP 服务器，应用程序可以通过该服务器提供此配置。应用程序必须在其应用程序清单中启用 DhcpService 功能。

Azure Sphere 应用程序调用 Networking_DhcpServerConfig_Init 来配置服务器，以便向客户端设备提供 IP 地址、子网掩码、网关地址、租约持续时间和最多三个 NTP 服务器地址。只能在最新版本中配置一个 IP 地址。然后，应用程序调用 Networking_DhcpServer_Start 在特定的网络接口上启动服务器。 DHCP 服务器启动后，客户端设备可以发出广播 DHCP 消息，以发现和请求指定子网上 DHCP 服务器的 IP 地址。

SNTP 服务器

客户端设备可以使用 SNTP 服务器将其系统时间与 Azure Sphere 设备的系统时间同步。若要使用该服务器，Azure Sphere 应用程序必须在其应用程序清单中启用 SntpService 功能。

若要启动该服务器，Azure Sphere 应用程序需调用 Networking_SntpServer_Start，并指定运行该服务器的网络接口。客户端设备和 Azure Sphere 设备必须位于运行该服务器的网络的同一本地子网。 Azure Sphere 设备必须连接到至少一个公用网络，这样才能从公共网络时间协议 (NTP) 服务器获取当前时间。在获取当前时间之前，SNTP 服务器不会响应查询。

注意

尽管应用程序可以直接设置系统时间，但不建议采用这种做法，因为设备断电时，时间不会保留。在 Azure Sphere 上管理系统时间和 RTC提供了详细信息。

侦听端口

如果 Azure Sphere 应用程序侦听传入的 TCP 或 UDP 连接，应用程序清单必须指定应用程序使用的端口。例如：

"Capabilities": {
  "AllowedTcpServerPorts": [ 11000 ],
  "AllowedUdpServerPorts": [ 1024, 50000 ]
}

示例

DNS 服务发现示例演示了如何查询和处理来自 DNS 服务器的响应。
专用网络服务示例演示了如何将 Azure Sphere 连接到专用网络，以及如何使用多个网络服务。

通过