SynchronizedProtocol

From SynchroEdit

(Difference between revisions)
Jump to: navigation, search
Revision as of 17:23, 10 October 2006 (edit)
Kalle Alm (Talk | contribs)
(Revision 9 - Added EMAILME*, CCE, ADAC.)
← Previous diff
Revision as of 17:24, 10 October 2006 (edit)
Kalle Alm (Talk | contribs)
(Client-to-server specification)
Next diff →
Line 108: Line 108:
strings [args] The argument(s), if any. E.g., "Kalle" strings [args] The argument(s), if any. E.g., "Kalle"
Description: Perform an ADministrator ACtion. Requires [[ExternalServicePOSTInterface|ESPI awareness]] for Description: Perform an ADministrator ACtion. Requires [[ExternalServicePOSTInterface|ESPI awareness]] for
- user roles; server will refuse all such actions from users not marked + user roles; server will refuse all such actions
- as moderators. If [cmd] begins with an exclamation mark (!), it will be+ from users not marked as moderators. If [cmd] begins
- refused unless the user is an administrator.+ with an exclamation mark (!), it will be refused
 + unless the user is an administrator.
==== Server-to-client specification ==== ==== Server-to-client specification ====

Revision as of 17:24, 10 October 2006

Contents

Interface implementation "SynchronizedProtocol":

Revision 9 (October 10, 2006)

Note

This specification does not take into consideration such things as logging in/identifying oneself on the server-system.

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.
  • 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.

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 

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.

Protocol

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.

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.

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.

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.
Personal tools