第 4 章 - mDNS 服务说明

本章介绍所有 NetX mDNS 服务(下面列出的)。

注意

在以下 API 说明的“返回值”部分中,以粗体显示的值不受定义用于禁用 API 错误检查的 NX_DISABLE_ERROR_CHECKING 影响,而不以粗体显示的值会被完全禁用。

nx_mdns_create

创建 mDNS 实例

原型

UINT nx_mdns_create(
    NX_MDNS *mdns_ptr,
    NX_IP *ip_ptr,
    NX_PACKET_POOL *packet_pool,
    UINT priority, 
    VOID *stack_ptr,
    UINT stack_size,
    UCHAR *host_name,
    VOID *local_service_cache,
    UINT local_service_cache_size,
    VOID *peer_service_cache,
    UINT peer_service_cache_size,
    VOID (*probing_notify)(
        NX_MDNS *mdns_ptr,
        UCHAR *name,
        UINT probing_state));

说明

此服务可在特定 IP 实例和关联的资源中创建 mDNS 实例。 此外,还可创建线程来处理传入 mDNS 消息,响应查询以及定期传输查询消息。

输入参数

  • mdns_ptr:指向 mDNS 控制块的指针。
  • ip_ptr:指向关联 IP 实例的指针。
  • packet_pool:指向有效数据包池的指针。
  • priority:mDNS 线程的优先级。
  • stack_ptr:指向 mDNS 线程堆栈区的指针
  • stack_size:堆栈区的大小。
  • host_name:分配给此节点的主机名。
  • local_service_cache:本地注册服务的存储空间。
  • local_service_cache_size:本地服务缓存的大小。
  • peer_service_cache:已接收服务信息的存储空间
  • peer_service_cache_size:对等服务缓存的大小
  • probing_notify:在探测操作结束时调用的可选回调函数。 此函数可通知应用程序:主机名(在本地接口上启用 mDNS 时)或服务名称(注册服务后)是否是唯一的。

返回值

  • NX_SUCCESS:(0x00) 已成功创建 mDNS 实例。

获准方式

线程数

示例

UCHAR stack_ptr[2048];
UCHAR local_cache_ptr[2048];
UCHAR peer_cache_ptr[8192];

/* Create a mDNS instance. */
status = nx_mdns_create(&my_mdns, &ip_0, &pool_0,
    3, stack_ptr, 2048,
    “NETX-MDNS-HOST”,
    local_cache_ptr, 2048,
    peer_cache_ptr, 8192,
    probing_notify);

/* If status is NX_SUCCESS, mDNS instance was created. */

nx_mdns_delete

删除 mDNS 实例

原型

UINT nx_mdns_delete(NX_MDNS *mdns_ptr);

说明

此服务可删除 mDNS 实例,并释放其资源。

输入参数

  • mdns_ptr:指向 mDNS 控制块的指针。

返回值

  • NX_SUCCESS:(0x00) 已成功删除 mDNS 实例。

获准方式

线程数

示例

/* Delete a previously created mDNS instance. */

status = nx_mdns_delete(&my_mdns);

/* If status is NX_SUCCESS, the mDNS instance has been deleted. */

nx_mdns_enable

启动 mDNS 服务

原型

UINT nx_mdns_enable(
    NX_MDNS *mdns_ptr,
    UINT interface_index);

说明

此 API 可在特定物理接口上启用 mDNS 服务。 启用服务后,mDNS 模块会先在网络上探测其所有的唯一服务名称,然后再响应接口所收到的查询。

输入参数

  • mdns_ptr:指向 mDNS 实例控制块的指针。
  • interface_index:要启用服务的接口的索引

返回值

  • NX_SUCCESS:(0x00) 已成功启用服务。

获准方式

线程数

示例

/* Enable mDNS service on specific interface. */

status = nx_mdns_enable(&my_mdns, 0);

/* If status is NX_SUCCESS, mDNS service was enabled. */

nx_mdns_disable

禁用 mDNS 服务

原型

UINT nx_mdns_disable(
    NX_MDNS *mdns_ptr,
    UINT interface_index);

说明

