Sie sind auf Seite 1von 32

Notification Service Transfer Protocol (NSTP)

version 1.0 November 15, 1996

Mark Day

John Patterson

Jakov Kucan 1

2

Wei Meng Chee

David Mitchell

Lotus Development Corporation 55 Cambridge Parkway Cambridge, MA 02142

1

Introduction

This document is a specification ofthe messages that can be sent by a client or server using the Notification Service Transfer Protocol(NSTP). It is intended to be a complete specification.

The document consists of 6 parts:

1. this introduction,

2. a description of the model of service provided by the protocol,

3. assumptions about the infrastructure made by the protocol,

4. a specification of the structure of protocol messages,

5. a specification of the meaning of protocol messages, and

6. a description of conventions that are not required for a correct implementation of the protocol, but that are helpful for interoperabilityof applications built using the protocol.

We put explanatory comments and rationale into paragraphs that look like this.

NSTP Specification 1.0

2 Model of Service

NSTP is intended to support the construction ofsynchronous groupware. In synchronous groupware, two or more people collaborate at what they perceive to be “the same time”. Each person’s actions within the collaboration are mediated by some software system. We refer to the parts of the software system “in front of each person” as the clients. We refer to the persons themselves asusers. Each user has a unique name used for the collaboration; we refer to that name as ausername. The clients typically need to coordinate some parts of their state with each other. They achieve this coordination via anotification service, which is implemented by one or morenotification servers. NSTP is a definition of a particular notification service.

NSTP provides a model in which collaboration-critical shared state is stored at the server, where it can be changed by clients. Each change to this shared state causes the server to deliver notifications of the change to interested clients. An unusual aspect ofNSTP is that it supports centralized state with decentralized semantics. That is, the server does not understand what the shared state means for the clients; it simply accepts updates to the state and forwards notice of the changes to interested clients.

Because the server does not attempt to interpret the state shared by clients, client and server communicate in terms of a relatively simple universe of discourse, consisting primarily ofThings and Places. A Thing is

a named piece of state; in general, the server understands the name but not the value. (There are a few

predefined Things that control aspects of server behavior; the values of those Thingsare interpreted by the

server).

Every Thing is contained within one and only one Place, which clients canenter or leave. A client that has entered a Place is said to bepresent in the Place until it leaves. A client that is present in a Place receives notifications of changes to the Things in that Place; a client not present in a Place receives no such notifications. A single client can be present in multiple Places simultaneously, but cannot be present in any one Place more than once.

The design of the protocol adheres to the following principles:

Notifications are symmetric: the client causing the notification receives the notification just as

every other client in the Place does. Responses are sufficient: a client knows enough from a response to a request to continue correctly

without waiting for a notification. Notifications are local: no client outside a Place receives notifications from that Place.

Although NSTP insists that clients outside a Place cannot receive notifications for the Things in that Place,

it is flexible about whether the values of those Things can be read or written from outside a Place. Those

Things that are accessible from outside the Place are said to be accessed through theFacade of the Place.

The reader seeking a lengthier introduction to the concepts behind the protocol should read the paper “Notification Servers for Synchronous Groupware.” [PDK96]

2

NSTP Specification 1.0

3

Infrastructure

The NSTP protocol is defined in terms of messages that are exchanged between client and server. These messages are assumed to be carried via a transport protocol such asTCP that provides a reliable stream of bytes. NSTP does not have mechanisms for sequencing, error detection, retransmission, or flow control. The base data types transmitted are bytes (octets), 2-byteUnicode characters [U96], and 4-byte unsigned integers (the integer encoded into bytes in so-called network order).NSTP is intended to be usable with any reliable bytestream protocol.

3

NSTP Specification 1.0

4 Structure of Protocol

Each message consists of a fixed-length header and a variable-length body. The header contains all the information necessary to pre-parse and dispatch the message on both the server and the client side. The body contains additional informationthat varies with each message.

4.1

Header

The header of a message takes the following form:

K

 

A

R

     

i

t

s

n

o

v

d

Op

m

d

ID

Place

Body size

Kind (1 byte): this field specifies thekind of message, which characterizes the style of communication being used. The protocol distinguishes between two forms of client-to-server message (collectively called requests) and five forms of server-to-client message. The kind field contains a single value, which is referred to subsequently by the mnemonic ofC,E,N,Q,R,S, or X. The following table explains the encoding:

Value of

Mnemonic

Meaning

Kind field

1

C

Challenge: a special response to a Q request, indicating that the server is requesting the client to provide additional credentials.

2

E

Error: sent by the server in response to a Q request that has failed.

3

N

Notification: a message from the server indicating that one or more Things in a Place have changed in some way.

4

Q

Query or synchronous request: a request that expects a response, indicating that it has succeeded (R), must provide more information (C), or has failed (E).

5

R

Reply: sent by the server in response to a Q request that has succeeded.

6

S

Send or asynchronous request: a request that does not expect an acknowledgementfrom the server in the normal case.

7

X

Asynchronous error: sent by the server when a previous S request has failed.

Operation (1 byte): this field is used to name the request orkind of notification (see table below).The name of the operation is also referred to as the message’sopcode. For historical reasons, theseopcodes have mnemonics consisting of 3 or 4 characters, which are used throughout the specification.

Each row summarizes an opcode. A full description of the semantics of eachopcode appears later in this document. The columns labeledkind indicate the kind of message that can be sent, either from client to server or vice-versa. Similarly, the columns labeledPlace? indicate whether that message has a Place handle or nothing in its place field when sent, either from client to server or vice-versa. The column labeled notify indicates the kind of notification caused by the operation.

4

NSTP Specification 1.0

 

client-to-

server-to-

 

server

client

operation

hex

description

kind

place

kind

place

notify

code

?

?

INIT

1

SignOn

Q

 

C|R|E

   

QUIT

90

SignOff

Q

 

R|E

   

NEW

10

CreatePlace

Q

 

R|E

 

GETP

20

GetPlaceByName

Q

 

R|E

 

GPE

21

GetPlaceAndEnter

Q

 

C|R|E

MADE *

GPEV

22

GetPlaceEnterGetValues

Q

 

C|R|E

MADE *

ENTR

23

EnterPlace

Q

C|R|E

MADE *

ENGV

24

EnterPlaceGetValues

Q

C|R|E

MADE *

MAKE

30

CreateThings

Q

R|E

MADE

S

X

DEL

31

DeleteThings

Q

R|E

DELD

S

X

GTT

40

GetThings

Q

R|E

 

GTV

41

GetThingValues

Q

R|E

 

STV

50

SetThingValues

Q

R|E

CHGD

S

X

GTA

42

GetThingAttributes

Q

R|E

 

LOCK

60

LockThing (non-blocking)

Q

R|E

**

LCKB

61

LockThing (blocking)

Q

R|E

**

ULCK

62

UnlockThings

Q

R|E

***

SNTC

70

Send Notice

Q

