1[manpage_begin nameserv n 0.4.2] 2[copyright {2007-2008 Andreas Kupries <andreas_kupries@users.sourceforge.net>}] 3[moddesc {Name service facility}] 4[titledesc {Name service facility, Client}] 5[category Networking] 6[require Tcl 8.4] 7[require nameserv [opt 0.4.2]] 8[require comm] 9[require logger] 10[keywords {name service} client] 11[see_also nameserv::common(n)] 12[see_also nameserv::server(n)] 13[description] 14 15Please read [term {Name service facility, introduction}] first. 16 17[para] 18 19This package provides a client for the name service facility 20implemented by the package [package nameserv::server]. 21 22[para] 23 24This service is built in top of and for the package [package comm]. 25It has nothing to do with the Internet's Domain Name System. If the 26reader is looking for a package dealing with that please see Tcllib's 27packages [package dns] and [package resolv]. 28 29[section API] 30 31The package exports eight commands, as specified below: 32 33[list_begin definitions] 34 35[call [cmd ::nameserv::bind] [arg name] [arg data]] 36 37The caller of this command registers the given [arg name] as its name 38in the configured name service, and additionally associates a piece of 39[arg data] with it. The service does nothing with this information 40beyond storing it and delivering it as part of search results. The 41meaning is entirely up to the applications using the name service. 42 43[para] 44 45A generally useful choice would for example be an identifier for a 46communication endpoint managed by the package [package comm]. Anybody 47retrieving the name becomes immediately able to talk to this endpoint, 48i.e. the registering application. 49 50[para] 51 52Of further importance is that a caller can register itself under more 53than one name, and each name can have its own piece of [arg data]. 54 55[para] 56 57Note that the name service, and thwerefore this command, will throw an 58error if the chosen name is already registered. 59 60 61[call [cmd ::nameserv::release]] 62 63Invoking this command releases all names (and their data) registered 64by all previous calls to [cmd ::nameserv::bind] of this client. Note 65that the name service will run this command implicitly when it loses 66the connection to this client. 67 68 69[call [cmd ::nameserv::search] [opt [option -async]|[option -continuous]] [opt [arg pattern]]] 70 71This command searches the name service for all registered names 72matching the specified glob-[arg pattern]. If not specified the 73pattern defaults to [const *], matching everything. The result of the 74command is a dictionary mapping the matching names to the data 75associated with them at [term bind]-time. 76 77[para] 78 79If either option [option -async] or [option -continuous] were 80specified the result of this command changes and becomes the Tcl 81command of an object holding the actual result. 82 83These two options are supported if and only if the service the client 84is connected to supports the protocol feature 85[term Search/Continuous]. 86 87[para] 88 89For [option -async] the result object is asynchronously filled with 90the entries matching the pattern at the time of the search and then 91not modified any more. 92 93The option [option -continuous] extends this behaviour by additionally 94continuously monitoring the service for the addition and removal of 95entries which match the pattern, and updating the object's contents 96appropriately. 97 98[para] 99 100[emph Note] that the caller is responsible for configuring the object 101with a callback for proper notification when the current result (or 102further changes) arrive. 103 104[para] 105 106For more information about this object see section 107[sectref {ASYNCHRONOUS AND CONTINUOUS SEARCHES}]. 108 109 110[call [cmd ::nameserv::protocol]] 111 112This command returns the highest version of the name service protocol 113supported by the package. 114 115 116[call [cmd ::nameserv::server_protocol]] 117 118This command returns the highest version of the name service protocol 119supported by the name service the client is currently connected to. 120 121 122[call [cmd ::nameserv::server_features]] 123 124This command returns a list containing the names of the features of 125the name service protocol which are supported by the name service the 126client is currently connected to. 127 128 129[call [cmd ::nameserv::cget] [option -option]] 130 131This command returns the currently configured value for the specified 132[option -option]. The list of supported options and their meaning can 133be found in section [sectref OPTIONS]. 134 135[call [cmd ::nameserv::configure]] 136 137In this form the command returns a dictionary of all supported 138options, and their current values. The list of supported options and 139their meaning can be found in section [sectref OPTIONS]. 140 141 142[call [cmd ::nameserv::configure] [option -option]] 143 144In this form the command is an alias for 145"[cmd ::nameserv::cget] [option -option]]". 146 147The list of supported options and their meaning can be found in 148section [sectref OPTIONS]. 149 150 151[call [cmd ::nameserv::configure] "[option -option] [arg value]..."] 152 153In this form the command is used to configure one or more of the 154supported options. At least one option has to be specified, and each 155option is followed by its new value. 156 157The list of supported options and their meaning can be found in 158section [sectref OPTIONS]. 159 160[para] 161 162This form can be used only as long as the client has not contacted the 163name service yet. After contact has been made reconfiguration is not 164possible anymore. This means that this form of the command is for the 165initalization of the client before it use. 166 167The command forcing a contact with the name service are 168 169[list_begin commands] 170[cmd_def bind] 171[cmd_def release] 172[cmd_def search] 173[cmd_def server_protocol] 174[cmd_def server_features] 175[list_end] 176[list_end] 177 178 179[section {CONNECTION HANDLING}] 180 181The client automatically connects to the service when one of the 182commands below is run for the first time, or whenever one of the 183commands is run after the connection was lost, when it was lost. 184 185[para] 186[list_begin commands] 187[cmd_def bind] 188[cmd_def release] 189[cmd_def search] 190[cmd_def server_protocol] 191[cmd_def server_features] 192[list_end] 193[para] 194 195Since version 0.2 of the client it will generate an event when the 196connection is lost, allowing higher layers to perform additional 197actions. This is done via the support package [package uevent]. This 198and all other name service related packages hereby reserve the 199uevent-tag [term nameserv]. All their events will be posted to that 200tag. 201 202[section EVENTS] 203 204This package generates only one event, [term lost-connection]. The 205detail information provided to that event is a Tcl dictionary. The 206only key contained in the dictionnary is [const reason], and its value 207will be a string describing why the connection was lost. 208 209This string is supplied by the underlying communication package, 210i.e. [package comm]. 211 212 213[section OPTIONS] 214 215The options supported by the client are for the specification of which 216name service to contact, i.e. of the location of the name service. 217 218They are: 219 220[list_begin options] 221[opt_def -host [arg name]|[arg ipaddress]] 222 223This option specifies the host name service to contact is running on, 224either by [arg name], or by [arg ipaddress]. The initial default is 225[const localhost], i.e. it is expected to contact a name service 226running on the same host as the application using this package. 227 228 229[opt_def -port [arg number]] 230 231This option specifies the port the name service to contact is 232listening on. It has to be a positive integer number (> 0) not greater 233than 65536 (unsigned short). The initial default is the number 234returned by the command [cmd ::nameserv::common::port], as provided by 235the package [package ::nameserv::common]. 236 237[list_end] 238 239 240[section {ASYNCHRONOUS AND CONTINUOUS SEARCHES}] 241 242Asynchronous and continuous searches are invoked by using either 243option [option -async] or [option -continuous] as argument to the 244command [cmd ::nameserv::search]. 245 246[para] 247 248[emph Note] that these two options are supported if and only if the 249service the client is connected to supports the protocol feature 250[term Search/Continuous]. The service provided by the package 251[package ::nameserv::server] does this since version 0.3. 252 253[para] 254 255For such searches the result of the search command is the Tcl command 256of an object holding the actual result. The API provided by these 257objects is: 258 259[list_begin definitions] 260 261[def Options:] 262[list_begin options] 263[opt_def -command [arg command_prefix]] 264 265This option has to be set if a user of the result object wishes to get 266asynchronous notifications when the search result or changes to it 267arrive. 268 269[para] 270 271[emph Note] that while it is possible to poll for the arrival of the 272initial search result via the method [method filled], and for 273subsequent changes by comparing the output of method [method getall] 274against a saved copy, this is not the recommended behaviour. Setting 275the [option -command] callback and processing the notifications as 276they arrive is much more efficient. 277 278[para] 279 280The [arg command_prefix] is called with two arguments, the type of 281change, and the data of the change. The type is either [const add] or 282[const remove], indicating new data, or deleted data, respectively. 283The data of the change is always a dictionary listing the 284added/removed names and their associated data. 285 286[para] 287 288The first change reported for a search is always the set of matching 289entries at the time of the search. 290 291[list_end] 292 293[def Methods:] 294[list_begin definitions] 295 296[call [cmd \$result] [method destroy]] 297 298Destroys the object and cancels any continuous monitoring of the 299service the object may have had active. 300 301 302[call [cmd \$result] [method filled]] 303 304The result is a boolean value indicating whether the search result has 305already arrived ([const True]), or not ([const False]). 306 307[call [cmd \$result] [method get] [arg name]] 308 309Returns the data associated with the given [arg name] at 310[term bind]-time. 311 312[call [cmd \$result] [method names]] 313 314Returns a list containing all names known to the object at the time of 315the invokation. 316 317[call [cmd \$result] [method size]] 318 319Returns an integer value specifying the size of the result at the time 320of the invokation. 321 322[call [cmd \$result] [method getall] [opt [arg pattern]]] 323 324Returns a dictionary containing the search result at the time of the 325invokation, mapping the matching names to the data associated with 326them at [term bind]-time. 327 328[list_end] 329[list_end] 330 331 332[section HISTORY] 333[list_begin definitions] 334[def 0.3.1] 335Fixed SF Bug 1954771. 336 337[def 0.3] 338Extended the client with the ability to perform asynchronous and 339continuous searches. 340 341[def 0.2] 342Extended the client with the ability to generate events when it loses 343its connection to the name service. Based on package [package uevent]. 344 345[def 0.1] 346Initial implementation of the client. 347[list_end] 348 349[section {BUGS, IDEAS, FEEDBACK}] 350 351This document, and the package it describes, will undoubtedly contain 352bugs and other problems. 353 354Please report such in the category [emph nameserv] of the 355[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. 356 357Please also report any ideas for enhancements you may have for either 358package and/or documentation. 359 360[manpage_end] 361