AgNet - silverware Networking Interface Kit

by silver Harloe

Doc Index / ClientKey Implementations

ClientKey Specification

'ClientKeys' are used by the server to index end-users and lists of end users. The messages which indicate an end-user (or list of end users) require a 'ClientKey' argument, usually as their first argument.

A ClientKey is a list of integers, which specify (in reverse) a route to the end-user through 'clients' of each mutliplexer along the way. Thus the client key '5:199' refers to client number five of the final listener, which in turn is client 199 of the multiplexer. Currently, multiplexer chaining isn't written, but when it is, a ClientKey list can be up to 10 levels deep, routing the client through multiplexers on the way to the final listener. In a message argument, a client key looks like a series of two to eleven integers - one for the depth and one more for each level. By the time they are on the server, they always have a depth of at least two (and, until multiplexer chaining is written, always have a depth of exactly two).

However, you really don't need to know that to write a server. What you do need to know is that ClientKeys 'stringify' to unique strings and thus make great hash keys for the server to keep track of end-users. And, in turn, that it needs to pass those keys (not their string representations!) back to the multiplexer to get messages out to the clients. How you get at the string form of ClientKeys and pass raw ClientKeys as message arguments depends on the language, see ClientKey Implementations. If the you use the APIs, the details of client keys will be totally unimportant to you, up to and including their depth.

The other thing you need to know is that ClientKeys can also refer to lists of client keys, but it up to the server to decide and maintain lists by sending the multiplexer messages to make lists, and add/remove clients from lists. The multiplexer supports lists numbered from one to 65535. A list is always exactly two levels deep and the 'listener number' (last number) in it is always 255. Thus '1:255' refers to list number one on the multiplexer. List number zero means 'all end users', and the server does not have to maintain list zero.

When lists are more fully implemented, I will disclose more information here about messages to use to maintain lists. No doubt the '0:255' ClientKey will be a "constant" defined in the server API, and probably the server APIs will have list maintenance functions/methods.

Anyway, the whole of the ClientKey 'specification' is that "ClientKeys are a list of from one to ten integers. If the last integer is 255, then there must be just one other integer, which must be from 0 to 65535. They must stringify uniquely, and when turned into a message argument, must use the 'integer argument byte order' to specify one int for the size of the list, and then each integer in succession".

Doc Index / ClientKey Implementations

This project is hosted by Logo project homepage silver's homepage