此 API 可在特定物理接口上禁用 mDNS 服务。 禁用服务后,mDNS 会将发给各本地服务的“再见”消息发送到此接口所连接的网络,以便通知邻近节点。

输入参数

  • mdns_ptr:指向 mDNS 控制块的指针。
  • interface_index:要禁用服务的接口的索引

返回值

  • NX_SUCCESS:(0x00) 已成功禁用服务。

获准方式

线程数

示例

/* Disable mDNS service on specific interface. */

status = nx_mdns_disable(&my_mdns, 0);

/* If status is NX_SUCCESS, mDNS service was disabled. */

nx_mdns_cache_notify_set

安装 mDNS 缓存已满通知函数

原型

UINT nx_mdns_cache_notify_set(
    NX_MDNS *mdns_ptr,
    VOID (*cache_full_notify_cb)(
        NX_MDNS *mdns_ptr,
        UINT state,
        UINT cache_type));

说明

此服务可安装用户提供的回调函数,以便在本地服务缓存或对等服务缓存已满时调用此函数。 当服务缓存已满时,不能再添加 mDNS 资源记录。 请注意,当添加和删除具有各种字符串长度的服务时,服务缓存可能会因内部碎片而被填满。 在收到对等服务缓存的缓存已满通知时,应用程序可以使用服务“nx_mdns_service_cache_clear”清除对等服务缓存中的所有条目。

输入参数

  • mdns_ptr:指向 mDNS 控制块的指针。

返回值

  • NX_SUCCESS:(0x00) 已成功安装 mDNS 缓存通知回调函数。

获准方式

线程数

示例

/* Set mDNS cache notify callback. */

status = nx_mdns_cache_notify_set(&my_mdns, cache_full_nofiy_cb);

/* If status is NX_SUCCESS, mDNS cache notify callback was set. */

nx_mdns_cache_notify_clear

清除 mDNS 服务缓存已满通知函数

原型

UINT nx_mdns_cache_notify_clear(NX_MDNS *mdns_ptr);

说明

此服务可清除用户提供的服务缓存通知回调函数。

输入参数

  • mdns_ptr:指向 mDNS 控制块的指针。

返回值

  • NX_SUCCESS:(0x00) 已成功清除 mDNS 服务缓存通知回调函数。

获准方式

线程数

示例

/* Clear mDNS cache notify callback. */

status = nx_mdns_cache_notify_clear(&my_mdns);

/* If status is NX_SUCCESS, mDNS cache notify callback clear. */

nx_mdns_domain_name_set

设置域名

原型

UINT nx_mdns_domain_name_set(
    NX_MDNS *mdns_ptr,
    CHAR *domain_name);

说明

此服务可设置默认本地域名。 创建 mDNS 实例时,将默认本地域名设置为“.local”。 使用此 API,应用程序可覆盖默认本地域名。

输入参数

  • mdns_ptr:指向 mDNS 控制块的指针。
  • domain_name:要使用的域名。

返回值

  • NX_SUCCESS:(0x00) 已成功配置本地域。

获准方式

线程数

示例

/* Set the domain name. */

status = nx_mdns_domain_name_set(&my_mdns, “home”);

/* If status is NX_SUCCESS, the “home” domain name was set. */

nx_mdns_service_announcement_timing_set

设置服务公告消息的计时参数

原型

UINT nx_mdns_service_announcement_timing_set(
    NX_MDNS *mdns_ptr,
    UINT t,
    UINT p,
    UINT k,
    UINT retrans_interval,
    UINT period_interval,
    UINT max_time);

说明

此服务可在发送服务公告时重新配置 mDNS 使用的计时参数。 发布期初始值为 t 个时钟周期,此时长可以扩大为 2 的 k 次方倍。 每次播发的重复次数为 p,每次重复播发的间隔为 interval 个时钟周期,而公告期数为 max_time。 默认情况下,初始公告期设置为 1 秒,并且 k = 1(公告期每次翻倍)、p = 1(不重复)、retrans_interval = 0(无时间间隔)、period_interval = 0xFFFFFFFF(最大公告期间隔)和 max_time = 3(播发次数)。

