WSRegisterLinkService （C 関数）

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

ネットワーク上のプロトコル p の n という名前のWSTPサービスを通知し，ネットワークドメイン d 上のサービスを通知し，非同期的にコールバック関数 f を通して登録結果の適用を知らせ，f にコンテキストオブジェクト c と変換操作参照 r を渡すプロセスを開始する．

詳細

  • WSRegisterLinkService()は，ネットワーク上のプロトコル p の n という名前のリンクサービスを通知する．
  • リンクサービス名を登録することは，基本的に非同期操作である．WSRegisterLinkService()は，登録操作を開始し，すぐに返す．WSTPライブラリは，登録の状況についてのアップデートとともにアプリケーションへのコールバックを行う．
  • サービス名を登録する際に，登録操作は既存のリンクサービスの名前に同じものがあることを検知することがある．そのような場合には，WSTPライブラリは，リンクサービスに自動的に別の名前を与え，その名前をコールバック関数 f を通してアプリケーションに通知する．
  • WSTPライブラリは，コールバック関数 f，改正されたサービス名，登録結果を示すフラッグ，コンテキストオブジェクト c を送る．
  • WSTPライブラリは，アプリケーションがWSStopRegisteringLinkService()を呼び出すまで，あるいはオペレーティングシステムの登録システムでエラーが起るまで，ネットワーク上のサービスを通知し続ける．
  • コンテキストオブジェクト c は，アプリケーションがリンクサービスの登録に成功するのに必要な任意オブジェクトへのポインタである．
  • コールバック関数によって返されたサービス名は，service._protocol._transport.domainの形式を持つ．_transportの文字列は，_tcpである．アプリケーションは，サービス名のserviceおよびprotocolの部分だけを使用すればよい．さらに名前は，マルチキャストDNSの記録に使用するのに適切な形式である．つまり，スペースは数列"\\032"として，ピリオドは'\.'として符号化される．アプリケーションのニーズによっては，これらの数列はスペースおよびピリオドの文字に戻さなければならないこともある．
  • フラッグの引数は，登録操作が成功した場合には，値WSSDADDSERVICEを持つ．登録操作が失敗した場合には，フラッグ引数の値はWSSDREMOVESERVICEである．登録プロセスで別のエラーが起った場合には，フラッグ引数の値はWSSDREGISTERERRORとなる．アプリケーションがWSSDREGISTERERRORを受け取った場合には，アプリケーションはWSStopRegisteringLinkService()を呼び出さなくてはならない．
  • 登録操作を停止するには，WSStopRegisteringLinkService()を使う．
  • WSRegisterLinkService()は，成功すると新しいWSLINKオブジェクトを返す．アプリケーションはこのWSLINKオブジェクトをリンクサービス接続のリスニング側として使う．アプリケーションは，他のWSTPのAPI関数を使う前に，リンク上でWSActivate()を呼び出さなくてはならない．
  • WSRegisterLinkService()は，失敗すると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 = WSRegisterLinkService(e,
        protocol, serviceName,  
        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 */ }
}