Страницы справочника OS X

Эта страница руководства для  версии 10.9 Mac OS X

Читать страницы руководства

nameserv(n)                                 Name service facility                                nameserv(n)



____________________________________________________________________________________________________________

NAME
       nameserv - Name service facility, Client

SYNOPSIS
       package require Tcl  8.4

       package require nameserv  ?0.4.2?

       package require comm

       package require logger

       ::nameserv::bind name data

       ::nameserv::release

       ::nameserv::search ?-async|-continuous? ?pattern?

       ::nameserv::protocol

       ::nameserv::server_protocol

       ::nameserv::server_features

       ::nameserv::cget -option

       ::nameserv::configure

       ::nameserv::configure -option

       ::nameserv::configure -option value...

       $result destroy

       $result filled

       $result get name

       $result names

       $result size

       $result getall ?pattern?

____________________________________________________________________________________________________________

DESCRIPTION
       Please read Name service facility, introduction first.

       This  package  provides  a  client  for  the  name  service facility implemented by the package name-serv::server. nameserv::server.
       serv::server.

       This service is built in top of and for the package comm.  It has nothing to do with  the  Internet's
       Domain  Name  System.  If  the  reader is looking for a package dealing with that please see Tcllib's
       packages dns and resolv.

API
       The package exports eight commands, as specified below:

       ::nameserv::bind name data
              The caller of this command registers the given name as its name in the  configured  name  ser-vice, service,
              vice,  and additionally associates a piece of data with it. The service does nothing with this
              information beyond storing it and delivering it as part of  search  results.  The  meaning  is
              entirely up to the applications using the name service.

              A generally useful choice would for example be an identifier for a communication endpoint man-aged managed
              aged by the package comm. Anybody retrieving the name becomes immediately able to talk to this
              endpoint, i.e. the registering application.

              Of  further importance is that a caller can register itself under more than one name, and each
              name can have its own piece of data.

              Note that the name service, and thwerefore this command, will throw an  error  if  the  chosen
              name is already registered.

       ::nameserv::release
              Invoking  this command releases all names (and their data) registered by all previous calls to
              ::nameserv::bind of this client. Note that the name service will run this  command  implicitly
              when it loses the connection to this client.

       ::nameserv::search ?-async|-continuous? ?pattern?
              This  command  searches the name service for all registered names matching the specified glob-pattern. globpattern.
              pattern. If not specified the pattern defaults to *, matching everything. The  result  of  the
              command  is  a dictionary mapping the matching names to the data associated with them at bind-time. bindtime.
              time.

              If either option -async or -continuous were specified the result of this command  changes  and
              becomes  the  Tcl  command of an object holding the actual result.  These two options are sup-ported supported
              ported if and only if the service the client is connected to  supports  the  protocol  feature
              Search/Continuous.

              For -async the result object is asynchronously filled with the entries matching the pattern at
              the time of the search and then not modified any more.  The option  -continuous  extends  this
              behaviour  by additionally continuously monitoring the service for the addition and removal of
              entries which match the pattern, and updating the object's contents appropriately.

              Note that the caller is responsible for configuring the object  with  a  callback  for  proper
              notification when the current result (or further changes) arrive.

              For more information about this object see section ASYNCHRONOUS AND CONTINUOUS SEARCHES.

       ::nameserv::protocol
              This  command  returns the highest version of the name service protocol supported by the pack-age. package.
              age.

       ::nameserv::server_protocol
              This command returns the highest version of the name service protocol supported  by  the  name
              service the client is currently connected to.

       ::nameserv::server_features
              This  command returns a list containing the names of the features of the name service protocol
              which are supported by the name service the client is currently connected to.

       ::nameserv::cget -option
              This command returns the currently configured value for the specified  -option.  The  list  of
              supported options and their meaning can be found in section OPTIONS.

       ::nameserv::configure
              In this form the command returns a dictionary of all supported options, and their current val-ues. values.
              ues. The list of supported options and their meaning can be found in section OPTIONS.

       ::nameserv::configure -option
              In this form the command is an alias for "::nameserv::cget -option]".  The list  of  supported
              options and their meaning can be found in section OPTIONS.

       ::nameserv::configure -option value...
              In  this  form the command is used to configure one or more of the supported options. At least
              one option has to be specified, and each option is followed by its new  value.   The  list  of
              supported options and their meaning can be found in section OPTIONS.

              This form can be used only as long as the client has not contacted the name service yet. After
              contact has been made reconfiguration is not possible anymore. This means that  this  form  of
              the  command is for the initalization of the client before it use.  The command forcing a con-tact contact
              tact with the name service are

              bind

              release

              search

              server_protocol

              server_features


