Message format description
This document should be expected to change in the production of the 
software and may be considered consumable in its current form. It is 
important to record not only the intent of the message formats, but 
also the format the messages use for cross-platform and future 
development purposes.

Copyright 2001 by Chris Jones. All rights reserved.
$Id: message_format.txt,v 1.2 2001/06/29 01:09:40 cjones Exp $
-----------------------------------------------------------------------

Messages in DMUD are of a fixed format, no more than 1500 bytes in
length. If larger files (like binaries) need to be transmitted, the
message should indicate that some handler should retrieve the file via
another protocol (HTTP, FTP, etc.).

Typically, a message acts as an event notification. There are several
categories of message:

    *** World Messages *** 
        --> Server to Client
        <common to all servers>
            movement of others (change coordinates)
            add object (advertise its presence)
            delete object (remove its presence)
            appearance change (change intrinsics)
            notify (arbitrary text message)


    *** Client Messages *** 
        --> Client to Server
        <intrinsic communication>
            page client
        <session>
            logoff request
            connect to server
            login to server (present certificate, password)
            gate (go to another server) [Consider removing]
        <administrative>
            portal (create permanent gate)
            accept (accept a permanent gate) [Consider removing]
        
        --> Server to Client
        <connection management>
            accept client connection (challenge phase)
            accept client login
            disconnect client
 
 
    *** System Messages *** 
        --> Client to Server
        <connection management>
            list portals
            list clients
            boot other client
        <certificate management>
            accept certificate
            reject certificate
            remove certificate
            list certificates
            examine certificate

        --> Server to Client
        <intrinsic communication>
            page message (from another client)
            system message
           

     *** Object Messages *** 
         --> Client to Server
         <object management>
            create object from class
            list class fields
            examine object field
            change object field
         <method discovery>
            list methods on class
            query method existance on class
            add method to class
            change method on class
            remove method from class
         <method invocation>
            invoke method on object

         --> Server to Server/Client
         <object management>
            query class existance
            query class fields
            query class methods
            query object existance
            get object class
            get object instance (class + fields) by obj id
            send object class (as new or replacement class)
            send object instance (with class, if not present)
            remove object class
            remove object instance
            get class home server reference (for updates)
         <method management>
            copy remote method to local class
            query method existance on (remote) object
         <method invocation>
            invoke method on (remote) object

     *** Sample methods ***   
     Actions (actions defined by the user's avatar by the host server)
        <movement and appearance change>
            walk
            run
            swim
            inch
            sneak
            face
            crouch
            lie down
            hide
            sit
        <communication>
            say
            emote
            whisper
            shout
    Objective (actions defined by some other object and advertised as
    available)
        look/examine
        take
        drop
        use
        give
        wear (if something is wearable)
        remove (if something is wearable)
      
Message format
    eol = \r | \n | \r\n | \n\r
    whitespace = [ \t\f] | ${eol}
    S = ${whitespace}+
    header = "<!start!>"
    footer = "<#end#>"
    msg = ${header} ${type} S ${body} ${footer}
    type = "system" | "client" | "world" | "object"
    body = ${cmd} (S ${param})*

    header and footer are constant byte patterns
    cmd is the command string

    parameters are typically:
        param = "dobj=" ${what} | "iobj=" ${what} | "str='" $value "'"
        
        what is the unique ID of the object manipulated
            ${host-id} ":" ${obj-id}
        string parameters are contained within ticks (')...ticks inside the
          ticks are escaped (\')
        legal parameters are discovered from the "list methods on object"
        which will provide templates for dobj, iobj, as well as a string
          parameter count

Communication between servers will typically use remote invocation,
with occasional local copies of trusted code.

Communication between clients and servers will typically use remote
invocation.


Unanswered Questions:
    Are gates one or two way (unidirectional or bidirectional)?

-----------------------------------------------------------------------
$Log: message_format.txt,v $
Revision 1.2  2001/06/29 01:09:40  cjones
Broken messages into different types of message, as well as common
messages that should be sent/received, as well as the role of the
message. Fleshed out and improved message format (to better allow
factory classing/typing of messages based on content).

