第 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. */