输入参数

  • mdns_ptr:指向 mDNS 控制块的指针。
  • t:初始公告期的时钟周期数。 默认值为 100 个时钟周期,表示 1 秒。
  • p:重复次数。 默认值为 1。
  • k:扩大倍数。 默认值为 1。
  • retrans_interval:发送重复公告消息之前要等待的时钟周期数。 默认值为 0。
  • period_interval:两次公告期之间的时钟周期数。 默认值为 0xFFFFFFFF。
  • max_time:用于播发的公告期数。 在 max_time 公告期后,不再发送公告消息。 默认值为 3。

返回值

  • NX_SUCCESS:(0x00) 成功设置计时值。

获准方式

线程数

示例

/* Set the service announcement timing. */

status = nx_mdns_service_announcement_timing_set(&my_mdns, 100,
    1, 1, 0, 0xFFFFFFFF, 3);

/* If status is NX_SUCCESS, the service announcement timing was set. */

nx_mdns_service_add

添加本地服务

原型

UINT nx_mdns_service_add(
    NX_MDNS *mdns_ptr,
    CHAR *instance,
    CHAR *service,
    CHAR *subtype,
    UINT ttl,
    USHORT priority,
    USHORT weight,
    USHORT port,
    UCHAR *text,
    UCHAR is_unique,
    UINT interface_index);

说明

此 API 可注册应用程序提供的服务。 如果设置标记 is_unique,则 mDNS 会在网络上开始公告服务之前,先探测此服务名称,以确保其在本地网络上是唯一的。 Instance 是服务名称的实例部分。 service 是服务名称的服务部分。 例如,“_http._tcp”是服务。 若要描述具有子类型的服务,调用方必须使用 subtype 参数。 例如,如果所需服务为“_printer._sub._http._tcp”,则服务字段为“_http._tcp”,子类型字段为“_printer”。

输入参数

  • mdns_ptr:指向 mDNS 控制块的指针。
  • instance:指向服务实例名称的指针。
  • service:指向 mDNS 服务类型(不包括子类型信息)的指针。
  • subtype:指向 mDNS 服务子类型部分(如果适用)的指针。
  • priority:服务优先级
  • weight:服务权重
  • port:服务使用的 TCP 或 UDP 端口号
  • text:其他文本信息
  • is_unique:布尔型标记,指示服务是共享的还是唯一的。 对于注册为唯一的服务,mDNS 必须在开始提供服务之前,先在网络上探测此服务。
  • Interface_index:提供服务的物理接口。 对于通过任何附加服务提供的服务,需使用 NX_MDNS_ALL_INTERFACES 值。

返回值

  • NX_SUCCESS:(0x00) 已成功注册服务。

获准方式

线程数

示例

/* Add local service. */

status = nx_mdns_service_add(&my_mdns, “NETX-SERVICE”,
    “_http._tcp”, NX_NULL,
    NX_NULL, 0, 0, 0, 80, NX_TRUE, 0);

/* If status is NX_SUCCESS, The service (NetX-SERVICE._http._tcp.local) was added. */

nx_mdns_service_delete

删除以前注册的服务

原型

UINT nx_mdns_service_delete(
    NX_MDNS *mdns_ptr,
    CHAR *instance,
    CHAR *service,
    CHAR *subtype);

说明

此 API 可删除以前注册的服务。 删除服务时,会将“再见”消息发送到本地网络,以便通知邻近节点。

输入参数

  • mdns_ptr:指向 mDNS 控制块的指针。
  • instance:指向服务实例名称的指针。
  • service:指向 mDNS 服务类型(不包括子类型信息)的指针。
  • subtype:指向 mDNS 服务子类型部分(如果适用)的指针。

返回值

  • NX_SUCCESS:(0x00) 已成功删除服务。

获准方式

线程数

示例

/* Delete local service. */

status = nx_mdns_service_delete(&my_mdns, “NETX-SERVICE”, “_http._tcp”, NX_NULL);

/* If status is NX_SUCCESS, The service (NetX-SERVICE._http._tcp.local) was deleted. */

