Ubuntu Manpage: nameserv::protocol - Name service facility, client/server protocol

NAME

       nameserv::protocol - Name service facility, client/server protocol

SYNOPSIS

       Bind name data

       Release

       Search pattern

       ProtocolVersion

       ProtocolFeatures

       Search/Continuous/Start tag pattern

       Search/Continuous/Stop tag

       Search/Continuous/Change tag add|remove response

________________________________________________________________________________________________________________

DESCRIPTION

       The  packages  nameserv::server, nameserv, and nameserv::common provide a simple unprotected name service
       facility for use in small trusted environments.

       Please read Name service facility, introduction first.

       This document contains the specification of the network protocol which is used by client  and  server  to
       talk to each other, enabling implementations of the same protocol in other languages.

NANO NAME SERVICE PROTOCOL VERSION 1

       This  protocol  defines the basic set of messages to be supported by a name service, also called the Core
       feature.

   BASIC LAYER
       The basic communication between client and server is done using the remote-execution  protocol  specified
       by  the  Tcl  package  comm.   The  relevant document specifying its on-the-wire protocol can be found in
       comm_wire.

       All the scripts exchanged via this protocol are single commands in list form and thus can be  interpreted
       as plain messages instead of as Tcl commands. The commands/messages specified in the next section are the
       only commands understood by the server-side. Command and variable substitutions are  not  allowed  within
       the messages, i.e. arguments have to be literal values.

       The  protocol is synchronous. I.e. for each message sent a response is expected, and has to be generated.
       All messages are sent by the client.  The server does not sent messages, only responses to messages.

   MESSAGE LAYER
       Bind name data
              The client sends this message when it registers itself  at  the  service  with  a  name  and  some
              associated data. The server has to send an error response if the name is already in use. Otherwise
              the response has to be an empty string.

              The server has to accept multiple names for the same client.

       Release
              The client sends this message to unregister all names it  is  known  under  at  the  service.  The
              response has to be an empty string, always.

       Search pattern
              The  client  sends  this  message  to  search the service for names matching the glob-pattern. The
              response has to be a dictionary containing the matching names as keys, and  mapping  them  to  the
              data associated with it at Bind-time.

       ProtocolVersion
              The  client  sends  this  message to query the service for the highest version of the name service
              protocol it supports. The response has to be a positive integer number.

              Servers supporting only Nano Name Service Protocol Version 1 have to return 1.

       ProtocolFeatures
              The client sends this message to query the service for the features of the name  service  protocol
              it supports. The response has to be a list containing feature names.

              Servers supporting only Nano Name Service Protocol Version 1 have to return {Core}.

NANO NAME SERVICE PROTOCOL EXTENSION: CONTINUOUS SEARCH

This protocol defines an extended set of messages to be supported by a name service, also called the
Search/Continuous feature. This feature defines additional messages between client and server, and is
otherwise identical to version 1 of the protocol. See the last section for the details of our foundation.

A service supporting this feature has to put the feature name Search/Continuous into the list of features
returned by the message ProtocolFeatures.

For this extension the protocol is asynchronous. No direct response is expected for any of the messages
in the extension. Furthermore the server will start sending messages on its own, instead of only
responses to messages, and the client has to be able to handle these notifications.

Search/Continuous/Start tag pattern
The client sends this message to start searching the service for names matching the glob-pattern.
In contrast to the regular Search request this one asks the server to continuously monitor the
database for the addition and removal of matching entries and to notify the client of all such
changes. The particular search is identified by the tag.

No direct response is expected, rather the clients expect to be notified of changes via explicit
Search/Continuous/Result messages generated by the service.

It is further expected that the tag information is passed unchanged to the
Search/Continuous/Result messages. This tagging of the results enables clients to start multiple
searches and distinguish between the different results.

Search/Continuous/Stop tag
The client sends this message to stop the continuous search identified by the tag.

Search/Continuous/Change tag add|remove response
This message is sent by the service to clients with active continuous searches to transfer found
changes. The first such message for a new continuous search has to contains the current set of
matching entries.

To ensure this a service has to generate an add-message with an empty response if there were no
matching entries at the time.

The response has to be a dictionary containing the matching names as keys, and mapping them to the
data associated with it at Bind-time. The argument coming before the response tells the client
whether the names in the response were added or removed from the service.

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

       comm, name service, protocol

COPYRIGHT

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