(incomplete, does not cover lists yet)
Unless you're writing a listener or editing the multiplexer, all you need to know about ClientKeys is how to receive them, use them as hash keys, and pass them back out. So here's how to do those steps in C. The one thing to keep in mind is that no ClientKey in C is ever mallocd by the libraries provided, and so most of these functions require a client key as a 'buffer'. The buffer can and probably will be modified to nonsense if the function returns an error, so always check the return value before trusting the buffer. The type of ClientKeys is 'struct clientkey'.
When you know a message argument is supposed to be a ClientKey (and you aren't using the base server, which does this for you), this will get the ClientKey:
To pass a client key into a message (assuming you aren't using one of the handy methods in serverfuncs.c which composes a message given a 'struct clientkey *' argument directly):
Finally, given a ClientKey, this is how you get the 'string form' which makes a great hash key (or something to print to debugging logs):
You can copy a and compare ClientKeys with the following code bits. There currently no notion of ordering ClientKeys (as hash keys, they do not need an ordering).
When writing a listener, if you get a client key, you probably want to do the
the following. The important functions are '
The other thing you'll need to do when writing a listener is turn your base integers representing end-user ids into ClientKeys to pass up to the multiplexer. This is accomplished thusly:
When working on the multiplexer, there will be some amount of dropping levels
from ClientKeys before passing them along to listeners. There is a function
ck_can_drop_a_level' for checking validity there, and a more
complicated function '
ck_remainder' which takes a new buffer and
returns a new ClientKey with one fewer levels than the passed in
ClientKey. When passing ClientKeys back up to the multiplexer, the inverse
ck_can_add_a_level' and '
will be used (since there is no copy-while-adding operation corresponding to
ck_remainder', one will have to use '
shown above, first). Relevant sample code can be found in the multiplexer by
searching for those function names.
Doc Index / ClientKey Specification
|This project is hosted by sourceforge.net:||project homepage||silver's homepage|