# =========== Header ===========
# File:					Using The Name Server
# Project:				(Newton Bowels)
# Written by:			Paul Guyot (pguyot@kallisys.net)
#
# Created on:			03/15/2002
# Internal version:		1
# Tab size:				4 spaces
#
# Copyright:			© 2002 by Paul Guyot.
# 						All rights reserved worldwide.
# ===========

# =========== Change History ===========
# 03/15/2002	v1	[PG]	Creation of the file
# ===========

Abstract
========

This note explains how to use a built-in feature of NewtonOS, the name server.
It comes with a sample program, GetCardInfo (with source code, requires NCT
and NTK).

Platforms
=========

This applies to 2.x Newtons at least (and very probably to any Newton)

Introduction
============

You can't have global variables in native code on NewtonOS. I mean, the OS has
some global read/write location, but your programs cannot have any.
The OS uses intensively something called the NameServer that you can use as a
way to share informations between various parts of your program.
Note: this is one of the ways, several other methods are available.

What is the Name Server?
========================

The NameServer can be considered as an object responsible for a hash table.
Entries in the table are identified by a key composed of two strings (of any
size I guess). The data for entries is made of two longs.

The reason why the keys are made of two strings and the data is available as
two longs is that the name server is mainly used to work with protocol classes
(although the OS uses it for other purposes as well) and the first string is
the implementation class, the second string the interface class, the first
long the object ID or the pointer to the class and the second long the version
of the interface. But you are not bound to use it this way.

The Name Server also provides a resource conflict mechanism and lets you wait
until some name is registered or unregistered. This tech note won't detail all
these APIs.

How to use the Name Server?
===========================

This is rather straightforward. You need to include NameServer.h header for
the class definitions.

Somewhere in your code, you need to register some name in the name server.
Create an instance of the Name Server with:

	TUNameServer NameServer;

Then tells it to register your name with:

	NewtonErr theErr =
		NameServer.RegisterName(
						kSomeString,
						kSomeOtherString,
						SomeLong,
						SomeOtherLong );

I suggest to put as the second string your developer signature, and as the
second long a version identifying the structure.

Then, somewhere else in your code, create an instance of the name server the
same way and retrieve your two longs with:

	TUNameServer NameServer;	// name server instance.
	ULong theResult;
	ULong theVersion;
	NewtonErr theErr =
		NameServer.Lookup(
						kSomeString,
						kSomeOtherString,
						&theResult,
						&theVersion );

The error that the name server will most probably do is
kError_Not_Registered to tell you that this key doesn't exist in the hash
table.

Once you created your entry, it's a good idea to release it when you no
longer need it (e.g. when your package is deleted/frozen/on a card that is
removed). To do so, just create a name server instance and call
UnRegisterName method.

	TUNameServer NameServer;
	NewtonErr theErr =
		NameServer.UnRegisterName( kSomeString, kSomeOtherString );

You will probably not want the task you are running in to be blocked until a
given name is allocated or released. Just in case, there are the
WaitForRegister and WaitForUnregister methods which are pretty easy to use.

The Sample Project
==================

The sample project shows how to do these basic operations by having a TLog
object shared between various parts of the program (and various tasks).
Please note that this project is really simple, and especially, it doesn't
use the OS classes for its shared memory zone. This isn't required here
because both tasks are in the same domain, but you might need it.

History
=======

I have been using the name server method to share data between tasks for
several years. GetCardInfo project was written to get someone's card
Product String, and sent it to Laurent Daudelin to illustrate how to use
the name server.

## =============================================================================== ##
## Eudaemonic research proceeded with the casual mania peculiar to this part of    ##
## the world.  Nude sunbathing on the back deck was combined with phone calls to   ##
## Advanced Kinetics in Costa Mesa, American Laser Systems in Goleta, Automation   ##
## Industries in Danbury, Connecticut, Arenberg Ultrasonics in Jamaica Plain,      ##
## Massachusetts, and Hewlett Packard in Sunnyvale, California, where Norman       ##
## Packard's cousin, David, presided as chairman of the board. The trick was to    ##
## make these calls at noon, in the hope that out-to-lunch executives would return ##
## them at their own expense.  Eudaemonic Enterprises, for all they knew, might be ##
## a fast-growing computer company branching out of the Silicon Valley.  Sniffing  ##
## the possibility of high-volume sales, these executives little suspected that    ##
## they were talking on the other end of the line to a naked physicist crazed      ##
## over roulette.                                                                  ##
##                 -- Thomas Bass, "The Eudaemonic Pie"                            ##
## =============================================================================== ##