WSBrowseForLinkServices()

int WSBrowseForLinkServices(WSENV e,WSBrowseCallbackFunction f,const char *p,const char *d,void *c,WSServiceRef *r)

开始上网浏览 WSTP 服务匹配协议 p，网络域为 d，并通过回调函数 f 传递 f 上下文对象 c 和浏览操作参考（browse operation reference） r，向程序异步通知服务状态.

更多信息

  • 浏览链接服务本质上是一个异步操作. 调用 WSBrowseForLinkServices() 以开始浏览操作. WSTP 库会在网络浏览事件发生时对提供的回调函数 f 进行回调. WSBrowseForLinkServices() 并不等待浏览操作完成，而是在浏览操作开始后立刻返回调用者.
  • 网络浏览操作会一直运行，直到程序调用 WSStopBrowsingForLinkServices() 或操作系统服务浏览机制发生错误. 这种连续操作说明，当浏览操作处于活动状态时，程序的回调函数可以在任何时候接收回调信号.    
  • 由于 WSTP 库是异步使用回调函数来注册浏览事件，回调函数必须注意要保护共享资源的通路，比如要注意可同时从另一线程访问的数据结构.
  • 上下文对象 c 可能是程序为成功解决命名链接服务所需的对象指针.
  • 域名 d 指定了可浏览服务的网络域. 但大多数应用并不指定域名，而是用传递 NULL 表示 d 来代替，说明 WSBrowseForLinkServices() 应在默认域内浏览服务.
  • 使用 WSStopBrowsingForLinkServices() 以停止浏览操作.
  • 用户必须对每一个想要接收浏览事件回调信号的协议 p 调用 WSBrowseForLinkServices().
  • 若函数成功，则 WSBrowseForLinkServices() 返回0；若失败，则返回非零值.
  • 由于错误而从 WSBrowseForLinkServices() 返回的非零值相当于 wstp.h 中由 WSError()返回的 WSE 错误代码.

范例

基本范例  (1)

#include "wstp.h"

void BrowseCallbackFunction(WSENV e, WSServiceRef r, int flag, const char *serviceName, void *context);

void doWSTPServiceBrowsing(WSENV e, const char *protocol)
{
    int apiResult;
    WSServiceRef r;

    apiResult = WSBrowseForLinkServices(env, BrowseCallbackFunction,
        protocol, NULL /* For the default browse domain */, NULL, &r);
    if(apiResult != 0)
    { /* handle error */}

    /* Perform other tasks while browsing occurs */

    /* For completeness stop the browse operation, this would normally
    be handled at another point in the code */
    WSStopBrowsingForLinkServices(e, r);
}


void BrowseCallbackFunction(WSENV e, WSServiceRef r, int flag, const char *serviceName, void *context)
{
    if(flag & WSSDADDSERVICE)
    {
        /* The service named in serviceName has become available
        on the network, store the name for use in the program.  Don't
        forget to include any synchronization mechanisms needed for
        ensuring the integrity of shared data structures. */
    }
    else if(flag & WSSDREMOVESERVICE)
    {
        /* The service named in serviceName is no longer available
        on the network, remove the name from any stored account of
        named services on the network.  Again, don't forget to make
        use of synchronization mechanisms to ensure application             integrity.  */
    }
    else if(flag & WSSDBROWSEERROR)
    {
        /* An error has occurred with the browse operation.  When this         case happens, the program should use 
        WSStopBrowsingForLinkServices() to shutdown the browse
        operation.  An error communicating with the operating system
        service discovery mechanisms has occurred and the browse
        should be stopped and re-started.   In addition, when
        WSSDBROWSEERROR occurs, all cached service names should be
        released. */
    }
}