R|E

NTC or

BNTC

S

X

KILL

11

DestroyPlace

Q

R|E

KILD

EXIT

25

LeavePlace

Q

R|E

DELD *

MADE

80

ThingCreated

   

N

 

DELD

81

ThingDeleted

   

N

 

CHGD

82

ThingChanged

   

N

 

KILD

83

PlaceDestroyed

   

N

 

NTC

84

Notice

   

N

 

BNTC

85

Broadcast Notice

   

N

 

* Implicit creation (or deletion) of user-Thing at entry (or exit). ** When a Thing has been locked, notifications are not sent until it has been unlocked. *** Unlocking a Thing may cause notifications to be sent if it was previously modified.

Atom (1 byte): This field is normally zero (00 16 ). If it has the value one (01 16 ), the server is allowed to treat the request non-atomically, so that operations on some Things can succeed while others fail. A server carrying out a non-atomic request may send a complex error report back to the client, indicating which

5

NSTP Specification 1.0

operations failed. A client setting this field to allow non-atomic operations must be prepared to deal with such a report.

In this version of the protocol, ULCK is the only non-atomic operation whose return value is defined. We expect that a future version will include a complete specification of the return values and errors sent when the Atom field is non-zero.

For the opcode ULCK (unlock), the operation is non-atomic regardless of the setting of the Atom field.

All other values of this field are reserved for future use.

Note that the server is allowed to treat the request non-atomically, but is not required to. The exception is the ULCK operation, which is always non-atomic. There is no technique currently defined in the protocol for determining whether a server implements non-atomic requests.

Reserved (1 byte): reserved for future use.

In addition to saving some room in the header for future use, this reserved byte means that the remaining fields in the header are aligned on 4-byte boundaries if the header as a whole is aligned on a 4-byte boundary. This can make a difference to performance on some machines (e.g. Digital Alpha, Intel Pentium Pro)

Id (4 bytes): this field is set by the client when sending a requestQ( or S) and is copied to the same field of the corresponding reply (C or R) or error (E or X) sent back by the server. In case of a notification (N), this field is the id copied from the request that caused the notification.

In the case of a locked Thing, the id field in the notification depends on the notification delivered. A CHGD notification contains the id of the last STV to affect the Thing before the lock was released. A DELD notification contains the id of the DEL or EXIT causing the Thing to be deleted. A KILD notification contains the id of the KILL causing the Place to be destroyed.

The protocol doesn’t specify how id’s are assigned, nor how to avoid collisions among clients. Clients are free to use any scheme that works for them; the server is unaffected.

Place (4 bytes): this field contains the handle for thePlace the message is referring to.Clients refer to Places in terms of handles assigned by the server. Two different clients may have different handles to refer to the same Place, or the same handle for different Places. A handle is not valid beyond a single client/server session; in particular, a client cannot store a handle in a file and rely on it to refer to the same Place at a later time. Within a single client/server session, both client and server must use a single handle to refer to a single Place.

For example, if a client asks for a Place called “Nirvana” twice within a single session, the server must return the same handle both times. The one exception is if the Place was destroyed and re-created between requests, in which case the two Places named “Nirvana” are not the same Place and so need not have the same handle. Note that in this second case, the server is not required to use a different handle for the new Place than for the destroyed Place.

6

NSTP Specification 1.0

The handle FFFFFFFF 16 is reserved to mean “no handle”.

Except for reserving the value for “no handle”, a server is free to assign handles in any way that it finds convenient and efficient. Handles need not be contiguous integers, nor have any client-intelligible structure. The handle for a destroyed Place may be reused or not, as the server chooses.

Body size (4 byte integer in network byte order): this field specifies the size, in bytes, of the body of the message.

4.2

Body

The body may be up to 4G bytes long.

We do not recommend sending very large bodies. The limit of 4G bytes is due to the 32-bit size field.

Message bodies are not self-describing. In general, it is not possible to decode a message body without some knowledge of the operation field (in the header). There are four kinds of elements in a body: values, tuples, lists, and errors.

4.2.1

Values

An arbitrary binary value (sequence of bytes) consists of an integer followed by data:

length (in bytes) data
length (in bytes)
data

The length is a 4-byte integer in network order. The length describes the number of bytes in the data. We further describe the following specialized values: strings, names, and types. Names and types are themselves specialized strings.

4.2.1.1 Strings

A string is a distinguished form of value. A string is a sequence ofUnicode (two-byte) characters; accordingly, no string may have an odd length.

4.2.1.2 Names

A name is a string that is interpreted by the server to identify one of the following:

a user,

a Place, or

a Thing within a Place.

The protocol requires that names be unique within their scope: each user or Place at a server must have a unique name, and each Thing within a Place must have a unique name. No case conversion is done at the

7

NSTP Specification 1.0

server when determining whether two names are the same, so the name “john” will not match the name “John”.

Names that start with the characters “NS:” are reserved for use by the server. Clients may not create new

entities with names that start with that prefix. The server will reject all attempts to create a new Place or Thing whose name starts with “NS:”. However, clients may use names beginning with “NS:” when finding

or manipulating existing Places and Things.

Because commas are used to delimit elements within lists for the values of the predefined Things, names may not contain commas.

4.2.1.3 Types

A type is a string that may be interpreted by the client or server to determine how to treat a Place, Thing, or

notice. In contrast to names, multiple Places may have the same type, and multiple Things within a Place may have the same type. Multiple notices sent within a Place may have the same type.

Types that start with the characters “NS:” are reserved for the server. A client may use a type that begins with “NS:” if that type is known to the server. A client may not use a server-reserved type that is not known to the server.

For example, a client might well be able to create a Thing whose type is “NS:DefaultThingType”. On the other hand, it is unlikely that a client will be able to create a Thing whose type is “NS:Asparagus” unless the server has been implemented to support vegetable-related Places.

The complete set of types known at a server is implementation-dependent. The protocol does not define a mechanism for determining the set of types known at a server.

4.2.2

Tuples

When several elements are to be sent and the number of elements is known in advance, the collection of elements is described as atuple. For example, any given Thing being created by the server has an

agreed-on representation described elsewhere in this document. The distinct parts of tuplea packed sequentially in the message, in the defined order.

are simply

Numerous data structures are sent as tuples. The most pervasive example is attributes of Things, described

in the next section.

4.2.2.1 Attributes

A Thing consists of a value, a lock, andattributes. The attributes of a Thing include its name, its type, its

read permissions, etc. The attributes of a Thing are immutable, so a client can cache them and be sure that they will not change at the server. Attributes aretransmitted as the followingtuple, consisting of 6 mandatory elements and 3 optional elements.

8

NSTP Specification 1.0

fieldname: encoding

Mnemonic

Value

Meaning

theName: name

 

The name of the Thing

theType: type

 

The type of the Thing

readcode: 4-byte integer

R_FACADE

10

readable from facade [no readstring]

R_PLACE

11

