MKWii Network Protocol/PARAM-STRING

From Custom Mario Kart
Jump to: navigation, search

This pages is related to MKWii Network Protocol and describes the packet type PARAM-STRING.

Description

PARAM-STRING is a very simple protocol to transfer named parameters and their values. The complete data is sent as a ASCII string using the format:

\NAME1\VALUE1\NAME2\VALUE2\NAME3\VALUE3\...\FINAL\

The PARAM-STRING itself is not null terminated, only the packet length defined the end of the string. The backslash character ("\") is used as a separator and can't be used for the values. After splitting the string at the backslash separator you have an even number of substrings. 2 substrings together are one PARAMETER with NAME and VALUE. The parameter LIST is always terminated by a final parameter with an empty value. A PARAM-STRING may contain 1 or more LISTS.

If TCP is used for data transmission, the PSH flag is always set to push all buffered data to the receiving application and to avoid an unwanted data split.

Naming Convention & Syntax

PARAM_STRING    := COMPLETE_LIST  [ PARAM_STRING ]
COMPLETE_LIST   := LIST  FINAL_PARAM
LIST            := PARAMETER  [ LIST ]
PARAMETER       := '\' NAME '\' VALUE
NAME            := NAME_CHAR  [ NAME ]
NAME_CHAR       := 'a' | 'b' | ... | 'z'
VALUE           := VALUE_CHAR  [ VALUE ]
VALUE_CHAR      := any_but_not_backslash
FINAL_PARAMETER := '\final\'

Some notes:

any_but_not_backslash
Any character (also an ASCII control character), but not a backslash.
'...'
A literal character or string.
[...]
Optional parts. They are often used as self reference to define a list of the same element.
|
An alternative element. Use exact one of the alternatives.
If there is a slash (/) in the data that does not indicate a new sub section, it is escaped with "/1". A backslash (\) in the data (not indicating a new parameter) is escaped with "/2".

Display Scheme

Here is an example string:

\name1\\name2\VALUE2\name3\VALUE3\final\\name4\\name5\VALUE5\final\

A more readable representation of the same string (also used by mkw-ana) is:

    name1 =
    name2 = VALUE2
    name3 = VALUE3
    final /
    name4 =
    name5 = VALUE5
    final /
The parameter documentation in this wiki uses this scheme often.

Sub-Lists

Some values are itself a parameter list with a different separator character. 2 examples are statstring and msg:

statstring = /SCM/1/SCN/0/VER/90
       msg = |s|1|ss|/SCM/1/SCN/0/VER/90|ls||ip|633988064|p|0|qm|0

Interesting is, that msg contains a statstring (abbreviated to ss) third level sub list.

Special Packets

Sometime you can find packets with 0, 2 or 6 NULL bytes. These packets without content are used for TCP sync, finish, reset and acknowledge (see the TCP flags byte).

Examples

In the following example, the parameter statstring contains a parameter string with a slash as separator.

          status = 1
         sesskey = 262611642
      statstring = /SCM/1/SCN/0/VER/90
       locstring =
           final /

       updatepro =
         sesskey = 262611642
       firstname = Wii:4113862228885420@RMCE
       partnerid = 11
           final /

In the next example, the parameter msg contains a parameter string with a pipe as separator.

              bm = 100
               f = 295941470
             msg = |s|0|ss|Offline
           final /

Usage

The following servers use PARAM-STRING packets for data transmission: