FATAL DIMENSIONS IMPLEMENTATION OF THE INTERMUD-3 PROTOCOL ========================================================== $Id: fd_imc3.txt,v 1.1 2001/12/12 00:33:12 mud Exp $ DISCLAIMER AND LICENSE ---------------------- Please read the file LICENSE. WHAT IS INTERMUD-3 ------------------ Intermud-3 is the next generation of Intermud-protocols. It has several new aspects, not found in older protocols like Intermud and IMC2 like: - network- and client segregation. The client is more a "dumb" client, which doesn't have to worry about the network and the underlying structure. - reduced state-information. Instead of periodically all known muds to all clients, it will only send them at the beginning of the session and updates when they occur. - better documentation. See http://www.imaginary.com/protocols/intermud3.html WHAT IS IMPLEMENTED ------------------- The current implementation only has the basics in it, that is: - setup of the sessions between the router and the client. - exchange of information about muds connected between the router and the client. - exchange of information about channels between the router and the client. - the who, locate and finger command - subscription to a channel and the possibility of sending and received messages on it. DESIGN ------ The Fatal Dimensions implementation of Intermud-3 is based on this layer model: ----------------------------------------------------------- | MUD | --------------------------v-----^-------------------------- | MUD to IMC3 interface | IMC3 to MUD interface | --------------------------v-----^-------------------------- | IMC3 core | --------------------------v-----^-------------------------- | IMC3 to network interface | network to IMC3 interface | ----------------------------------------------------------- The idea is to minimize the amount changes in the MUD code, to have a high-level implementation between the MUD and the IMC3 core and to have abstract interface between the IMC3 and the network related parts. Furthermore: - There are muds on IMC3 - There are channels on IMC3. - A channel can be subscribed to. - A channel is listened to by characters. HOW IS IT IMPLEMENTED --------------------- MUD to IMC3 interface (file fd_imc3_rom.c) --------------------- - This is done by the interpret() function in the mud. - The meaning of these functions are to make sure that the parameters are checked and passed on the the IMC3 core functions. - Functions available to this layer: - find_imc3_channel_by_localname() returns the structure of the channel which is locally known by that name. - find_imc3_channel_by_name() returns the structure of the channel which is on the IMC3 network known by that name. - find_imc3_mud_by_name() returns the structure of the mud which is known by that name. - find_imc3_listener_by_char() returns the structure of the listener based on the channel and the character. IMC3 to MUD interface (several files) --------------------- - This is done by the functions called after an IMC3 packet has been received. - Right now the IMC3 to MUD interface and the IMC3 core are located in the same files. - Functions available to this layer: - IMC3_find_user() returns the structure of the player known by that name IMC3 core (several files) --------- - These are the functions which create IMC3 packets on demand of players, the functions which receive IMC3 replies on the requests they send out and the functions which act on incoming IMC3 requests. - The format of the function-names is - IMC3_process_send_() On request of the user. - IMC3_process__req() Received from the network. - IMC3_process__reply() Received from the network. IMC3 to network interface (file fd_imc3_main.c) ------------------------- - Although the maximum size of IMC3-packets is 2**32-1, the IMC3 to network buffer is 64Kb big. If a packet gets larger, it will not be appended (see IMC3_write_buffer()) - Functions available on this layer: - IMC3_write_header() Creates a new IMC3-header and writes it into the send-buffer. - IMC3_write_buffer() Writes new data into the send-buffer. - IMC3_send_buffer() Sends the data in the send-buffer to the socket and empties the buffer. - IMC3_escape() Escapes the " in a string to \" - Example: See IMC3_send_locate() in fd_imc3_locate.c network to IMC3 interface (file fd_imc3_main.c) ------------------------- - Although the maximum size of IMC3-packets is 2**32-1, the network to IMC3 buffer is 64Kb big. This is currently not checked for buffer overflows. This should be fixed. - Functions available to this layer: - IMC3_get_header() Gets the IMC3-header of an IMC3-packet. - IMC3_get_field() Gets one IMC3-field from an IMC3-packet. - IMC3_remove_quotes() Removes the quotes from an IMC3-string. - Note: IMC3_get_field works only if the router sends valid packets. If the packet is broken (for example, missing })'s) it will break the mud. This should be fixed. AVAILABLE NEW COMMANDS ---------------------- The following new commands are available: - imc3 stats gives a statistical overview of all received packets. - imc3 chanlist [all] [filter] "imc3 chanlist" gives an overview of the channels available to the mud. "imc3 chanlist all" gives an overview of all the channels available, even if the mud is not subscribed to it. - imc3 mudlist [all] [filter] "imc3 mudlist" gives an overview of all the muds currently connected to the network. "imc3 mudlist all" gives an overview of all the muds defined in the router (that is: also the ones which are down) - imc3 chanwho This gives an overview of all the people listening on a mud to this channel. - imc3 setup Subscribe the mud to an IMC3 channel and use the local name to access it. *should become a privileged command!* - imc3 listen Let the player listen to this channel. - rwho Get an overview of all people available at that mud. - rfinger @ Get the finger information of that player at that mud. - rlocate Search on the IMC3 network for a player known by this name. WHAT HASN'T BEEN DONE YET & TO DO --------------------------------- - a lot, see the list of implemented packet-types for example. - better protection for large incoming IMC3-packets (>64Kb). - make IMC3_get_field() foolproof. - let IMC3_remove_quotes() also remove the escaped "'s. - segregate the IMC3 core and IMC3 to mud functions ? - proper interpretation of colours. - loading and saving of data like subscribed channels for both the mud and the players. - data for the Intermud-3 stuff should be readable from file instead of in a .h file. - make local "hub" from which your mud connects to the router so that all your TCP traffic is machine-machine while the real TCP traffic (and thus the delay) goes machine-network-machine. THE IMPLEMENTED PACKET-TYPES ---------------------------- This is a quick summary of the packet-types. The ones with an x in front of it are handled. implemented: tell : send a message to a remote user emoteto : send an emote to a remote user x who-req : request a list of users on a remote mud x who-reply : reply with a list of users on a remote mud x finger-req : request finger information for a remote user x finger-reply : reply with finger information for a remote user x locate-req : request the location of a user x locate-reply : reply with the location of a user x chanlist-reply : reply with/update the list of available channels x channel-m : send a message over a channel x channel-e : send an emote over a channel x channel-t : send a targeted emote over a channel channel-add : register a new channel channel-remove : remove a channel from name server databases. channel-admin : administrate the participants of a channel chan-filter-req : filter a channel chan-filter-reply : return filtered channel messages to the router x chan-who-req : request a who list for people listening to a channel on a remote mud x chan-who-reply : return a requested channel who list x channel-listen : tune a mud as a whole into or out of a channel chan-user-req : request channel user's info chan-user-reply : reply with channel user's info news-read-req : retrieve a news post from an OOB news server. news-post-req : post news to an OOB news server. news-grplist-req mail : deliver an item of mail mail-ack : acknowledge a mail file-list-req : request a list of files on a remote mud file-list-reply : reply with list list file-put : send a file to a remote mud file-put-ack : acknowledge a file-put file-get-req : get a file from a remote mud file-get-reply : reply with the requested file auth-mud-req : request a mud-level authorization token auth-mud-reply : reply with a mud-level authorization token ucache-update : update cached user information x error : provide error information x startup-req-3 : provide start up information to the router x startup-reply : reply with/update the basic startup information shutdown : gracefully indicate shutdown x mudlist : reply with/update the list of available muds oob-req : request setup for OOB connection oob-begin : begin OOB communication oob-end : end one side of an OOB process