nx_mdns_service_one_shot_query

启动一次性服务发现

原型

UINT nx_mdns_service_one_shot_query(
    NX_MDNS *mdns_ptr,
    UCHAR *instance,
    UCHAR *service,
    UCHAR *subtype,
    NX_MDNS_SERVICE *service_ptr,
    ULONG wait_option);

说明

此服务可执行一次性 mDNS 查询。 如果在对等服务缓存中找到指定服务,则返回第一个实例。 如果在本地对等服务缓存中找不到服务,则 mDNS 模块会发出查询命令并等待响应。 在收到第一个应答或查询超时之前,系统不会阻止此服务。

输入参数

  • mdns_ptr:指向 mDNS 控制块的指针。
  • instance:指向服务实例名称(如果适用)的指针。
  • service:指向 mDNS 服务类型(不包括子类型信息)的指针。 应用程序必须指定服务类型。
  • subtype:指向 mDNS 服务子类型部分(如果适用)的指针。
  • service_ptr:用户提供的指针,可指向存储查询结果的 NX_MDNS_SERVICE 结构。
  • wait_option:等待响应的时长,以时钟周期为单位。

返回值

  • NX_SUCCESS:(0x00) 已成功获取服务信息。

获准方式

线程数

示例

/* Start service one shot query. */

status = nx_mdns_service_one_shot_query(&my_mdns, “NETX-SERVICE”, “_http._tcp”,
    NX_NULL, service_ptr, 500);

/* If status is NX_SUCCESS, The query with
    name: NetX-SERVICE._http._tcp.local,
     type: ANY (SRV and TXT) was sent.
    And the answer was stored in service_ptr if success. */

nx_mdns_service_continuous_query

启动连续服务发现

原型

UINT nx_mdns_service_continous_query(
    NX_MDNS *mdns_ptr,
    CHAR *instance,
    CHAR *service,
    CHAR *subtype);

说明

此服务可启动连续查询。 请注意,此服务会立即返回结果。 发出连续查询后,应用程序可使用 API nx_mdns_service_lookup 检索服务记录。 若要停止连续查询,应用程序可以使用 API nx_mdns_service_query_stop

输入参数

  • mdns_ptr:指向 mDNS 控制块的指针。
  • instance:指向服务实例名称(如果适用)的指针。
  • service:指向 mDNS 服务类型(不包括子类型信息,如果适用)的指针。
  • subtype:指向 mDNS 服务子类型部分(如果适用)的指针。

返回值

  • NX_SUCCESS:(0x00) 已成功启动连续查询。

获准方式

线程数

示例

/* Start service continuous query. */

status = nx_mdns_service_continuous_query(&my_mdns,
    “NETX-SERVICE”, “_http._tcp”, NX_NULL);

/* If status is NX_SUCCESS, The continuous query with
    name: NetX-SERVICE._http._tcp.local,
    type: ANY (SRV and TXT) was added.
    And the query will be periodically sent. */

nx_mdns_service_query_stop

终止以前发出的连续服务发现

原型

UINT nx_mdns_service_query_stop(
    NX_MDNS *mdns_ptr,
    CHAR *instance,
    CHAR *service,
    CHAR *subtype);

说明

此 API 可终止以前发出的连续服务发现。

输入参数

  • mdns_ptr:指向 mDNS 控制块的指针。
  • instance:指向服务实例名称的指针。
  • service:指向 mDNS 服务类型、子类型信息的指针。
  • subtype:指向 mDNS 服务子类型部分(如果适用)的指针。

返回值

  • NX_SUCCESS:(0x00) 已成功停止连续查询。

获准方式

线程数

示例

/* Stop service continuous query. */

status = nx_mdns_service_query_stop(&my_mdns, “NETX-SERVICE”, “_http._tcp”, NX_NULL);

/* If status is NX_SUCCESS, The continuous query with
    name: NetX-SERVICE._http._tcp.local,
    type: ANY (SRV and TXT) was stopped. */

nx_mdns_service_lookup

从本地对等服务缓存中检索服务

原型