readable only from inside Place [no readstring]

R_THINGNAME

14

readstring contains name of a Thing in this Place

readstring: string [optional]

 

determined by previous field

writecode:4-byte integer

W_FACADE

20

writable from the facade [no writestring]

W_PLACE

21

writable only from inside the Place [no writestring]

W_FINAL

22

final, not writable [no writestring]

W_USERLIST

23

writestring contains comma-separated sequence of usernames allowed to write

W_THINGNAME

24

writestring contains the name of a Thing in this Place

W_SERVER

25

writable only by the server [no writestring]

writestring: string

 

determined by previous field

[optional]

deletecode:4-byte integer

D_PLACE

31

deletable only inside Place [no deletestring]

D_FINAL

32

final, deleted only when Place is destroyed [no deletestring]

D_USERLIST

33

deletestringcontains comma-separated sequence of usernames allowed to delete

D_THINGNAME

34

deletestringcontains the name of a Thing in this Place

D_SERVER

35

deleted only by server [no deletestring]

deletestring:string

determined by previous field

   

[optional]

notifystyle: 4-byte integer

N_CREATE_DELETE

48

notification only when Thing is created or deleted

N_CHANGE

49

notification on creation, value change, or deletion

9

NSTP Specification 1.0

The smallest possible attribute structure consists of the following:

a zero-length name (one 4-byte integer with value zero),

a zero-length type (one 4-byte integer with value zero),

a readcode (one 4-byte integer),

a writecode (one 4-byte integer),

a deletecode(one 4-byte integer),

a notifystyle (one 4-byte integer).

Thus the smallest possible attribute structure requires 6 integers or a total of 24 bytes to be transmitted.

There are 5 codes that require a following string:R_THINGNAME, W_USERLIST, W_THINGNAME, D_USERLIST, and D_THINGNAME. For each such code, a following string must be encoded even if it is an empty string that contains no characters: that is, each of these codes must be followed by an integer encoding the length of the string, even if that integer’s value is zero.

The codes R_THINGNAME, W_THINGNAME, and D_THINGNAME allow the following string to be the name of a Thing. The current protocol does not describe the semantics of these codes in detail. Instead, those codes are reserved for a future version of the protocol that will allow some attributes of a Thing to be determined by the value of a different Thing in the same Place.

4.2.3 Lists

When an operation takes an arbitrary number of arguments, those arguments are represented as follows:

count of items items in the list
count of items
items in the list

The count is a 4-byte integer in network order. Note that it describes thenumber of items following, not their combined length in bytes. The items may be values,tuples, or further nested lists.

4.2.4 Errors

The current protocol does not use any nested lists.

An error body is the body of a message of kind E or X. Itconsists of a 32-bit network-order integererror code, followed by an encodedstring that describes the error condition. Following SMTP [P82], we use numeric codes where the initial digit indicates the class of error, and the second digit indicates the kind of entity to which the error applies. In contrast toSMTP, we use a total of 4 digits in the error code, allowing a two-digit space for error codes for each kind of entity. Also in contrast toSMTP, we use a 32-bit integer rather than ASCII to represent the error code. Note that legal error codes are in the domain 0 to 9999 inclusive.

All of the currently-defined error codes are in the class that SMTP terms “Permanent negative completion reply” and accordingly all of the error codes start with the digit “5”.

10

NSTP Specification 1.0

Syntax errors

Code

Meaning

Caused by

5000

Bad Message Format

Any

5001

Not Legal Command

Any

5002

Not Legal Kind

Any

5003

Short Message

Any

5004

Not Implemented

Any

5005

Can’t Construct Attributes

Any

5006

Can’t Construct Handle

Any

5007

Can’t Construct List

Any

5008

Can’t Construct Name

Any

5009

Can’t Construct Type

Any

5010

Can’t ConstructVal

Any

5011

Can’t Construct String

Any

5012

Can’t Construct Error

Any

Information

Code

Meaning

Caused by

5100

Info Not Available

Not currently used

Connection errors

5200

Connection Closed

Any

5201

Invalid Handle

ENTR, ENGV, MAKE, DEL, GTT, GTV, GTA, STV, LOCK, LCKB, ULCK, EXIT, KILL, SNTC

5202

Logon Rejected

INIT

5203

Logon Technique Not Supported

INIT

5204

Logon Technique Not Supported, List of Supported Techniques Returned

INIT

Server errors

Code

Meaning

Caused by

5300

User Name Conflict

INIT

5301

Place Name Conflict

NEW

5302

User Not Found

INIT

5303

Place Not Found

Any except INIT, QUIT, NEW

5304

Place Creation Not Allowed

NEW

5305

Server Error

Any

11

NSTP Specification 1.0

Place errors

Code

Meaning

Caused by

5400

Thing Name Conflict

MAKE

5401

Thing Not Found

DEL, STV, GTT, GTA, GTV, LOCK, LCKB, ULCK

5402

Entry Not Allowed

ENTR, ENGV, GPE, GPEV

5403

Not In Place

EXIT, KILL, LOCK, LCKB, ULCK

5404

Thing Creation Not Allowed

MAKE

5405

Already In Place

ENTR, ENGV, GPE, GPEV

Thing errors

Code

Meaning

Caused by

5500

Bad Attribute

MAKE

5501

Bad Type

MAKE

5502

No Access

DEL, GTT, GTV, GTA, LOCK, LCKB, ULCK, KILL

5503

Would Block

LOCK

5504

Not Lock Holder

ULCK

5505

Locked

DEL, STV, GTT, GTV

4.3 Arguments, Return Values, and Errors

In the following table thearguments column lists the arguments encoded in the body of a request message

(Q or S) sent by the client. Thereturn values column lists the valuesthat the server encodes in the body of

a reply (R) and the errors column lists the information encoded in the body of an error message (Eor X).

In cases when an error occurs and multiple values are returned, the values can either be legal values or error values, indicating which parts of request have been successfully completed.

Parentheses, (), are used to indicate lists of values, e.g.(a,b,c) is a list containing a, b, and c. The symbols

+ and * have their usual meaning as in regularexpressions: a+ means one of (a), or (a,a), or (a,a,a), etc.,

and a* means either the empty list () or a+. Note that both a* and a+ are lists. Curly brackets, {}, are used to indicate a tuple of values whose length and structure are determined by the context of the message, so that neither the length nor the structure of thetuple is encoded explicitly.

12

NSTP Specification 1.0

   

Return Value

Common Errors

 

(kind=R unless

(kind=E unless preceded by X)

Opcode

Arguments

otherwise marked)

Notification

INIT

version:int,

response:val

5202, 5203

 

authstyle:string,

key:val

kind = C challenge:val

QUIT

-

 

-

possible DELD to other(s) in Place(s) left

NEW

placename:name,

place field set to handle of new place things:{attr, value}+

5301, 5304

 

placetype:type,

initval:val,

authstyle:string,

 

key:value,

