Ubuntu Manpage: nameserv - Name service facility, Client

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
       nameserv::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 service, 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 managed 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. 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.

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 supported 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 package.

::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 values. 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 contact with the name service are

bind

release

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 communication 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 supports 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 callback 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 invokation.

$result getall ?pattern?
Returns a dictionary containing the search result at the time of the
invokation, mapping 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   Trackers
       [http://core.tcl.tk/tcllib/reportlist].  Please also report any ideas for enhancements you
       may have for either package and/or documentation.

       When proposing code changes, please provide unified diffs, i.e the output of diff -u.

       Note further that attachments are strongly preferred over inlined patches. Attachments can
       be  made  by going to the Edit form of the ticket immediately after its creation, and then
       using the left-most button in the secondary navigation bar.

KEYWORDS

       client, name service

COPYRIGHT

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