UINT nx_mdns_service_lookup(
    NXD_MDNS *mdns_ptr,
    CHAR *instance,
    CHAR *service,
    CHAR *subtype,
    UINT instance_index,
    NXD_MDNS_SERVICE *service_ptr);

说明

此服务可在本地对等服务缓存中查找与特定实例名称(如果已提供)和服务类型匹配的服务。 在 instance_index 设置为零时,应用程序会启动服务查找,以获取缓存中与描述一致的第一个服务。 随着 instance_index 值的增大,应用程序会继续使用此服务,获取缓存中找到的其他服务,直到服务返回 NX_NO_MORE_ENTRIES,该值指示已查询到缓存结尾。

输入参数

  • mdns_ptr:指向 mDNS 控制块的指针。
  • instance:指向服务实例名称(如果适用)的指针。
  • service:指向 mDNS 服务类型(不包括子类型信息,如果适用)的指针。
  • subtype:指向 mDNS 服务子类型部分(如果适用)的指针。
  • Instance_index:要返回实例的索引号。
  • service_ptr:用户提供的指针,可指向存储查找结果的 NX_MDNS_SERVICE 结构。

返回值

  • NX_SUCCESS:(0x00) 已成功检索服务
  • NX_NO_MORE_ENTRIES:(0x17) 按指定索引号找不到服务项。 此错误代码表示搜索结束。

获准方式

线程数

示例

/* Lookup the service on specific index. */

status = nx_mdns_service_lookup(&my_mdns, “NETX-SERVICE”, “_http._tcp”, NX_NULL,
    0, service_ptr);

/* If status is NX_SUCCESS, The service with
    name: NetX-SERVICE._http._tcp.local, was retrieved. */

nx_mdns_service_ignore_set

配置服务忽略集

原型

UINT nx_mdns_service_ignore_set(
    NX_MDNS *mdns_ptr,
    ULONG service_mask);

说明

此 API 可配置掩码,以便忽略 service_mask 位掩码所指定的服务。 用户可以选择使用 service_mask 来选择不希望缓存的服务类型。 服务列表已在 nxd_mdns.c 的 nx_mdns_service_types 表中进行定义。nx_mdns_service_types[] 中第一个服务类型的相应掩码是 0x00000001,第二个服务类型的掩码是 0x00000002,依此类推。

输入参数

  • mdns_ptr:指向 mDNS 控制块的指针。
  • service_mask:要忽略的用户定义服务类型。 掩码是 32 位 ULONG 类型。 每一位均代表用户定义 nx_mdns_service_types 数组中的一个条目。 如果已设置某位,则在 nx_mdns_service_type 数组中指定的相应服务类型不会存储到对等服务缓存中。

返回值

  • NX_SUCCESS:(0x00) 成功设置服务忽略掩码。

获准方式

线程数

示例

/* Set the service mask to ignore the specified service. */

status = nx_mdns_service_ignore_set(&my_mdns, 0x00000003);

/* If status is NX_SUCCESS, The service with
    type “_device-info” and “_http” will be ignored. */

nx_mdns_service_notify_set

配置服务更改通知回调函数

原型

UINT nx_mdns_service_notify_set(
    NX_MDNS *mdns_ptr,
    ULONG service_mask,
    VOID (*service_change_notify)(
        NX_MDNS *mdns_ptr,
        NX_MDNS_SERVICE *service_ptr,
        UINT state));

说明

此 API 可配置服务更改通知回调函数。 当网络上其他节点提供的服务被添加、更改或不再可用时,可调用此回调函数。 用户可以选择使用 service_mask 来选择希望监视的服务类型。 受监视服务的列表已在 nxd_mdns.c 的 nx_mdns_service_types 表中进行硬编码。

nx_mdns_service_types[] 中第一个服务类型的相应掩码是 0x00000001,第二个服务类型的掩码是 0x00000002,依此类推。

输入参数

  • mdns_ptr:指向 mDNS 控制块的指针。
  • service_mask:要监视的用户定义服务类型。 掩码是 32 位 ULONG 类型。 每一位均代表 nx_mdns_service_types 数组中的一个条目。
  • service_change_notify 更改指定服务时要调用的回调函数。 系统会将详细的服务信息返回到 service_ptr 所指向的内存中。请注意,通过通知回调函数返回信息后,内存中的内容无效。

