MetaServerAPI ============= Notice ------ This API should not be modified. The canonical source is: https://github.com/worldforge/metaserver-ng Files ----- MetaServerAPI.hpp The main and only include. MetaServerVersion.hpp Contains build information about MetaServer that API was generated against. MetaServerProtocol.hpp Definition of the protocol for communications (much is duplicated here) MetaServerPacket.hpp MetaServerPacket.cpp Definition and implementation for the MSP Packet Protocl Details ---------------------- NMT_NULL Description: empty packet Type Size: 4 bytes Value: 0 Payload Size: 0 Note: While this is technically a valid packet it has no practical use. NMT_SERVERKEEPALIVE Description: A game server keep-alive packet, part 1 of a 3-packet handshake Type Size: 4 bytes Value: 1 ( 00 00 00 01 ) Payload Size: 0 NMT_CLIENTKEEPALIVE Description: The game client keep-alive packet, part 1 of 3-packet handshake Type Size: 4 bytes Value: 2 ( 00 00 00 02 ) Payload Size: 0 NMT_HANDSHAKE Description: The metaserver response to a SERVERKEEPALIVE or CLIENTKEEPALIVE, part 2 of 3-packet handshake Contains a random number. Type Size: 4 bytes Value: 3 ( 00 00 00 03 ) Payload Size: 4 bytes ( a random int ) NMT_SERVERSHAKE Description: The game server response to a HANDSHAKE, part 3 of 3-packet handshake. Triggers a new game server sesssion to be created, or updated. Type Size: 4 bytes Value: 4 ( 00 00 00 04 ) Payload Size: 4 bytes ( random int ) NMT_CLIENTSHAKE Description: The game client response to a HANDSHAKE, part 3 of a 3-packet handshake Type Size: 4 bytes Value: 5 ( 00 00 00 05 ) Payload Size: 4 bytes ( random int ) NMT_TERMINATE Description: The game client or server can terminate it's session by sending this. Type Size: 4 bytes Value: 6 ( 00 00 00 06 ) Payload Size: 0 NMT_LISTREQ Description: A client request to give a list of servers Type Size: 4 bytes Value: 7 ( 00 00 00 07 ) Payload Size: 4 bytes ( int of the offset ) Note: The offset value in case that a single LISTRESP is not enough, this offset allows a request starting at a specific point in the list. NMT_LISTRESP Description: The metaserver response with the values of IPs. Type Size: 4 bytes Value: 8 ( 00 00 00 08 ) Payload Size: Variable 4 bytes - int total servers sent 4 bytes - int packed servers sent 4 bytes - a 4 byte block representing EACH IP of the servers. So if packed was set to 6, this block would be 24 bytes long. Note: If you have 10 servers, and only 5 fit into the packet, then you would send total server == 10, and packed == 5. The client would then send a new request with the offset of 5, and a secondary LISTRESP would be packed and sent. The client would be responsible for assembling this information. NMT_PROTO_ERANGE Description: Used to indicate requesting LISTREQ is out of bounds. Type Size: 4 bytes Value: 9 ( 00 00 00 09 ) Payload Size: 0 Note: Obsolete. NMT_LAST Description: Unknown Type Size: 4 bytes Value: 10 ( 00 00 00 0A ) Payload Size: 0 Note: Obsolete. NMT_SERVERATTR Description: Register a name, value pair against the session. Type Size: 4 bytes Value: 11 ( 00 00 00 0B ) Payload Size: Variable 4 bytes - int size of the name 4 bytes - int size of the value n bytes - concatination of both name + value strings E.g. 'foo=bar' 3 - size of name 3 - size of value 6 - 'foobar' size of concat NMT_CLIENTATTR Description: Register a name value pair against a client session Type Size: 4 bytes Value: 12 ( 00 00 00 0C ) Payload Size: Variable Note: exactly same symantic as SERVERATTR NMT_CLIENTFILTER Description: Setup client filter, as a name, value pair Type Size: 4 bytes Value 13 ( 00 00 00 0D ) Payload Size: Variable. Same as SERVERATTR Note: TBD, not in use NMT_ATTRRESP Description: Attribute response Type Size: 4 bytes Value: 14 ( 00 00 00 0E ) Note: TBD, not in use. NMT_SERVERCLEAR Description: clears all attributes against this session Type Size: 4 bytes Value: 15 ( 00 00 00 0F ) NMT_CLIENTCLEAR Description: clears all attributes against this session Type Size: 4 bytes Value: 16 ( 00 00 00 10 ) NMT_MONITOR Description: interface to request internals Type Size: 4 bytes Value: 21 ( 00 00 00 15 ) Note: TBD, not implemented NMT_ADMIN Description: interface into effect change in metaserver Type Size: 4 bytes Value: 25 ( 00 00 00 19 ) Note: TBD, not implemented NMT_DNSREQ Description: Non-authenticated query in order find the queried server Type Size: 4 bytes Value: 32 ( 00 00 00 20 ) Payload Size: Variable 4 bytes - int size of the string n bytes - 4 bytes per n Note: response to this is going to be a dnsresp, almost identical to listresp. NMT_DNSRESP Description: packed response to a dnsreq Type Size: 4 bytes Value: 33 ( 00 00 00 21 ) Payload Size: Variable 4 bytes - total server sent 4 bytes - packed server sent 4 bytes - length of string, one for each packed server, so 3 servers, has 12 (4*3) int bytes n bytes - entire concatenated msg that will be sum of the size of all packed server lengths E.g: 33 05 05 06 04 07 07 04 foobarwaka1.2.3.4a.b.c.dtest 33 (4) - for packet type 05 (4) - int total server count 05 (4) - int packed server count 06 (4) - length of resp 1 04 (4) - length 0f resp 2 07 (4) - length of resp 3 07 (4) - length of resp 4 04 (4) - length of resp 5 foo(28) - message (6) foobar - server 1 (4) waka - server 2 (7) 1.2.3.4 - server 3 (7) a.b.c.d - server 4 (4) test - server 5 Total: 32 + 28 == 60 bytes ( plus about 12 bytes overhead ) Reasonably likely to fit 10 responses or so per packet, it's a bit heavier that the listresp because it's parsing IPs as strings ... so rather than 1.2.3.4 becoming 4 bytes, it's now 7 ... and 123.123.123.123 is 15 bytes, instead of 4. Sample Use Cases ---------------- Use Case 1: Server Registration or Keep-alive. Only servers with sessions can perform additional requests, such as attribute registration/removal. 1) Game Server sends a NMT_SERVERKEEPALIVE 2) MS responds with a NMT_HANDSHAKE, contains a random number, creates a handshake 3) Game Server responds with NMT_SERVERSHAKE, contains same random number AND handshake exists, creates session ( if session exists, expiry time is adjusted/renewed ) Use Case 2: Game Server Shutdown / Quit 1) Game Server sends a NMT_TERMINATE, if session exists, it is removed. Use Case 3: Client Registration or Keep-alive. Only clients with sessions can perform additional requests, such as LIST, FILTER, etc. 1) Game Client sends a NMT_CLIENTKEEPALIVE 2) MS responds with a NMT_HANDSHAKE, contains random number, creates a handshake 3) Game Client responds with NMT_CLIENTSHAKE, contains same random number AND handshake exists, creates a client session ( if session exists, expiry time is adjusted ).