{thingattrs:attr,

thingvalue:val}*,

{overattrs:attr,

overvalue:val}*

GETP

placename:name

place field set to handle of new place

5303

 

ENTR

initval:val,

things:

5402, 5404, 5405

MADE *

authstyle:string,

{name, type}+

key:val

kind = C challenge:val

GPE

placename:name,

place field set to handle of new place things:

5303, 5402,

MADE *

initval:val,

5404, 5405

authstyle:string,

key:val

{name, type}+

kind = C challenge:val

ENGV

initval:val,

things:{attr, val}+

5402, 5404, 5405

MADE *

authstyle:string,

key:val

kind = C challenge:val

GPEV

placename:name,

place field set to handle of new place things:{attr, val}+

5303, 5402,

MADE *

initval:val,

5404, 5405

authstyle:string,

key:val

 

kind = C challenge:val

13

NSTP Specification 1.0

   

Return Value

Common Errors

 

(kind=R unless

(kind=E unless preceded by X)

Opcode

Arguments

otherwise marked)

Notification

MAKE

{thingattrs:attr,

 

5400, 5403, 5404

MADE

kind=Q

thingval:val}+

MAKE

No reply

X5400, X5403,

kind=S

X5404

DEL

thingnames:name+

 

5401, 5502, 5505

DELD

kind=Q

DEL

No reply

X5401, X5502,

kind=S

X5505

GTT

thingnames:name+

things:{attr, val}+

5401, 5502, 5505

 

GTV

thingnames:name+

values:{name, val}+

5401, 5502, 5505

 

STV

updates:{name, val}+

 

5401, 5502, 5505

CHGD

kind=Q

STV

No reply

X5401, X5502,

kind=S

X5505

GTA

thingnames:name+

attributes:attr+

5401, 5502

 

LOCK

thingname:name

 

5401, 5502, 5505

**

LCKB

thingname:name

 

5401, 5502, 5503

**

ULCK

thingname:name+

 

-

***

{thingname:name,

errorcode:int,

errormsg:string}+

EXIT

-

 

-

DELD

KILL

-

 

5502

KILD

SNTC kind = Q

recipient:name,

 

5302, 5403

recipient = “” BNTC

noticetype:type,

 

contents:val

 

NTC

SNTC kind = S

No reply

X5302, X5403

recipient = “” BNTC

NTC

* Implicit creation (or deletion) of user-Thing at entry (or exit). ** When a Thing has been locked, notifications are not sent until it has been unlocked. *** Unlocking a Thing may cause notifications to be sent if it was previously modified.

14

NSTP Specification 1.0

Notifications have the body of the message in the following form:

opcode

content of the body

MADE

things:{attr, val}+

DELD

thingnames:name+

CHGD

changes:{name, val}+

KILD

-

NTC

sender:name,

noticetype:type,

contents:val

BNTC

sender:name,

noticetype:type,

contents:val

15

NSTP Specification 1.0

5 Detailed Semantics

This section provides detailed semantics for each message. We present the requests in alphabetical order, followed by notifications in alphabetical order. The next section describes predefined Things and their meaning at the server.

5.1

Requests

5.1.1

DEL

The DEL (DELete) message is used to delete zero or more Things within a Place.

It may have a kind field of Q or S. If the kind of the client request is Q, then the server will send a corresponding reply (of kind R) when all of the Things have been deleted, or will send an error message (of kind E) if one or more cannot be deleted. If the kind of the client request is S, then the server will not send a reply if the Things are deleted successfully. However, it will send an error message (of kind X) if one or more cannot be deleted. Note that a Thing cannot be deleted if it is locked by another client. If the Atom field is 00 16 , then no Thing is deleted unless all can be deleted. The behavior for other values of the Atom field is currently undefined.

A future specification may include a reply from a deletion that allows for some of the Things to be deleted while others are not.

The body of a DEL request consists of a list of zero or more names of Things. No name may occur more than once. No name may refer to a nonexistent (deleted or never-created) Thing. No name may be a zero-length string.

Each successful DEL request that deletes one or more Things causes exactly one corresponding DELD notification to be sent to each of the clients present in the Place. This notification is sent after the reply has been sent to the requesting client.

5.1.2 ENTR

The ENTR (ENTeR) message allows a client to become “present” in a Place, following which they receive notifications of changes to Things within that Place.

At attempted entry, the client provides anauthentication-style string and a key value. The server interprets these and may respond with a value called achallenge. The client must then issue another ENTR incorporating the challenge and whatever credential the client can provide to meet the challenge, encoded into the authentication-style and key.

So that the server need not keep track of challenges and connections, we recommend the use of authentication protocols that do not require the server to keep state. Instead, any necessary state can be passed to the client as part of the challenge and re-sent to the server with the client’s additional information as part of the key on its next ENTR.

16

NSTP Specification 1.0

Currently defined values for authentication-style are:

authentication-style

meaning of key

empty or zero-length string

key is ignored

matching

Place to be entered must have been created with authentication-style=matching, and key must have the same value (as a byte array) as the key that was provided when the Place was created.

Other values for authentication-style may be defined in the future, allowing for encryption and multiple levels of challenge. It is guaranteed that no string starting with the characters “X-” will ever be used as a defined value forauthentication-style. Accordingly, strings of that form can be used for experimentation with other authentication protocols in servers.

Entering a Place implicitly creates a new Thing in the Place corresponding to the user, called the user-Thing. The user-Thing’s name is derived from the name of the user. The user-Thing’s value field is available for clients to use as they see fit; however, the creation and deletion of the user-Thing are controlled by the server and occur as side effects of entering or leaving a Place.

The client provides a value to be used as the initial value of the new user-Thing. The server replies with a list of the names of all Things in the Place, including the newly-created user-Thing. Because of challenges, a client may issue multiple ENTR messages before successfully entering the Place. Only the value provided to the server on the last such message is used as the value of the new user-Thing.

Each successful ENTR request causes exactly one corresponding MADE notification (for the entering client’s new user-Thing) to be sent to each of the clients present in the Place, including the requesting client. This notification is sent after the reply has been sent to the requesting client.

and then

sending a MADE notification is the consequence of conforming to our principles that notifications are symmetric and responses are sufficient. However, this redundancy is only apparent. We do not want to allow a window during which other clients can see a newly-entered client’s user-Thing but the entering client itself does not know about it. Since there is no guarantee about the order in which notifications are delivered to clients, we also need the reply to eliminate this window, which exists if only the MADE notifications are used.

The apparent redundancy of both including the user-Thing in the returned list of Thing names

5.1.3

ENGV

The ENGV (ENter and Get Values) message allows a client to become “present” in a Place, following which they receive notifications of changes to Things within that Place. In addition,ENGV returns the values of all Things in the Place.

At attempted entry, the client provides anauthentication-style string and a key value. The server interprets these and may respond with a value called achallenge. The client must then issue another ENTR incorporating the challenge and whatever credential the client can provide to meet the challenge, encoded into the authentication-style and key.

