1nameserv::protocol(n)        Name service facility       nameserv::protocol(n)
2
3
4
5______________________________________________________________________________
6

NAME

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

SYNOPSIS

11       Bind name data
12
13       Release
14
15       Search pattern
16
17       ProtocolVersion
18
19       ProtocolFeatures
20
21       Search/Continuous/Start tag pattern
22
23       Search/Continuous/Stop tag
24
25       Search/Continuous/Change tag add|remove response
26
27______________________________________________________________________________
28

DESCRIPTION

30       The packages nameserv::server, nameserv, and nameserv::common provide a
31       simple unprotected name service facility for use in small trusted envi‐
32       ronments.
33
34       Please read Name service facility, introduction first.
35
36       This  document contains the specification of the network protocol which
37       is used by client and server to talk to each other, enabling  implemen‐
38       tations of the same protocol in other languages.
39

NANO NAME SERVICE PROTOCOL VERSION 1

41       This  protocol  defines  the basic set of messages to be supported by a
42       name service, also called the Core feature.
43
44   BASIC LAYER
45       The basic communication between client and server  is  done  using  the
46       remote-execution protocol specified by the Tcl package comm.  The rele‐
47       vant document specifying its  on-the-wire  protocol  can  be  found  in
48       comm_wire.
49
50       All the scripts exchanged via this protocol are single commands in list
51       form and thus can be interpreted as plain messages instead  of  as  Tcl
52       commands.  The  commands/messages specified in the next section are the
53       only commands understood by the server-side. Command and variable  sub‐
54       stitutions  are not allowed within the messages, i.e. arguments have to
55       be literal values.
56
57       The protocol is synchronous. I.e. for each message sent a  response  is
58       expected, and has to be generated. All messages are sent by the client.
59       The server does not sent messages, only responses to messages.
60
61   MESSAGE LAYER
62       Bind name data
63              The client sends this message when it registers  itself  at  the
64              service  with a name and some associated data. The server has to
65              send an error response if the name is already in use.  Otherwise
66              the response has to be an empty string.
67
68              The server has to accept multiple names for the same client.
69
70       Release
71              The  client  sends  this  message  to unregister all names it is
72              known under at the service. The response  has  to  be  an  empty
73              string, always.
74
75       Search pattern
76              The  client  sends  this message to search the service for names
77              matching the glob-pattern. The response has to be  a  dictionary
78              containing  the  matching names as keys, and mapping them to the
79              data associated with it at Bind-time.
80
81       ProtocolVersion
82              The client sends this message to query the service for the high‐
83              est  version  of  the  name  service  protocol  it supports. The
84              response has to be a positive integer number.
85
86              Servers supporting only Nano Name  Service  Protocol  Version  1
87              have to return 1.
88
89       ProtocolFeatures
90              The  client sends this message to query the service for the fea‐
91              tures of the name service protocol it supports. The response has
92              to be a list containing feature names.
93
94              Servers  supporting  only  Nano  Name Service Protocol Version 1
95              have to return {Core}.
96
98       This protocol defines an extended set of messages to be supported by  a
99       name  service,  also called the Search/Continuous feature. This feature
100       defines additional messages between client and server, and is otherwise
101       identical  to  version  1 of the protocol. See the last section for the
102       details of our foundation.
103
104       A  service  supporting  this  feature  has  to  put  the  feature  name
105       Search/Continuous  into  the  list  of features returned by the message
106       ProtocolFeatures.
107
108       For this extension the protocol is asynchronous. No direct response  is
109       expected  for  any  of  the  messages in the extension. Furthermore the
110       server will  start  sending  messages  on  its  own,  instead  of  only
111       responses  to  messages,  and the client has to be able to handle these
112       notifications.
113
114       Search/Continuous/Start tag pattern
115              The client sends this message to start searching the service for
116              names  matching  the  glob-pattern.   In contrast to the regular
117              Search request this one asks the server to continuously  monitor
118              the  database  for  the addition and removal of matching entries
119              and to notify the client of all  such  changes.  The  particular
120              search is identified by the tag.
121
122              No  direct response is expected, rather the clients expect to be
123              notified of changes via explicit  Search/Continuous/Result  mes‐
124              sages generated by the service.
125
126              It  is  further  expected  that  the  tag  information is passed
127              unchanged to the Search/Continuous/Result messages. This tagging
128              of  the  results  enables clients to start multiple searches and
129              distinguish between the different results.
130
131       Search/Continuous/Stop tag
132              The client sends this message  to  stop  the  continuous  search
133              identified by the tag.
134
135       Search/Continuous/Change tag add|remove response
136              This  message is sent by the service to clients with active con‐
137              tinuous searches to transfer found changes. The first such  mes‐
138              sage for a new continuous search has to contains the current set
139              of matching entries.
140
141              To ensure this a service has to generate an add-message with  an
142              empty response if there were no matching entries at the time.
143
144              The  response  has  to  be  a dictionary containing the matching
145              names as keys, and mapping them to the data associated  with  it
146              at Bind-time.  The argument coming before the response tells the
147              client whether the names in the response were added  or  removed
148              from the service.
149

BUGS, IDEAS, FEEDBACK

151       This  document,  and the package it describes, will undoubtedly contain
152       bugs and other problems.  Please report such in the  category  nameserv
153       of  the Tcllib Trackers [http://core.tcl.tk/tcllib/reportlist].  Please
154       also report any ideas for enhancements you may have for either  package
155       and/or documentation.
156
157       When proposing code changes, please provide unified diffs, i.e the out‐
158       put of diff -u.
159
160       Note further that  attachments  are  strongly  preferred  over  inlined
161       patches.  Attachments  can  be  made  by  going to the Edit form of the
162       ticket immediately after its creation, and  then  using  the  left-most
163       button in the secondary navigation bar.
164

SEE ALSO

166       comm_wire(n), nameserv(n), nameserv::server(n)
167

KEYWORDS

169       comm, name service, protocol
170

CATEGORY

172       Networking
173
175       Copyright (c) 2007-2008 Andreas Kupries <andreas_kupries@users.sourceforge.net>
176
177
178
179
180tcllib                                0.1                nameserv::protocol(n)
Impressum