返回值

  • NX_SUCCESS:(0x00) 已成功安装回调函数。

获准方式

线程数

示例

/* Set the service mask to notify the specified service. */

status = nx_mdns_service_notify_set(&my_mdns, 0x00000002, service_change_notify);

/* If status is NX_SUCCESS, the callback will be called
    if received the service with type “_http”. */

nx_mdns_service_notify_clear

清除服务更改通知回调函数

原型

UINT nx_mdns_service_notify_clear(NX_MDNS *mdns_ptr);

说明

此 API 可清除服务更改通知回调函数和。

输入参数

  • mdns_ptr:指向 mDNS 控制块的指针。

返回值

  • NX_SUCCESS:(0x00) 已成功清除回调函数。

获准方式

线程数

示例

/* Clear the service notify. */

status = nx_mdns_service_notify_clear(&my_mdns);

/* If status is NX_SUCCESS, the service notify function clear. */

nx_mdns_host_address_get

获取主机地址

原型

UINT nx_mdns_host_address_get(
    NX_MDNS *mdns_ptr,
    UCHAR *host_name,
    ULONG *ipv4_address,
    ULONG *ipv6_address,
    ULONG wait_option);

说明

此服务可对主机 IPv4 和 IPv6 地址执行 mDNS 查询。 如果在对等服务缓存中找到指定主机名的地址,则返回该地址。 如果在对等服务缓存中找不到地址,则 mDNS 模块会发出 A 和 AAAA 类型查询,并等待响应。 在收到应答或查询超时之前,此 API 不会阻止查询。

输入参数

  • mdns_ptr:指向 mDNS 控制块的指针。
  • host_name:指向主机名的指针。
  • ipv4_address:指向 IPv4 地址存储空间中 4 字节对齐地址的指针。 用户应为 IPv4 地址分配 4 字节空间。 如果应用程序不需要检索 IPv4 地址,则可将 NX_NULL 地址传递到此 API。
  • ipv6_address:指向 IPv6 地址存储空间中 4 字节对齐地址的指针。 用户应为 IPv6 地址分配 16 字节空间。 如果应用程序不需要检索 IPv6 地址,则可将 NX_NULL 地址传递到此 API。
  • wait_option:等待响应的时长,以时钟周期为单位。

返回值

  • NX_SUCCESS:(0x00) 成功获取主机地址。

获准方式

线程数

示例

ULONG ipv4_address;
ULONG ipv6_address[4];

/* Get the IP address of specified host. */
status = nx_mdns_host_address_get(&my_mdns, “MDNS-Host”, &ipv4_address, ipv6_address, 500);

/* If status is NX_SUCCESS, the IP address of specified host was retrieved. */

nx_mdns_local_cache_clear

清除所有本地服务

原型

UINT nx_mdns_local_cache_clear(NX_MDNS *mdns_ptr);

说明

此服务可在发送再见消息后清除本地服务缓存中的所有条目。

输入参数

  • mdns_ptr:指向 mDNS 控制块的指针。

返回值

  • NX_SUCCESS:(0x00) 已成功清除缓存中的所有条目。

获准方式

线程数

示例

/* Clear the local cache, delete all local service. */

status = nx_mdns_local_cache_clear(&my_mdns);

/* If status is NX_SUCCESS, all services and resource records of local cache were deleted. */

nx_mdns_peer_cache_clear

清除所有已发现的服务

原型

UINT nx_mdns_peer_cache_clear(NX_MDNS *mdns_ptr);

说明

此服务可清除对等服务缓存中的所有条目。

输入参数

  • mdns_ptr:指向 mDNS 控制块的指针。

返回值

  • NX_SUCCESS:(0x00) 已成功清除缓存中的所有条目。

获准方式

线程数

示例

/* Clear the peer cache, delete all peer service. */

status = nx_mdns_peer_cache_clear(&my_mdns);

/* If status is NX_SUCCESS, all services and resource records of peer cache were deleted. */