So that the server need not keep track of challenges and connections, we recommend the use of authentication protocols that do not require the server to keep state. Instead, any necessary state can be passed to the client as

17

NSTP Specification 1.0

part of the challenge and re-sent to the server with the client’s additional information as part of the key on its next ENGV.

Currently defined values for authentication-style are:

authentication-style

meaning of key

empty or zero-length string

key is ignored

matching

Place to be entered must have been created with authentication-style=matching, and key must have the same value (as a byte array) as the key that was provided when the Place was created.

Other values for authentication-style may be defined in the future, allowing for encryption and multiple levels of challenge. It is guaranteed that no string starting with the characters “X-” will ever be used as a defined value forauthentication-style. Accordingly, strings of that form can be used for experimentation with other authentication protocols in servers.

Entering a Place implicitly creates a new Thing in the Place corresponding to the user, called the user-Thing. The user-Thing’s name is derived from the name of the user. The user-Thing’s value field is available for clients to use as they see fit; however, the creation and deletion of the user-Thing are controlled by the server and occur as side effects of entering or leaving a Place.

The client provides a value to be used as the initial value of the new user-Thing. If there have been multiple ENTR messages sent, the value provided to the server on the last such message is used. The server replies with a list of all Things in the Place, including the newly-created user-Thing. Each Thing is represented as its attributes, followed by its value.

Each successful ENGV request causes exactly one corresponding MADE notification (for the entering client’s new user-Thing) to be sent to each of the clients present in the Place, including the requesting client. This notification is sent after the reply has been sent to the requesting client.

and then sending a

MADE notification is the consequence of conforming to our principles that notifications are symmetric and responses are sufficient. However, this redundancy is only apparent. We do not want to allow a window during which other clients can see a newly-entered client’s user-Thing but the entering client itself does not know about it. Since there is no guarantee about the order in which notifications are delivered to clients, we also need the reply to eliminate this window, which exists if only the MADE notifications are used.

The apparent redundancy of both including the user-Thing in the returned list of Things

5.1.4

EXIT

The EXIT message allows a client to leave the specified Place. After receiving a reply from EXIT, the client will not receive further notifications from the left Place until such time as the clientre-enters the Place using ENTR, ENGV, GPE, or GPEV. Any notifications caused between the time of an EXIT and a subsequent re-entry are lost; they are not saved to be redelivered to are-enteringclient.

18

NSTP Specification 1.0

At EXIT, any locks held by the client are released. Then, het

causing a DELD notification to any other clients present in the Place.

client’s corresponding user-Thing is deleted,

Depending on the type of Place and values of Things within that Place, leaving the Place may implicitly cause it to be destroyed.

5.1.5 GETP

The GETP (GET Place) message allows a client to find the handle for a Place, given its name. The client provides a name, which may begin with “NS:”. The server returns a reply with the Place field set to the handle of the named Place, or returns an error.

5.1.6 GPE

The GPE (Get Place and Enter) message allows a client to get a Place and enter it, with a single message. This effectively combines a GETP with an ENTR.The client provides a name, which may begin with “NS:”, a value to be used as the value of the user-Thing, an authentication-style string, and a key value (see ENTR for the semantics of these fields). For a normal return, the server returns a reply where the Place field is set to the handle of the named Place and the body is a list of the names of all Things in the Place. The list of all Things includes the newly-created user-Thing.

The server must deliver the reply to the entering client before delivering any notification from the entered Place to the client. The server must deliver the MADE notification for the entering client’s new user-Thing to the client.

Each successful GPE request causes exactly one corresponding MADE notification (for the entering client’s new user-Thing) to be sent to each of the clients present in the Place, including the requesting client. This notification is sent after the reply has been sent to the requesting client.

and then sending a

MADE notification is the consequence of conforming to our principles that notifications are symmetric and responses are sufficient. However, this redundancy is only apparent. We do not want to allow a window during which other clients can see a newly-entered client’s user-Thing but the entering client itself does not know about it. Since there is no guarantee about the order in which notifications are delivered to clients, we also need the reply to eliminate this window, which exists if only the MADE notifications are used.

The apparent redundancy of both including the user-Thing in the returned list of Things

5.1.7 GPEV

The GPEV (Get Place and Enter returning Values) message allows a client to get a Place and enter it, fetching all values, with a single message. This effectively combines a GETP with anENGV. The client provides a name, which may begin with “NS:”, a value to be used as the value of the user-Thing, an authentication-style string, and a key value (seeENGV for the semantics of these fields) . For a normal return, the server returns a reply where the Place field is set to the handle of the named Place and the body is a list of all Things in the Place. The list of all Things includes the newly-created user-Thing. Each Thing is sent as the attributes followed by the value.

19

NSTP Specification 1.0

The server must deliver the reply to the entering client before delivering any notification from the entered Place to the client. The server must deliver the MADE notification for the entering client’s new user-Thing

to the client.

Each successful GPEV request causes exactly one corresponding MADE notification (for the entering client’s new user-Thing) to be sent to each of the clients present in the Place, including the requesting client. This notification is sent after the reply has been sent to the requesting client.

and then sending a

MADE notification is the consequence of conforming to our principles that notifications are symmetric and responses are sufficient. However, this redundancy is only apparent. We do not want to allow a window during which other clients can see a newly-entered client’s user-Thing but the entering client itself does not know about it. Since there is no guarantee about the order in which notifications are delivered to clients, we also need the reply to eliminate this window, which exists if only the MADE notifications are used.

The apparent redundancy of both including the user-Thing in the returned list of Things

5.1.8 GTA

The GTA (GeT Attributes) message allows a client that is in a Place to fetch the attributes of zero or more Things in a Place. The body consists of a list of zero or more names of Things. No name can be a zero-length string, but any name can start with “NS:”. The reply (of kind R) consists of a list of attributes. The server returns Thing attributes in order, corresponding to the order of the names in the request. Note that attributes are immutable and can be safely cached by the client.

An attempt by a client outside the Place to use GTA for any Thing in that Place, even one visible in the Facade, causes a “No Access” error.

GTA does not work for clients outside the Place. The attributes of a Thing can reveal information about users and their privileges. This information can be hidden from public view by restricting access to the Place, as long as no request allows attributes to be accessed from outside the Place.

A GTA message causes no notifications.

5.1.9 GTT

The GTT (GeT Thing) message allows a client in a Place to fetch both the attributes and the value of zero

or more Things in a Place. The body consists of a list of zero or more names of Things. No name can be a

zero-length string, but any name can start with “NS:”. The reply (of kind R) consists of a list of Things, each of which consists of attributes followed by the Thing’s value. The server returns Things in order, corresponding to the order of the names in the request.

An attempt by a client outside the Place to useGTT for any Thing in that Place, even one visible in the Facade, causes a “No Access” error.

20

NSTP Specification 1.0

