WSRegisterLinkServiceWithHostname （C 函数）

WSLINK WSRegisterLinkServiceWithHostname(WSENV e, const char *p, const char *n, const char *h, WSRegisterCallbackFunction f, const char *d, void *c, WSServiceRef *r, int *err)

开始在网络上为协议 p 推广名为 n, 的 WSTP 链接服务的过程，在操作系统和网络界面 h 为网络域名 d 选择的端口上推广服务，异步通过回调函数 f 将注册结果通知给该应用，并把上下文对象 c 和解析操作基准（resolve operation reference）r 传递给 f.

更多信息

  • WSRegisterLinkServiceWithHostname() 在网络上为协议 p 推广名为 n 的链接服务.
  • 注册链接服务名称本质上是一个异步操作. WSRegisterLinkServiceWitAndHostname() 开始注册操作，并立即返回. WSTP 库会用注册状态的更新回调到该应用.
  • 注册服务名称时，注册操作可能会检测到与已存在链接服务的名称发生冲突的问题. 若上述事件发生，WSTP 库会自动给该链接服务一个新名称，并将该名称通过回调函数 f 报告给该应用.
  • WSTP 库会发送回调函数 f、修改后的服务名称、说明注册结果的标记和上下文对象 c.
  • WSTP 库会继续在网络上推广该服务，直到应用调用 WSStopRegisteringLinkService() 或操作系统注册机制中发生错误.
  • 上下文对象 c 可以是应用需要用来成功注册链接服务的任意对象的指针.
  • 回调函数返回的的服务名称会有如下形式：service._protocol._transport.domain. 这个 _transport 字符串将会是 _tcp. 该应用只需要使用服务名称的 service 和 protocol 部分. 另外，这个名称会有一个适合在组播 DNS 记录中使用的形式，意即空格字符（space characters）会被编译为序列 "\\032"，且句点字符（period characters）会被编译为 as '\.'. 根据应用的需要，这些序列可能需要改变回空格字符或句点字符.
  • 若注册操作成功，则标记参数会有值 WSSDADDSERVICE. 若注册操作失败，则标记参数会有值 WSSDREMOVESERVICE. 若注册过程中发生了任何其他错误，则标记参数会有值 WSSDREGISTERERROR. 若应用收到 WSSDREGISTERERROR，则应用应该调用 WSStopRegisteringLinkService().
  • 可使用 WSStopRegisteringLinkService() 来停止注册操作.
  • 若成功，则 WSRegisterLinkServiceWithHostname() 会返回一个新的 WSLINK 对象. 该应用会使用这个 WSLINK 对象作为这个链接服务连接的接收端. 该应用必须在使用任何其他 WSTP API 函数之前在链接上调用 WSActivate().
  • 若失败，则 WSRegisterLinkServiceWithHostname() 会返回 NULL，且 err 参数会包含一个说明引起错误原因的错误代码. 这个错误代码相当于 wstp.h 中的 WSE 错误代码，并由 WSError() 返回.

范例

基本范例  (1)

#include "wstp.h"

void RegisterCallbackFunction(WSENV e, WSServiceRef r, int flags, const char *serviceName, void *context);

WSServiceRef startRegisterOperationForServiceWithProtocol(WSENV e, 
    const char *serviceName, const char *protocol)
{
    WSServiceRef theRef;
    WSLINK theLink = (WSLINK)0;
    int error;

    theLink = WSRegisterLinkServiceWithHostname(e,
        protocol, serviceName, "192.168.1.138", 
        RegisterCallbackFunction, NULL /* Use the default
        network domain */, NULL, /* No context object for this
        example */, &theRef, &error);

    if(theLink == (WSLINK)0 || error != 0)
    { /* handle the error */ }

    return theRef;    
}


void RegisterCallbackFunction(WSENV e, WSServiceRef r, int flags, const char *serviceName, void *context)
{
    if(flags & WSSDADDSERVICE)
    { /* Handle successful service registration */ }
    else if(flags & WSSDREMOVESERVICE)
    { /* Handle service registration failure */ }
    else if(flags & WSSDREGISTERERROR)
    { /* Handle error in register operation */ }
}