Spezifikation für die Interaktion WDSMap <=> phpmap-Server

Author:

Dominik Haumann

Wenn man ein neues Profil anlegt, kann man die phpmap als Server angeben. Dieses Dokument versucht, das spezifizierte Format der Daten festzuhalten und zu erläutern.

Version 1 der Spezifikation (WDSMap 0.3)

• Update: Die WDSMap empfängt Daten von dem phpmap-Server
  • Teil 1: Die Anfrage: WDSMap -> phpmap
  • Teil 2: Das Exportformat der Antwort: phpmap -> WDSMap
  • Datentypen
  • Werte sind implizit gesetzt
  • Traffic pro Zeile

---

Version 1 der Spezifikation (WDSMap 0.3)

Update: Die WDSMap empfängt Daten von dem phpmap-Server

Teil 1: Die Anfrage: WDSMap -> phpmap

Hier ist die WDSMap offensichtlich Client, und muss alle nötigen Informationen bei der Anfrage an die phpmap mitschicken, im Detail

• User, Groß- und Kleinschreibung beachten
• Passwort als md5-String
• Version als Integer
• Timestamp, damit die phpmap weiß, wann das letzte Update war
• WDSMap-User im HTTP-Header, somit umgehen wir Cookies
• WDSMap-Password im HTTP-Header

Wie WDSMap schickt alle Informationen im HTTP-Header mit, hier ein Beispiel eines HTTP/1.1-GET-Requests:

    GET /page/export.php HTTP/1.1
    Host: 80.34.134.62        // IP des Clients
    User-Agent: WDSMap/0.3    // Version der WDSMap: n.n, also 0.3
    WDSMap-Version: 1         // Version der Spezifikation
    WDSMap-User: username     // Groß- und Kleinschreibung beachten
    WDSMap-Password: password // md5sum
    WDSMap-Timestamp: 437234  // Unix timestamp
    WDSMap-Type: update       // Typ der Anfrage (update, import, ...)

Die phpmap kann den User beispielsweise per $_SERVER['HTTP_WDSMAP_USER'] auslesen.

Note:

WDSMap-User wird zu $_SERVER['HTTP_WDSMAP_USER'], die anderen dementsprechend.

Teil 2: Das Exportformat der Antwort: phpmap -> WDSMap

Die Daten werden als Text übertragen und die Trennung von Feldern erfolgt durch Leerzeichen. Dabei muss die Antwort enthalten

• Erfolgsmeldung (Return code)
  • bei Erfolg: 0
  • bei Fehler: 1
• neuer Timestamp
• Version des Exportformats
• Größe der Datenmenge phpmap-DataSize

Die phpmap schickt also die Antwort, der Header (Kopf) sieht so aus:

    // Header bei Erfolg
    phpmap-ReturnCode: 0      // Erfolg
    phpmap-Version: 1         // Version des Exportformats
    phpmap-Timestamp: 238762  // neuer Unix Timestamp
    phpmap-DataSize: 20932    // Größe des Daten-Bodys

    // Header bei Fehler
    phpmap-ReturnCode: 1      // Fehler
    phpmap-ErrorMessage: Text // Fehler-Nachricht ohne Anführungszeichen,
                              // z.B.: Der Benutzer existiert nicht.

Liste der ReturnCodes:

    0 Erfolg (Success)
    1 Ungültiger Login (Invalid login)
    2 Ungültiger Export-Typ (Invalid export type)
    // Neue Fehlermeldungen hier einfügen!

Der Daten-Teil sieht so aus:

    // bei Fehler: der Body ist leer

    // bei Erfolg: Zeile 1, Zeile 2, ... Zeile n
    X Y [BUILDING] [BORDERS] [STREETS] [UNITS] [FOW] [SIGHT] [TOWN_NAME] [PLAYER_NAME] [GUILD]
    X Y [BUILDING] [BORDERS] [STREETS] [UNITS] [FOW] [SIGHT] [TOWN_NAME] [PLAYER_NAME] [GUILD]
    // ...
    X Y [BUILDING] [BORDERS] [STREETS] [UNITS] [FOW] [SIGHT] [TOWN_NAME] [PLAYER_NAME] [GUILD]