CONNECTION HANDLING
       The client automatically connects to the service when one of the commands below is run for the  first
       time, or whenever one of the commands is run after the connection was lost, when it was lost.


       bind

       release

       search

       server_protocol

       server_features


       Since  version  0.2  of  the  client  it will generate an event when the connection is lost, allowing
       higher layers to perform additional actions. This is done via the support package  uevent.  This  and
       all other name service related packages hereby reserve the uevent-tag nameserv. All their events will
       be posted to that tag.

EVENTS
       This package generates only one event, lost-connection. The detail information provided to that event
       is  a  Tcl  dictionary.  The only key contained in the dictionnary is reason, and its value will be a
       string describing why the connection was lost.  This string is supplied by the underlying  communica-tion communication
       tion package, i.e. comm.

OPTIONS
       The  options supported by the client are for the specification of which name service to contact, i.e.
       of the location of the name service.  They are:

       -host name|ipaddress
              This option specifies the host name service to contact is running on, either by  name,  or  by
              ipaddress.  The  initial  default  is localhost, i.e. it is expected to contact a name service
              running on the same host as the application using this package.

       -port number
              This option specifies the port the name service to contact is listening on. It  has  to  be  a
              positive  integer number (> 0) not greater than 65536 (unsigned short). The initial default is
              the number returned by the  command  ::nameserv::common::port,  as  provided  by  the  package
              ::nameserv::common.


ASYNCHRONOUS AND CONTINUOUS SEARCHES
       Asynchronous  and  continuous  searches  are  invoked by using either option -async or -continuous as
       argument to the command ::nameserv::search.

       Note that these two options are supported if and only if the service the client is connected to  sup-ports supports
       ports  the protocol feature Search/Continuous. The service provided by the package ::nameserv::server
       does this since version 0.3.

       For such searches the result of the search command is the Tcl command of an object holding the actual
       result. The API provided by these objects is:

       Options:

              -command command_prefix
                     This  option  has  to  be set if a user of the result object wishes to get asynchronous
                     notifications when the search result or changes to it arrive.

                     Note that while it is possible to poll for the arrival of the initial search result via
                     the  method filled, and for subsequent changes by comparing the output of method getall
                     against a saved copy, this is not the recommended behaviour. Setting the -command call-back callback
                     back and processing the notifications as they arrive is much more efficient.

                     The  command_prefix  is  called with two arguments, the type of change, and the data of
                     the change. The type is either add or remove, indicating new  data,  or  deleted  data,
                     respectively.   The data of the change is always a dictionary listing the added/removed
                     names and their associated data.

                     The first change reported for a search is always the set of  matching  entries  at  the
                     time of the search.

       Methods:

              $result destroy
                     Destroys the object and cancels any continuous monitoring of the service the object may
                     have had active.

              $result filled
                     The result is a boolean value indicating whether the search result has already  arrived
                     (True), or not (False).

              $result get name
                     Returns the data associated with the given name at bind-time.

              $result names
                     Returns  a list containing all names known to the object at the time of the invokation.

              $result size
                     Returns an integer value specifying the size of the result at the time of  the  invoka-tion. invokation.
                     tion.

              $result getall ?pattern?
                     Returns  a  dictionary containing the search result at the time of the invokation, map-ping mapping
                     ping the matching names to the data associated with them at bind-time.


HISTORY
       0.3.1  Fixed SF Bug 1954771.

       0.3    Extended the client with the ability to perform asynchronous and continuous searches.

       0.2    Extended the client with the ability to generate events when it loses its  connection  to  the
              name service. Based on package uevent.

       0.1    Initial implementation of the client.


BUGS, IDEAS, FEEDBACK
       This  document,  and  the  package  it  describes,  will undoubtedly contain bugs and other problems.
       Please  report  such  in  the  category  nameserv  of  the   Tcllib   SF   Trackers   [http://source -
       forge.net/tracker/? group_id=12883].   Please  also report any ideas for enhancements you may have for
       either package and/or documentation.

SEE ALSO
       nameserv::common(n), nameserv::server(n)

KEYWORDS
       client, name service

CATEGORY
       Networking

COPYRIGHT
       Copyright (c) 2007-2008 Andreas Kupries <andreas_kupries@users.sourceforge.net>




nns                                                 0.4.2                                        nameserv(n)