GTT does not work for clients outside the Place. The attributes of a Thing can reveal information about users and their privileges. This information can be hidden from public view by restricting access to the Place, as long as no request allows attributes to be accessed from outside the Place.

A GTT message causes no notifications.

5.1.10 GTV

The GTV (GeT Value) message allows a client to fetch the value of zero or more Things in a Place. The body consists of a list of zero or more names of Things. No name can be a zero-length string, but any name can start with “NS:”. The reply (of kind R) consists of a list of pairs, each of which consists of the Thing name followed by the Thing’s value. The server returns Things in order, corresponding to the order of the names in the request. If any of the Things requested are not readable by the requesting client, the request fails with the error code for “No Access”.

A GTV message causes no notifications.

5.1.11 INIT

The INIT (INITialize) message serves to start a client-server session. The client provides an integer representing the version number of the protocol and two values:authentication-style and key. The version

number corresponding to the protocol described in this document is 1. The server usesauthentication-style

to interpret key, and sends back a message with a kind of R, C, or E. A message withkind=R contains a

single value called theresponse. A message with kind=C contains a single value called thechallenge. A

message with kind=E contains an error body.

Currently defined values forauthentication-style are the strings “openlogon” and “simple-password”.

For “openlogon”, key is considered to start with a single string that represents the user name to be used for the session. Any following bytes are ignored. The server returns a zero-lengthresponse if the logon was accepted, and otherwise returns an error message. There is no challenge.

For “simple-password”, key is considered to consist of two strings. The first represents the user name, and the second represents that user’s password. Any following bytes are ignored. The server returns a zero-lengthresponse if the logon was accepted, and otherwise returns an error message. There is no challenge.

Other values for authentication-style may be defined in the future, allowing for encryption and multiple levels of challenge. It is guaranteed that no string starting with the characters “X-” will ever be used as a defined value forauthentication-style. Accordingly, strings of that form can be used for experimentation with other authentication protocols in servers.

So that the server need not keep track of challenges and connections, we recommend the use of authentication protocols that do not require the server to keep state. Instead, any necessary state can be passed to the client as part of the challenge and re-sent to the server with the client’s additional information as part of the key on its next INIT.

21

NSTP Specification 1.0

INIT causes no notifications.

5.1.12 KILL

The KILL message destroys a Place and all of the Things contained therein. It implicitly releases all locks on all Things in the Place by deleting them, regardless of who is locking them.

KILL causes a KILD notification to be delivered to each of the clients that was present in the Place immediately before it was destroyed. Nosubseqent notifications are delivered from the Place, and no further operations can be performed on the Place.

5.1.13 LOCK

The LOCK message serves to lock exactly one Thing in a Place. When the Thing is locked, the following effects are visible to clients other than the client that successfully obtained a lock:

Attempts to LOCK it fail with an error message indicating that it is locked.

Attempts to read its value (GTT or GTV) fail with an error message indicating that it is locked

(however, the attributes are not locked and may be read with a GTA request). Attempts to set its value (STV) fail with an error message indicating that it is locked.

Attempts to delete it (DEL) fail with an error message indicating that it is locked.

The locking client may freely issue further LOCK or LCKB requests, which always succeed and have no further effect.

Changes made by the locking client (using STV messages) do not cause notifications until the lock is released. If a Thing is changed multiple times with a lock held, only the last change is sent as a CHGD notification when the Thing is unlocked.

A client holding a lock may release it by any of the following means:

Sending an ULCK message naming the locked Thing

Leaving the Place

Deleting the locked Thing (in this case no CHGD notifications are sent, only the DELD

notification) Destroying the Place

LOCK causes no notifications.

5.1.14 LCKB

The LCKB (LoCK with Blocking) message serves to lock one Thing in a Place,queueing for that lock if necessary. If the Thing is deleted while one or more clients are queued for its lock, each of those clients receives an error message indicating that the Thing was not found. This error message is not sent if the Place is destroyed.

When the Thing is locked, the following effects are visible to clients other than the client that successfully obtained a lock:

Attempts to LOCK it fail with an error message indicating that it is locked.

Attempts to read its value (GTT or GTV) fail with an error message indicating that it is locked (however, the attributes are not locked and may be read with a GTA request).

22

NSTP Specification 1.0

Attempts to set its value (STV) fail with an error message indicating that it is locked.

Attempts to delete it (DEL) fail with an error message indicating that it is locked.

The locking client may freely issue further LOCK or LCKB requests, which always succeed and have no further effect.

Changes by the locking client (STV) do not cause notifications until the lock is released. If a Thing is changed multiple times with a lock held, only the last change is sent as a CHGD notification when the Thing is unlocked.

A client holding a lock may release it by any of the following means:

Sending an ULCK message

Leaving the Place

Deleting the Thing (in this case no CHGD notifications are sent, only the DELD notification)

Destroying the Place

LCKB causes no notifications.

5.1.15 MAKE

The MAKE message is used to create zero or more new Things in a particular Place.

It may have a kind field of Q or S. If the kind of the client request is Q, then the server will send a

corresponding reply (of kind R) when all of the Things have been created, or will send an error message (of kind E) if one or more cannot be created. If the kind of the client request is S, then the server will not send a reply if the Things are created successfully. However, it will send an error message (of kind X) if one or more cannot be created.

The body of a MAKE request consists of a list of zero or more specifications of new Things, each of which consists of the attributes followed by the value of that Thing. The client must specify a name and type for each Thing. The name may not be a zero-length string, nor may it start with the characters “NS:”. The type may be a zero-length string, and may start with the characters “NS:”. However, if the type starts with

“NS:”, then the type is known to the server and interpreted by the server. The server may reject the creation

of Things whose type begins with “NS:” but where the remainder of the type is not understood by the

server, or where the other attributes or value of the Thing specified are not appropriate for that server-defined type.

If multiple Things are to be made in a single MAKE message, they are made in sequence, with the first

Thing in the message-body being the first Thing made.

A MAKE message causes a MADE notification.

23

NSTP Specification 1.0

5.1.16 NEW

The NEW message creates a new Place. The user is immediately present within the Place without having to separately enter (the Place is created “around” the user).

To create a Place, the client must provide:

the name of the Place, the type of the Place, zero or more initial Things to be created in the Place, zero or more overrides to predefined Things in the Place,

a string describing the authentication style used for the Place,

a value to be used as the key for the Place, and the value to be used for the user-Thing in the Place.

The name of the Place must not begin with “NS:”. The name may not be a zero-length or empty string.

The type of the Place may begin with “NS:”, but if so, the type is significant to the server and must be known to the server.

For each initial Thing oroverridenThing specified, the client must provide the Thing’s attributes and value. An attribute of an overridden Thing may be specified asDONTCARE, in which case the server uses the attribute setting that would have been used for that Thing if there had been no override provided.

Initial Things are created in an unspecified order. Similarly, overridden Things are overridden in an unspecified order. The protocol does not specify whether overrides take place before, after, or interleaved with creation of new Things.