Datentypen

• Vom Typ Integer sind: X Y BUILDING BORDERS STREETS UNITS FOW SIGHT
• Vom Typ String sind: TOWN_NAME PLAYER_NAME GUILD

Zu beachten ist hierbei, dass ein String in Anführugszeichen stehen muss. Beispiel einer Zeile:

X   Y   [BUILDING] [BORDERS] [STREETS] [UNITS] [FOW] [SIGHT] [TOWN_NAME] [PLAYER_NAME] [GUILD]
430 567 230        0         3         7       0     20      "Accarant"  "FooBar"      "AKB"

Werte sind implizit gesetzt

Eckige Klammern (z.B. [FOW]) bedeuten, dass die Werte implizit gesetzt werden. Konkret heißt das, dass dann ein Default-Wert existiert. Die Default-Werte im einzelnen:

• Kodierung der Koordinaten X und Y
  • X Y sind die Koordinaten des Feldes - wie auch im Spiel
  • Es existeren keine Default-Werte
• Kodierung der BUILDINGs
  • Zahl der Bitmap, z.B. 230
  • Default: 0
• Kodierung der BORDERS
  • BORDERS & 1 = N(orden)
  • BORDERS & 2 = O
  • BORDERS & 4 = S
  • BORDERS & 8 = W
  • Default: 0
  • Beispiel: 7 = 4 + 2 + 1, also Grenzen im N, O und S
• Kodierung der STREETS
  • STREETS & 1 = N(orden)
  • STREETS & 2 = O
  • STREETS & 4 = S
  • STREETS & 8 = W
  • Default: 0
  • Beispiel: 12 = 4 + 8, also geht eine Straße von Süden nach Westen
• Kodierung der UNITS
  • UNITS & 1 = Mensch
  • UNITS & 2 = Elfen
  • UNITS & 4 = Zwerge
  • UNITS & 8 = Orks
  • Default: 0
  • Beispiel: 13 = 8 + 4 + 1, also Mensch, Zwerg, Ork
• Kodierung des FOW
  • 0: kein Fog Of War
  • 1: Fog Of War (Feld verdunkelt)
  • Default: 0
• Kodierung der SIGHT
  • 0: keine (also 0) Sicht
  • INT: INT Sicht
  • Default: 0
• Kodierung der STRINGs
  • "Text goes on inside quotes"
  • Default: ""

Einige Beispiele

    // Koordinaten 15:22; 230=Sägewerk; Grenzen im S und W;
    // keine Straßen; Einheit: Elf; Rest weggelassen, also ""
    15 22 230 12 0 2

    // Gültig ist fogendes auch, das kann z.B. passieren,
    // wenn dort vorher eine Einheit war.
    15 22

Traffic pro Zeile

Zwei hypothetische Extrema beim Traffic:

    // Im Best-Case fällt an Traffic maximal an:
         X    Y    [BUILDING] [BORDERS] [STREETS] [UNITS] [FOW] [SIGHT] [TOWN_NAME] [PLAYER_NAME] [GUILD]
    max: 1500 1500
         4 + 1 + 4 = 9 bytes pro Zeile

    // Im Worst-Case fällt an Traffic an:
         X    Y    [BUILDING] [BORDERS] [STREETS] [UNITS] [FOW] [SIGHT] [TOWN_NAME] [PLAYER_NAME] [GUILD]
    max: 1500 1500 999        15        15        15      1      1       "Accarant"  "Accolon"     "WDS"
         4  +1+ 4+1+3     +  1+2      +1+2      +1+2    +1+1  +1+1 +   1+   10 +   1 + 9  +      1 + 5
         = 54 bytes pro Zeile

---