AgNet - silverware Networking Interface Kit

by silver Harloe

Doc Index

Internal Communication Specification

multiplexer <=> server messages
ID Hex Dir. & Name Arguments Notes
1 01 M=>S TICK   sent every (configurable number) of seconds from the multiplexer to the server so that the server can simply loop on a blocking read for easier writing
2 02 S=>M TERMINATE   the server can request the multiplexer go offline with this message. in normal operation, the server would not do this just because the server needs to restart, but might do this on the instigation of an administrator command to cease service for, say, hardware changes or a multiplexer upgrade. ideally, the server would send a GOING OFFLINE message first.
3 03 M=>S GOING OFFLINE   sent when the multiplexer terminates. as this will cease service, the server will probably respond by going offline as well (after, perhaps, saving data)
4 04 S=>M NOT READY   the server can send this to suspend input from the users. in normal operation, the server would do this immediately upon initial connection from the multiplexer so that it can restore the state of previously connected clients without interference. if sent while the server is 'ready', the users will receive notification just as if the server were going offline
5 05 S=>M READY   the server sends this when it is ready to operate normally, receiving all user input and logins/disconnections as they happen
6 06 S=>M GOING OFFLINE   the server should send this when going offline. the multiplexer will attempt to reconnect periodically to the server after getting this message, so the server can restart without disconencting the end-users. if end-user termination is desired, the server could follow this message up with TERMINATE
7 07 S=>M ARE YOU ALIVE   the server can use this to force the multiplexer to send a response, in case the server is unsure if the multiplexer is still operating. if the multiplexer does not respond with I AM ALIVE within a few seconds (ideally, one, but this may vary with system load), then the server may assume the multiplexer had died
8 08 M=>S I AM ALIVE   response to ARE YOU ALIVE
10 0A S=>M ACCEPT LOCALHOST ONLY   the server can use this to restrict logins to localhost only - listeners which can make such restrictions will do so, and listeners which cannot will be disabled. no end users will be disconnected, but new ones from other sites will be rejected. this allows administrators to log in before before other users in many cases. the multiplexer will respond with ACCEPTING LOCALHOST ONLY
11 0B S=>M ACCEPT ALL   the server sends this to tell the multiplexer to accept logins from anywhere. it will be up to the server to ban individual hosts on a user by user basis if that is desired. the multiplexer will start listeners which cannot restrict logins, and tell the other listeners to accept all. the multiplexer will respond with ACCEPTING ALL
12 0C S=>M TELL ME YOUR ACCEPT MODE   when the server comes online, it probably has no idea what mode the multiplexer is in. so it can (should) send this message to the multiplexer. the multiplexer will respond with either ACCEPTING LOCALHOST ONLY or ACCEPTING ALL
20 14 M=>S GOT SUBCLIENT clientkey
the multiplexer sends this when a user is accepted (the multiplexer may be configured to only accept users after determining their DNS and Identd information, if those are available). it also sends it when asked to list all subclients. in either case, the protocol depends on the listener which the client has connected through, and settings for that listener. since the multiplexer merely relays text between the client and server, it is up to the server to decide whether it wishes to alter the text based on protocol or not. see the listener protocols page for more details. the IPaddress is a string, which is either dotted-decimal format (for IPv4) such as '' or else a series of hex digits separated by colons (for IPv6, where available)
21 15 M=>S LOST SUBCLIENT clientkey sent by the multiplexer when a user disconnects without a request to disconnect the client having been sent. normally if a user sends a command to quit (in whatever form is appropriate for your server), the server would then respond with KILL SUBCLIENT and then the multiplexer would respond with KILLED SUBCLIENT, so LOST SUBCLIENT usually represents an error or drop-off from the user
22 16 S=>M KILL SUBCLIENT clientkey asks the multiplexer to terminate the user connection, the multiplexer will respond with KILLED SUBCLIENT
23 17 M=>S KILLED SUBCLIENT clientkey not to be redundant, but this is sent when the multiplexer has terminated a user at server request. before this is received, the server cannot assume the user is actually gone (but note that the baseserver implementations set a 'locally killed' variable in the subclient_info and ignore some messages from the subclient when that is set)
24 18 M=>S GOT SUBCLIENT TEXT clientkey
the multiplexer sends this when the server is 'ready' and user text is received. up to 4044 bytes of binary data are sent. depending on the listener protocol, connection speed, and amount of user input, this may represent a partial 'line' of input (where by 'line' I mean text typed until the user hits enter) or just one line, or several lines of input. the server should be written to parse any of those cases equally well, which may require saving data until another GOT SUBCLIENT TEXT message is received. of course, 'lines' of input may even be irrelevant - if you write a client that sends mouse or joystick movements, for example. strings are not null terminated, but their length is sent as part of the message argument (this is because the data sent is actually arbitrary binary data)
25 19 S=>M SEND SUBCLIENT TEXT clientkey
tells the multiplexer to send up to 4044 bytes of data to the user. if more data must be sent, multiple messages must be used (in which case you may wish to buffer the output until the next TICK message, just to keep from 'freezing' all the other users). the multiplexer passes the data along to the user without delay or buffering
26 1A S=>M SAVE SUBCLIENT INFO clientkey
allows the server to place up to 4044 bytes of data onto the multiplexer for later retrieval. the big limitation is that ONLY 4044 bytes of data per user can ever be saved. the big advantage is this may be enough to restore user state after the server goes offline and comes back. if you need more than 4044 bytes of data to restore user state, consider asking the multiplexer to save a database key and/or filename. if the user disconnects while the server is offline, the multiplexer will delete the data, so this should be relatively secure against users swapping places while the server restarts. if the server sends this message, any previous data will be replaced with the new data (with no warning). however, the server cannot assume the user data is saved unless it receives SAVED SUBCLIENT INFO
27 1B S=>M DELETE SUBCLIENT SAVED INFO clientkey tells the multiplexer to forget any saved info for the user. no response is given, and it is not an error to send this if there is no saved info already
28 1C M=>S SAVED SUBCLIENT INFO clientkey the usual response to SAVE SUBCLIENT INFO. the server is now assured it can retrieve that information unless the user disconnects
29 1D M=>S COULD NOT SAVE SUBCLIENT INFO clientkey this response is sent if there was some error saving the user state information. currently, the multiplexer will never actually send this message, and receiving it implies some error in coordination of message sizes and should be reported as a bug to the AgNet development team. if the server asks the multiplexer to save user info and the user has disconnected, a NO SUCH SUBCLIENT message is sent, instead
30 1E M=>S DELETED SUBCLIENT SAVED INFO clientkey the usual response to DELETE SUBCLIENT SAVED INFO. the other possible response is NO SUCH SUBCLIENT
33 21 S=>M GET SUBCLIENT DNS clientkey the server can send this to ask the multiplexer to ask the listener to lookup the users DNS information. this might be used if you have not configured the multiplexer to automatically ask the listeners to get this information and prefer to handle that process yourself. the multiplexer will always return with SUBCLIENT DNS IS or NO SUCH SUBCLIENT, however, the DNS string returned might be '' or '' instead of a real DNS address (depending on whether the listener implements DNS lookups or simply cannot resolve the DNS in under two seconds)
34 22 S=>M GET SUBCLIENT IDENTD clientkey similar to GET SUBCLIENT DNS except more likely to return '' or useless information. works and is semi-trustable on users who shell through good ISPs sometimes. it is always valid to ask the multiplexer this even if no listeners can get identd, as it will simply return ''
35 23 S=>M GET SUBCLIENT IDLETIME clientkey similar to GET SUBCLIENT DNS, but always returns a time in seconds or else sends NO SUCH SUBCLIENT. the server should keep track of this itself, however. this isn't even really useful on startup, since the multiplexer will send this automatically for all pre-existing users when sent GET ALL SUBCLIENT INFO. this message was included mostly for completeness. note that changes in the system clock can vary this time dramatically, even causing it to go negative (which may or may not be reflected properly by the integer parser, since it does not actually take negative numbers into account, which may be a big bug in it)
36 24 S=>M GET SUBCLIENT CONNECTTIME clientkey similar to GET SUBCLIENT IDLETIME, and with the save caveats. returns the time since the multiplexer 'accepted' the user, which depends in part on whether the multiplexer is configured to automatically get DNS and Identd info
37 25 S=>M GET SUBCLIENT SAVED INFO clientkey returns the user info which the server previous asked the multiplexer to save. possible responses are NO SUCH SUBCLIENT, THERE IS NO SUBCLIENT SAVED INFO, COULD NOT GET SUBCLIENT SAVED INFO, or SUBCLIENT SAVED INFO IS. note that under the current implementation, 'COULD NOT GET' will never actually be returned. the multiplexer will return THERE IS NO SUBCLIENT SAVED INFO if there are zero bytes of saved data, unless the mutliplexer does not think it has ever told the server that the user exists. no distinguishment is made between data saved and deleted, or data never have been received
38 26 S=>M GET ALL SUBCLIENT INFO   tells the multiplexer to send all user keys and all DNS, Identd, idle time, connect time, and saved info for all known users. this is intended for use at start up and would be pretty inefficient to use any other time. If the server wants 'all data' for a single subclient, it can only get it by sending the above five messages in quick succession (which means the protocol and ip address can only be re-retrieved with this message, which may or may not be a bug in the communication specification)
39 27 M=>S NO SUCH SUBCLIENT clientkey sent when the server requests information about a user which has disconnected or which has connected but not been reported to server (which probably means the mutliplexer is still awaiting DNS and/or Identd info from the listener). this is also sent when the server tries to send text to or kill a user which has not been reported to the server, which is an attempt to insure that a user connecting to the same port which was emptied recently will not inherit the old user's state
40 28 M=>S SUBCLIENT DNS IS clientkey
sent under conditions outlined above, and when the user first connects if the multiplexer is configured to automatically get DNS. can be '' if the listener could not resolve the DNS info in two seconds, or '' if the listener is not able to resolve DNS (such as a listener which relays messages through AIM or ICQ)
41 29 M=>S SUBCLIENT IDENTD IS clientkey
similar to SUBCLIENT DNS IS in circumstance, but more likely to return '' or useless information
similar to SUBCLIENT DNS IS in circumstance, though never sent when the client first logs in (idletime is assumed zero, though it may technically be as high as five seconds if DNS and Identd lookup were slow). always returns a value, though the caveat about system clock changes from GET SUBCLIENT IDLETIME applies
just like SUBCLIENT IDLETIME IS in circumstance and warnings, and see GET SUBCLIENT CONNECTTIME for the exact meaning of it
similar to SUBCLIENT DNS IS in circumstance, though never returned when a user first logs in (as they should have none). however, as a zero-byte argument is invalid, there also exists a THERE IS NO SUBCLIENT SAVED INFO for response to GET SUBCLIENT SAVED INFO requests
45 2D M=>S THERE IS NO SUBCLIENT SAVED INFO clientkey see GET SUBCLIENT SAVED INFO, DELETE SUBCLIENT SAVED INFO, and SUBCLIENT SAVED INFO IS above for references to when this message is sent
46 2E M=>S COULD NOT GET SUBCLIENT SAVED INFO clientkey currently never used. was originally written in case the multiplexer used run-time memory allocation to handle saved info requests. to be fully able to handle multiplexer upgrades, the server should probably treat this as COULD NOT GET SUBCLIENT SAVED INFO, though
47 2F M=>S DONE SENDING SUBCLIENT INFO clientkey this is sent when a user is accepted by the multiplexer and from one two three messages are sent to the server (GOT SUBCLIENT, SUBCLIENT DNS IS, SUBCLIENT IDENTD IS, depending on whether the multiplexer is configured to automatically try to get the latter two). depending on the server, it may just simply ignore this message, or else try to be really picky and check whether data it thought the multiplexer was configured to send was really sent. the other time this message is sent is as a 'break' between users when the multiplexer is replying to GET ALL SUBCLIENT INFO
48 30 M=>S DONE SENDING ALL SUBCLIENT INFO   sent when the multiplexer is done looping over users after a GET ALL SUBCLIENT INFO request. the handler for this message is probably the place to decide whether to send READY and go online or not (unless the server foolishly asked for all subclient info during 'ready' operation)

multiplexer <=> listener messages

Doc Index

This project is hosted by Logo project homepage silver's homepage