The following values of authentication-style are defined:

authentication-style

meaning of key

empty or zero-length string

key is ignored

matching

Key is stored; entry to Place requires providing an identical key value, and an authentication-style of “matching”.

Other values for authentication-style may be defined in the future. It is guaranteed that no string starting with the characters “X-” will ever be used as a defined value forauthentication-style. Accordingly, strings

of that form can be used for experimentation with other authentication protocols in servers.

A NEW request cannot cause a challenge(kind=C) response.

In a NEW request, the authentication-style and key are used to set up the Place’s authentication mechanism, not to authenticate the client. The client has already been authenticated by logging on to the server (via INIT). Connection to a server and entry to a Place are the only two points at which challenges can be issued.

The value of the user-Thing is an ordinary value, available for use by the user, and is not interpreted by the server in any special way.

24

NSTP Specification 1.0

We expect that a common use of this value will be to make non-NSTP contact information about the user (such as a phone number or email address) available to other users.

The server reply to NEW is a list of all the Things in the Place. This includes the initial Things specified by the client and the user-Thing created by the server. It is likely to include a number of other Things that were created by the server for the Place. For each such Thing, the server sends the attributes and the value.

A server is not obligated to honor any NEW request.

Some servers may allow only a limited number of NEW requests, others may allow only specific types of Places to be created, still others may refuse to create any new Places for clients (allowing clients only to use the Places that already exist at the server, possibly by some non-protocol mechanism). A server implementor has a great deal of latitude in deciding when to allow new Places to be created. In contrast, a server may not arbitrarily refuse to MAKE a new Thing for a client that has entered an existing Place.

NEW causes no notifications.

5.1.17 QUIT

The QUIT message serves to end the session started by INIT. The client receives no further notifications, and no other commands will be accepted by the server on the connection until another INIT is issued. The user will be seen by others to leave all Places in which that user is present. The server need not cause the user to leave all Places before replying to the QUIT, but must ensure that the user leaves all Places soon thereafter.

QUIT may cause notifications if the quitting client is present in one or more Places. For each Place where the quitting client is present, QUIT causes the client to leave the Place. Leaving the Place causes the corresponding user-Thing to be deleted, and so causes a DELD notification to be delivered to each other client still present in that Place.

5.1.18 SNTC

The SNTC (Send NoTiCe) message is used to deliver aNTC notification to a single user, or aBNTC notification to all of the clients present in a Place.

The body of the request consists of one name, one type, and one value. The name may be an empty or zero-length string, in which case aBNTC notification containing the provided value is delivered to every

client in the Place. If the name is not an empty or zero-length string, it is the name of a user present in the Place, and the corresponding client will receive aNTC notification containing the provided value. If the name provided does not correspond to the name of a user present in the Place, noNTC notification is delivered and an error message is sent back to the client sendingSNTC. The name may begin with “NS:”.

If the name does begin with “NS:” it names a pseudo-user implemented by the server. This is a possible

mechanism for communicating arbitrary information to the server.

The type may begin with “NS:”. If the type does begin with “NS:”, it is significant to the server and may be treated specially. The server may respond with an error if the notice’s type starts with “NS:” but the type

is not known at this server.

25

NSTP Specification 1.0

SNTC causes BNTC or NTC notifications.

5.1.19 STV

The STV (SeT Value) message is used to provide a new value for zero or more Things in a Place.

It

may have a kind field of Q or S.

If

the kind of the client request is Q, then the server will send a corresponding reply (of kind R) when all of

the Things have been set to their new value, or will send an error message (of kind E) if one or more cannot be set.

If the kind of the client request is S, then the server will not send a reply if the Things are set successfully.

However, it will send an error message (of kind X) if one or more cannot be set.

The client provides a list of name-value pairs (2-tuples). Each name must be the name of a Thing in the Place. The server changes the Thing named by each name to contain the corresponding value provided.

In general, STV causes CHGD notifications for any Thing changed. However, if a Thing’s

notification-style attribute indicates that notifications are set only on creation or deletion, then CHGD notifications are not sent. In addition, if the Thing is currently locked by the client performing the STV, the notifications are delayed until the lock is released.

A Thing can be named more than once, and the last value provided will be the value at the server after the

message has been processed. If a Thing is named more than once, it is undefined exactly how many times that Thing will appear in a corresponding CHGD notification; however, it will appear at least once and no more than the number of times the Thing’s name appeared in the STV message.

5.1.20 ULCK

The ULCK (UnLoCK) message serves to release locks held on zero or more Things. The locks may have been acquired by any mixture of LOCK and LCKB messages. The body of the message consists of a list of names of Things. No name can be a zero-length string.

The ULCK message does not cause any notifications directly. It may allow previously-delayed CHGD notifications to be released. Any CHGD notification delivered from an unlocked Thing carries the id and value of the last STV applied to the Thing before the Thing was unlocked.

Regardless of the value of the Atom field, ULCK is always non-atomic: it releases whichever locks can be released, even if some of the Things named do not exist or are not locked. If the response to ULCK

contains no information, then all locks were released successfully. Otherwise, the response consists of a list

of triples (3-tuples), each consisting of a Thing name, an integer error code, and a string containing an error

message. ULCK never returns a message of kind E; instead the errors are encoded in a message of kind R.

26

NSTP Specification 1.0

5.2

Notifications

5.2.1

BNTC

The BNTC (Broadcast NoTiCe) notification carries an arbitrary type and value to every client present in a particular Place. Its body consists of the username of the sender (another client present in the Place), the type being sent, and the value being sent.

The sender’s name may begin with “NS:”. If the name does begin with “NS:” it represents a pseudo-user implemented by the server. This is a possible mechanism for the server to communicate arbitrary information to users.

The type may begin with “NS:”. If the type does begin with “NS:”, it is significant to the server and may represent special server-related information or actions, even if not sent by the server.

BNTC is caused by the SNTC operation.

5.2.2 CHGD

The CHGD (CHanGeD) notification serves to indicate that one or more Things in a single Place have had new values assigned. The body of the notification consists of a list of pairs, each consisting of a name and a value. The name is the name of a changed Thing and the value is its new value.

Not all Things cause CHGD notifications when they are modified. A Thing’s attributes may include a notification-style of create/delete, in which case CHGD notifications never refer to the Thing.

In the absence of locking, each CHGD notification corresponds exactly to one STV request: all of the change-notifying Things modified by the STV appear in a single CHGD notification.

For any locked Thing, the CHGD notification caused by the STV is delayed until the Thing is unlocked, and may be eliminated entirely in the following circumstances:

there is a subsequent STV (causing another CHGD),

the Thing is deleted, or

the Place is destroyed.

Each delayed notification may be delayed separately; the server is not obligated to deliver delayed notifications for a collection of locked Things in a single CHGD notification, even if the Things were all changed by a single STV and unlocked by a single ULCK.

