SynchronizedProtocol
From SynchroEdit
Contents |
[edit]
Interface implementation "SynchronizedProtocol":
[edit]
Revision 10 (October 31, 2006)
[edit]
Note
This specification does not take into consideration such things as logging in/identifying oneself on the server-system.
[edit]
Changelog
Revision Date Description 4 Aug 16, 2005 Added ELA command, for attribute changes. 5 Jan 31, 2006 Added PAUSE and RECONNECT. 6 Feb 21, 2006 Added EMAIL. 7 May 30, 2006 Added CHAT. 8 Jun 21, 2006 Added FREEZE, FROZEN. 9 Oct 10, 2006 Added EMAILME*, CCE, ADAC. 10 Oct 31, 2006 Added CANCEL.
- Eventually, it is the intention that the more specific protocol functions will be moved out of the core spec and into server-side plugins. Plugins will do things like provide link-generation, Wiki-word observation, and emailing to users. The *-marked entries will eventually become obsolete, to disappear entirely from this core spec.
[edit]
Definitions
// DOM Node defines: var NT_ELEMENT_NODE = 1; // Node.ELEMENT_NODE var NT_ATTRIBUTE_NODE = 2; // Node.ATTRIBUTE_NODE var NT_TEXT_NODE = 3; // Node.TEXT_NODE var NT_DOCUMENT_NODE = 4; // Node.DOCUMENT_NODE
[edit]
Protocol specification
General:
- All commands are separated by line-feed.
- Some commands' parameters may include line-feeds; these commands should wrap the entire parameter content in [] brackets.
- All commands from server-to-client which originate from another client should have the client's UID (user ID) as its first argument, followed by any (if any) command arguments.
- All commands should be prefixed with the DocumentStateSequence, even if the DocumentStateSequence is currently unset (-1), and even if the command is DSS-insensitive. DSS-announcements server-to-client should always have the DSS sequence -1, regardless of document state.
[edit]
Protocol
[edit]
Client-to-server specification
Command: UP [charcount] [content]
int [charcount] # of characters in transmission
string [content] the content to update with
DSS-sensitive: No.
Description: Update the currently edited node.
Command: SET [node-identifier] [charcount] [content]
string [node-identifier] the node to update
int [charcount] # of characters in transmission
string [content] the content to update with
DSS-sensitive: Yes.
Description: Update the specified node and move the node-pointer.
Command: NODE [node-identifier]
string [node-identifier] the node to move to
DSS-sensitive: Yes.
Description: Move the node-pointer to a new node.
Command: REM [node-identifier]
string [node-identifier] the node to remove
DSS-sensitive: Yes.
Description: Remove a node.
Command: INS [node-identifier] [node-type] [element-tag] [temp-id] [charcount] [content]
string [node-identifier] new node's identifier
int [node-type] the NT_* value of this node's type
string [element-tag] element tag name (only when [node-type]==1)
string [temp-id] temporary id (only when [node-type]==1)
int [charcount] # of characters in transmission
string [content] the content to update with
DSS-sensitive: Yes.
Description: Insert a new node.
Command: ELA [element-id] [attribute-id] [charcount] [attribute-value]
string [element-id] The element ID, which can be obtained using the DOM
getElementById(), or using the Node.getAttribute("id")
string [attribute-id] The attribute which is to be changed.
int [charcount] # of characters in transmission
string [attribute-value] The value to set the attribute to.
DSS-sensitive: No.
Description: Set or add an attribute to an element.
Command: PAUSE
DSS-sensitive: No.
Description: Ask the server to start buffering updates for the client and
to tell the client to reconnect.
Command: COLOR [htmlRgb]
string [htmlRgb] New color.
DSS-sensitive: No.
Description: Tell the server we have a new color.
Command: EMAIL [address]
string [address] User's email address.
DSS-sensitive: No.
Description: Tell the server user's email address.
Command: CHAT [message]
string [message] A message.
DSS-sensitive: No.
Description: Send a message to the in-client chat pane.
Command: FROZEN Description: Tell the server that the client is frozen.
Command: EMAILME
Description: Send the current document as an email to the user.
This depends on an ESPI handler for
the 'on-demand-email' hook.
Command: ADAC [cmd] [args]
string [cmd] The command; e.g. "KICK"
strings [args] The argument(s), if any. E.g., "Kalle"
Description: Perform an ADministrator ACtion. Requires ESPI awareness for
user roles; server will refuse all such actions
from users not marked as moderators. If [cmd] begins
with an exclamation mark (!), it will be refused
unless the user is an administrator.
Command: CCE [message]
string [message] Error message.
Description: Inform server about a (javascript) error that occured on the client.
Command: CANCEL
Description: Cancel the session. This command is only available if the ESPI hook "may-cancel" is enabled
and returns appropriate results. If canceled, the session is immediately shut down and
any potential "terminate-action" ESPI hooks will be ignored.
[edit]
Server-to-client specification
Command: RECONNECT DSS-sensitive: No. Description: Ask the client to reconnect to the server.
Command: ID [old-id] [new-id]
string [old-id] the node-identifier of the node that should be renamed
string [new-id] the new element ID of the resulting element
DSS-sensitive: No.
Definition: private-response
Description: Identify an element node, effectively making it an anchor.
Command: UP [uid] [charcount] [content]
string [uid] user ID
int [charcount] # of characters in transmission
string [content] the content to update with
DSS-sensitive: No.
Definition: announcement
Description: Update the currently edited node.
Command: SET [uid] [node-identifier] [charcount] [content]
string [uid] user ID
string [node-identifier] the node to update
int [charcount] # of characters in transmission
string [content] the content to update with
DSS-sensitive: Yes.
Definition: announcement
Description: Update the specified node and move the node-pointer.
Command: NODE [uid] [node-identifier]
string [uid] user ID
string [node-identifier] the node to move to
DSS-sensitive: Yes.
Definition: announcement
Description: Move the node-pointer to a new node.
Command: REM [uid] [node-identifier]
string [uid] user ID
string [node-identifier] the node to remove
DSS-sensitive: Yes.
Definition: announcement
Description: Remove a node.
Command: INS [uid] [node-identifier] [node-type] [element-tag] [element-id] [charcount] [content]
string [uid] user ID
string [parent-identifier] new node identifier
int [node-type] the NT_* value of this node's type
string [element-tag] element tag name (only when [node-type]==1)
string [element-id] element identifier (only when [node-type]==1)
int [charcount] # of characters in transmission
string [content] the content to update with
Definition: announcement
Description: Insert a new node.
Command: ELA [uid] [element-id] [attribute-id] [charcount] [attribute-value]
string [uid] user ID
string [element-id] The element ID, which can be obtained using the DOM
getElementById(), or using the Node.getAttribute("id")
string [attribute-id] The attribute which is to be changed.
int [charcount] # of characters in transmission
string [attribute-value] The value to set the attribute to.
DSS-sensitive: No.
Description: Set or add an attribute to an element.
Command: DSSA [dss]
int [dss] DSS sequence relative correction
Definition: private-announce
Description: Document State Sequence Announcement. The [dss] integer is a signed relative correction (most probably a
positive number) defining the DSS out-of-syncness of the client.
Command: CHAT [uid] [message]
string [message] A message.
DSS-sensitive: No.
Description: Display a message from [uid] in the in-client chat pane.
Command: FREEZE Description: Tell client to freeze and lock the document.
[edit]
Use cases
The use cases here were deemed misleading as they do not currently represent the current implementation of SynchroEdit and thus have been removed.
[edit]
History
- June 21, 2006
- We've realized that the document client-side, after a few hours, becomes nearly impossible to work with due to client-side optimizations. Thus, we're introducing the FREEZE/FROZEN commands which will be used to briefly freeze the editing, normalize/clean up the document in session, then re-send the document to every participant. This would happen every 30 minutes.
- October 10, 2006
- Mostly filling out the specification. The note above (June 21, 2006) has not yet taken effect.
- October 31, 2006
- Added "CANCEL" command, in the work to make MediaWiki and SynchroEdit play together.
