Elko: Client Objects

The Client View of the Context-User-Item Model

The Session Object

When a client first establishes a connection to a Context Server, there is one server object in scope that it can send messages to. This is the Session object, which represents the session connection itself. The Session object is always known by the ref "session".

The client may send the following messages to the server presence of the Session object:

entercontext

→ { to:"session", op:"entercontext", context:CTXREF_STR, user:?USERREF_STR, name:?STR, sess:?STR, auth:?STR, debug:?BOOL }

This message places (or attempts to place) a user into a particular context on the server.

If entry is successful, the server will transmit a series of "make" messages describing the context and the users and items it contains, including a description of the entering user. This series of "make" messages will be terminated by a "ready" message targeted at the context, after which the client may consider itself to be fully entered into the context. In particular, after that point, the server may send additional, unsolicited messages to the client describing changes in the context environment and activity going on there. The nature of these messages depends on the specific application that the context is presenting.

Note that a user may be entered into more than one context concurrently. The user's presence in any particular context will be identified by a unique context-specific reference string that will be provided as part of the user description sent to the client in response to the "entercontext" message. Messages sent from the server to the client will use this reference string as the message target for messages to the user, allowing the client to disambiguate which presence (and thus which application) the message pertains to.

disconnect

→ { to:"session", op:"disconnect" }

This message removes the user from any contexts they are in and terminates the session. The connection to the server is broken.

ping

→ { to:"session", op:"ping", tag:?STR }

This message tests connectivity to the server.

If the message is successfully received by the server, it will reply with:

← { to:"session", op:"pong", tag:?STR }

debug

→ { to:"session", op:"debug", msg:STR }

This message delivers debugging information to the server. If the server is configured to permit this, the string given in the msg parameter will be written to the server's log. If the server is not configured to permit this, this message will simply be ignored.

The server may send the following messages to the client presence of the Session object:

make

The server will send "make" messages to the session to direct it to create client presences of context objects (within a context, successive "make" messages will be directed to the context object itself to generate the in-context user object and the other objects contained by the context). The "make" message is generic. It is described below.

exit

← { to:"session", op:"exit", why:?STR, whycode:STR, reload:?BOOL }

This message informs the client that it is being disconnected from the server. After this message is sent, the server will close the connection. This may be sent in reply to a "disconnect" message sent by the client to the server, but it may also be sent spontaneously as a result of events happening on the server.

Generic messages

The server may send the following messages to any C-U-I object:

make

← { to:CONTAINERREF_STR, op:"make", maker:?USERREF_STR, obj:OBJDESC, you:?BOOL, sess:?STR }

This message directs the client to create a client presence of a C-U-I object. The target of the message is the container into which the object should be created. If this container is "session", then the new object will be "contained" by the session; as a rule, the only objects that will be belong to the session in this way are the contexts themselves. Users will be contained by context objects, while items may be contained by contexts, by users, or by other items.

delete

← { to:REF_STR, op:"delete" }

This message directs the client to delete its client presence of the C-U-I object that is the target of the message, as well as any other objects it may contain. After this message is received, the targeted object no longer exists in the context environment, and messages sent to the server presence of the object will be rejected by the server.

say

← { to:REF_STR, op:"say", from:?USERREF_STR, text:STR }

This message is used to carry system messages and text chat. It directs the client to display the text string that was transmitted, in a manner consistent with the application in the context. The target of this message is always the context or a user, never an item. If targeted at a user, the communication is for that user. If targeted at the context, it is for all users in the context. (Note that a given client will only receive messages targeted at its own user or at the context.)

push

← { to:REF_STR, op:"push", from:?USERREF_STR, url:STR, frame:?STR }

This message directs the client to load a web page. The target of this message is always the context or a user, never an item. If targeted at a user, the intent is that that user is being pushed to the given URL. If targeted at the context, all users in the context are being pushed. (Note that a given client will only receive messages targeted at its own user or at the context.)

The Context Object

When a context is created by a "make" message, the obj parameter of the "make" message will be a context descriptor, which is a JSON object of the form:

{ type:"context", id:CTXREF_STR, name:STR, mods:[MODDESC] }

Upon successful entry to a context (such as when the client sends an entercontext message to the server presence of the session object), the server will send a "make" message to the client presence of the session object, creating the client presence of the context itself. This context object will then be sent one or more "make" messages creating client presences for the other users in the context and for any items contained by the context. If any of these users or items have any contents of their own, additional "make" messages will be sent to those objects that create their content objects. The end of this series of "make" messages will be indicated by the server sending a "ready" message to the context. Finally, the server will send the context a "make" message creating the client presence of user who entered.

ready

← { to:CTXREF_STR, op:"ready" }

This message signals to the client that the series of "make" messages generating the context and its contents is complete and that the context is ready for the client to interact with it.

exit

→ { to:CONTEXT_REF, op:"exit" }

This message removes the sending user from the context and terminates their interaction with it.

The context object may understand additional messages depending on what mods are attached to it.

The User Object

When a user is created by a "make" message, the obj parameter of the "make" message will be a user descriptor, which is a JSON object of the form:

{ type:"user", id:USERREF_STR, name:STR, mods:[MODDESC] }

The Item Object

When an item is created by a "make" message, the obj parameter of the "make" message will be an item descriptor, which is a JSON object of the form:

{ type:"item", id:ITEMREF_STR, name:STR, mods:[MODDESC], cont:?BOOL, deletable:?BOOL }

delete

→ { to:ITEMREF_STR, op:"delete" }

A client may request the server to delete a deletable item by sending a "delete" message targeted at the item it wishes to delete. If the server complies, it will send a delete message back (see Generic Messages above) directing the client to go ahead and delete the item.