The server does not pay attention to whether the new value provided in a STV is actually different from the old value of the Thing: it is possible that a client has set the value of a Thing to a value it already has. Nevertheless, the server will still send a CHGD notification if that would be sent for a different value.

CHGD is caused by the STV operation.

27

NSTP Specification 1.0

5.2.3 DELD

A DELD notification serves to indicate that one or more Things in a Place have been deleted. Its body

consists of a list of names of Things. No name can appear more than once in the list of names, and no name

can be a zero-length string.

DELD can be caused by the operations DEL, EXIT, or QUIT.

5.2.4 KILD

The KILD (KILleD) notification indicates that a Place has been destroyed. Its body is empty (the Place destroyed is indicated by the handle in the Place field of the notification’s header). When a Place is destroyed, all Things in the Place are implicitly deleted. Clients receive no further notifications from a Place after receiving a KILD notification for that Place.

KILD is caused by a KILL operation.

5.2.5 MADE

The MADE notification serves to indicate that one or more Things have been created in a Place. The body

of the notification consists of a list of pairs, each of which consists of the full attributes of the Thing,

followed by its value.

MADE is caused by the operations MAKE, ENTR, ENGV, GPE, and GPEV.

5.2.6 NTC

The NTC (NoTiCe) notification carries an arbitrary type and value to a single client present in a particular Place. Its body consists of theusername of the sender (another client present in the Place), the type being sent, and the value being sent.

The sender’s name may begin with “NS:”. If the name does begin with “NS:” it represents a pseudo-user implemented by the server. This is a possible mechanism for the server to communicate arbitrary information to users.

The type may begin with “NS:”. If the type does begin with “NS:”, it is significant to the server and may represent special server-related information or actions, even if not sent by the server.

NTC is caused by the SNTC operation.

28

NSTP Specification 1.0

5.3 Predefined Things

Every Place created contains a number of predefined Things that have special values, provided by or used by the server. The following table shows for each predefined Thing its name, meaning, type, and the format of its value. The following table shows default values and permissions for the same predefined Things.

Name

Meaning

Type

Format

NS:Name

The name of the Place. Must be provided when Place is created.

NS:String

String

NS:Type

The type of the Place. Must be provided when Place is created.

NS:String

String

NS:Readable

Names of Things that are Facade-readable but not Facade-writable

NS:List:ThingName

String containing comma-separated list of names

NS:ReadableWritable

Names of Things that are Facade-readable and also Facade-writable

NS:List:ThingName

String containing comma-separated list of names

NS:Writable

Names of Things that are Facade-writable but not Facade-readable

NS:List:ThingName

String containing comma-separated list of names

NS:PlaceThingList

Names of Things that are neither Facade-readable nor Facade-writable

NS:List:ThingName

String containing comma-separated list of names

NS:User-username

Not significant to server, and available for user. May be specified on entry.

NS:User

 

NS:UserList

Names of users present in Place

NS:List:UserName

String containing comma-separated list of names

NS:EntryControlList

Names of users allowed to enter this Place. An empty list means anyone may enter.

NS:List:UserName

String containing comma-separated list of names

NS:Door

The current state of the door that prevents any entry when closed.

NS:Entry

Either “Open” or “Closed”

NS:DestroyFormat

When the Place is automatically destroyed.

NS:Destroy

Either “AfterLastUserLeaves” or “Never”

NS:PlaceDestroyers

Names of users allowed to destroy this Place. An empty list means anyone in the Place may destroy

NS:List:UserName

String containing comma-separated list of names

NS:ThingCreators

Names of users allowed to create Things in this Place . An empty list means anyone in the Place may create a Thing.

NS:List:UserName

String containing comma-separated list of names

29

NSTP Specification 1.0

Name

Default value

Read

Write

Delete

Notif.

NS:Name

No default allowed

Facade

Final

Final

Create Delete

NS:Type

No default allowed

Facade

Final

Final

Create Delete

NS:Readable

N/A

Facade

Server

Final

Create Delete

NS:ReadableWritable

N/A

Facade

Server

Final

Create Delete

NS:Writable

N/A

Facade

Server

Final

Create Delete

NS:PlaceThingList

N/A

Place

Server

Final

Create Delete

NS:User-username

zero-length string

Place

Owner

Server

Change

username

NS:UserList

N/A

Place*

System

Final

Create Delete

NS:EntryControlList

zero-length string *

Place*

Place*

Final

Change*

NS:Door

“Open” *

Facade*

Place*

Final

Change*

NS:DestroyFormat

“AfterLastUserLeaves” *

Place*

Place*

Final

Change*

NS:PlaceDestroyers

zero-length string *

Place*

Place*

Final

Change*

NS:ThingCreators

zero-length string *

Place*

Place*

Final

Change*

An asterisk (*) indicates that a particular attribute may be overridden when the Place is created.

30

NSTP Specification 1.0

6 Appendix: Conventions

Early applications of the protocol use a number of conventions in naming Things that are useful for describing or linking Places. Each of these names begins with the tag “STD:”.This tag does not have any special status within the protocol. Applications are not required to use these conventions, and neither client nor server is required to treat these names specially. However, conforming to these conventions will help differentNSTP applications to interoperate.

Name

 

Value

Type

Read

Write

Delete

Notif.

STD:About

A

Property-Value List

STD:PVList

Facade

Final

Final

Create

describing the Place and

Delete

its purpose. 3

STD:JavaExecutable

A URL for a Java class

STD:NSApplet:Java

Facade

Final

Final

Create

that can run in a client and interpret the Place.

Delete

STD:ActiveXExecutable

A

URL for an ActiveX

STD:NSApplet:ActiveX

Facade

Final

Final

Create

that can run in a client and interpret the Place.

Delete

STD:Link -- name

A

URL for another Place

STD:Link

Place

Final

Place

Create

that bears no necessary relation to this Place.

preferred

preferred

Delete

but not

but not

 

required

required

STD:ParentPlace

A

URL for another Place

STD:Link:Parent

Place

Final

Final

Create

that is logically the parent of this Place.

preferred

Delete

but not

 

required

STD:SubPlace -- name

A

URL for another Place

STD:Link:SubPlace

Place

Final

Place

Create

that is logically a subplace of this Place.

preferred

preferred

Delete

but not

but not

 

required

required

STD:Generator -- name

A

URL for a Java class

STD:NSApplet:Java:Gener

Place

Final

Place

Create

that can create a SubPlace

ator

preferred

preferred

Delete

but not

but not

required

required

NSTP Specification 1.0

7

References

[P82] Jonathan B. Postel. “Simple Mail Transfer Protocol.” RFC 821, 1982. [PDK96] John F. Patterson, Mark Day, and Jakov Kucan. “Notification Servers for Synchronous Groupware.” In Proceedings of CSCW 96. [U96] The Unicode Consortium. The Unicode Standard, Version 2.0. Addison-Wesley,1996.

32