XML Socket Multiuser Server - eClever

Jak server pracuje?
Celá činnost serveru je v podstatě jednoduchá:
1. Klient se jménem např. client1 pošle na server zprávu určenou klientovi se jménem client2 v určitém tvaru, např.

<protocol>
     <userMsg sendTo="client2">
           <data game="27"></data>
     </userMsg>
</protocol>

2. Server přepošle klientovi se jménem client2 zprávu ve tvaru

<protocol>
      <received action="userMsg" sentFrom="test">
            <data game="27"></data>
      </received>
</protocol>

3. Server potvrdí odeslání zprávy klientovi, který zprávu odeslal. Client1 tedy dostane od serveru zprávu

<protocol>
     <response action="userMsg" errorCode="0"/>
</protocol>

Obecné informace k práci se serverem
1. Ve všech požadavcích posílaných na server můžeme použít atribut sid. Tento atribut je nepovinný a vrací se klientovi, který tento atribut použil. Atribut sid slouží pouze k přesné identifikaci dotaz-odpověď. Pokud klient atribut sid nepoužil, nebude mu ani vrácen. Atribut sid musí mít vždy jedinečnou hodnotu v rámci posílaných dotazů stejného typu, abychom mohli správně atribut sid použít k rozlišení jednotlivých dotazů. To je důležité hlavně při rychlém posílání dotazů.
2. Posíláme-li zprávu klientovi, dostane ji vždy ve tvaru

<protocol>
      <received action="userMsg">....</received>
</protocol> ,

kde action identifikuje typ doručené zprávy.
3. Odpovídá-li server klientovi, který zprávu odeslal, je odpověď vždy ve tvaru

<protocol>
       <response action=userMsg" errorCode="0" ..... />
</protocol>

Kde action identifikuje typ dotazu a errorCode je návratový kód. Pokud je vráceno errorCode="0", znamená to, že se vše správně vykonalo. V opačném případě došlo k nějaké chybě. Následující tabulka uvádí seznam obecných chyb, které vrací socket server klientovi.

errorCode		Popis chyby
0		Požadovaná operace proběhla bez chyby
-1		Špatný XML formát odesílaných dat
-2		V dotazu byl použit nedefinovaný atribut
-3		Klient není přihlášen do žádné domény
-4		Klient není přihlášen do žádné místnosti
-1000		Klient není přihlášen jako administrátor.

Další chyby budou definovány vždy u příslušné funkce.

Pozn. Atributy označené [ ] jsou nepovinné a nemusejí se v XML protokolu používat.

Protokol pro používání XML serveru
XML Socket Multiuser Server používá následující příkaz

login		Přihlášení klienta na server
roomLogin		Přihlášení klienta do místnosti
userMsg		Odeslání soukromé zprávy zvolenému klientovi
roomMsg		Odeslání zprávy všem klientům přihlášeným do místnosti
userList		Seznam klientů přihlášených do místnosti
roomList		Seznam dostupných místností
myRoom		Informace, do jaké místnosti je klient přihlášen
addRoom		Přidání místnosti do domény
addRoomGame		Přidání herní místnosti do domény.
delRoom		Zrušení místnosti
variableList		Zjištění názvů a hodnot všech proměnných v místnosti
getVariable		Zjištění hodnoty proměnné v místnosti
setVariable		Nastavení proměnné v místnosti na určitou hodnotu
addVariable		Přidání proměnné do místnosti
delVariable		Zrušení proměnné v místnosti
echo		Test odezvy serveru
serverInfo		Informace o XML Socket Multiuser Serveru
disconnect		Odpojení klienta od serveru
xtra		Používání rozšíření XML Socket Multiuser Serveru.
adminLogin		Přihlášení administrátora na server.
adminMsg		Odeslání zprávy administrátora ostatním klientům.
adminBan		Odpojení klienta od serveru administrátorem.
adminInfo		Podrobné informace o XML Socket Multiuser Serveru.
adminRestart		Restart XML Socket Multiuser Serveru.

-----------------------------------------------------------------------------------------------------------------------------------------------------------

login - Přihlášení klienta na server

Přihlášením klienta na server se klient přihlásí do určité domény, ve které dále pracuje, může využívat místnosti a proměnné této domény. Konkrétní uživatel může být z jedné klientské aplikace přihlášen vždy pouze v jedné doméně.

XML dotaz odeslaný klientem na server

<protocol>
        <login nickName="client1" domainName="demo1" domainPassword="pass1" [sid="1"]/>
 </protocol>

Atribut	Význam
nickName	Jméno, pod kterým se chceme přihlásit na server. Toto jméno musí být na serveru jedinečné, musí mít více než 2 znaky. Pokud už bylo jméno na serveru použito, server uživatele upozorní.
domainName	Jméno domain, do které se chceme přihlásit.
domainPassword	Uživatel musí k přihlášení použít heslo. Seznam použitelných hesel definuje administrátor v souboru eClever.config.

Pozn.: Příkaz login musí být odeslán na server do určité doby od připojení klienta na server. Pokud vyprší časový limit,
klient bude od serveru odpojen. Tento limit se zadává v souboru eClever.config, v parametru loginTimeOut.
Pokud několik různých klientských aplikací využívá jednu doménu, mají tyto aplikace vždy stejné parametry domainName a domainPassword. Zjednodušeně: do aplikací jednoho vývojáře se přihlašujeme vždy stejně, pokud jeho aplikace využívají jednu sekci domain.

XML odpověď serveru klientovi

<i><protocol> </i> 
       <response action="login" clientId="5F1A8894-EF25-41E0-BAF3-0DFC7675B252" errorCode="0" [sid="1"]/>
 </protocol>

Atribut	Význam
clientId	Identifikátor, který jednoznačně identifikuje každého uživatele.

errorCode	Popis chyby
11	Špatné heslo pro přihlášení na server.
12	Zadané nickName na serveru již existuje.
13	NickName má méně znaků než 4 nebo více znaků než 25.
14	Do domain se nepodařilo přihlásit, protože byl překročen maximální povolený počet přihlášených klientů.
15	Klient je již přihlášen na server. Pokud se chce přihlásit znovu do jiné domény, musí se nejprve odhlásit od serveru.

XML zpráva serveru ostatním klientům
Ostatní přihlášení klienti nedostávají žádnou zprávu.

-----------------------------------------------------------------------------------------------------------------------------------------------------------

roomLogin - Přihlášení klienta do místnosti

XML dotaz odeslaný klientem na server

<protocol>
       <roomLogin room="room1" [password="a1"] [sid="2"]/>
 </protocol>

Atribut	Význam
room	Jméno místnosti, do které se chceme přihlásit. Seznam dostupných místností získáme pomocí dotazu roomList.
password	Uživatel musí k přihlášení do místnosti použít heslo, pokud je toto heslo požadováno. Seznam místností a hesel definuje administrátor v konfiguračním souboru pro každou doménu.

XML odpověď serveru klientovi

<protocol>
      <response action="roomLogin" errorCode="0" [sid="2"] />
 </protocol>

errorCode	Popis chyby
21	Špatné přístupové údaje do místnosti.
22	Do místnosti se nepodařilo přihlásit, protože byl překročen maximální povolený počet přihlášených klientů.
23	Nepodařilo se odeslat informaci všem přihlášeným klientům v místnosti.

XML zpráva serveru ostatním klientům

<protocol>
      <received action="roomLogin" sentFrom="client1"><data room="room1"/></received>
 </protocol>

Atribut	Význam
sentFrom	Jméno klienta, který se přihlásil do místnosti.
room	Jméno místnosti, do které se klient přihlásil.

<protocol>
     <userMsg sendTo="test2" type="message" [sid="3"]>
         <data><game position="27" time="12"/></data>
     </userMsg>
 </protocol>

Atribut	Význam
sendTo	Jméno klienta, kterému chcete poslat soukromou zprávu.
type	Typ soukromé zprávy. Server nyní používá tyto hodnoty: 1. type="message", používá se při posílání obyčejné soukromé zprávy. 2. type="challenge", používá se při výzvě ke hře. 3. type= "answer", používá se při odpovědi na výzvu ke hře.
data	Vše, co umístíte do sekce <data ... ></data> , bude odesláno klientovi. Sekce data musí být samozřejmě v korektním XML formátu.

XML odpověď serveru klientovi

<protocol>
       <response action="userMsg" errorCode="0" [sid="3"]/>
 </protocol>

errorCode	Popis chyby
31	Nebyl zadán příjemce zprávy.
32	Zpráva neobsahovala sekci data.
33	Na serveru není přihlášen klient se zadaným jménem.
34	Zprávu se nepodařilo odeslat.

XML zpráva serveru ostatním klientům

<protocol>
      <received action="userMsg" sentFrom="test3" type="message">
           <data><game position="27" time="12"/></data>
      </received>
 </protocol>

Atribut	Význam
sentFrom	Jméno klienta, který zprávu zaslal.
type	Typ soukromé zprávy.
data	V této sekci jsou vlastní informace, které klient zasílá.

<protocol>
      <roomMsg [sid="4"]>
            <data><game position="27" time="12"/></data>
      </roomMsg>
 </protocol>

Atribut	Význam
data	Vše, co umístíte do sekce <data ... ></data> , bude odesláno všem klientům přihlášeným do místnosti. Sekce data musí být samozřejmě v korektním XML formátu.

Pozn.: Klient může komunikovat pouze s klienty, kteří jsou přihlášeni do stejné místnosti.

XML odpověď serveru klientovi

<protocol>
      <response action="roomMsg" errorCode="0" [sid="4"]/>
 </protocol>

errorCode	Popis chyby
41	Zpráva neobsahovala sekci data.
42	V místnosti nejsou přihlášeni žádní klienti.
43	Zprávu se nepodařilo odeslat všem klientům přihlášeným do místnosti.

XML zpráva serveru ostatním klientům

<protocol>
      <received action="roomMsg" sentFrom="test3">
           <data><game position="27" time="12"/></data>
      </received>
 </protocol>

Atribut	Význam
sentFrom	Jméno klienta, který zprávu zaslal.
data	V této sekci jsou vlastní informace, které klient posílá ostatním klientům přihlášeným do místnosti.

<protocol>
      <userList [sid="5"]/>
 </protocol>

Pozn.: Klient může získat seznam klientů přihlášených pouze v místnosti, ve které je sám přihlášen.

XML odpověď serveru klientovi

<protocol>
      <response action="userList" errorCode="0" [sid="5"]>
            <data userCount="2">
                  <nickName>client1></nickName>
                  <nickName>client2</nickName>
            </data>
      </response>
 </protocol>

Atribut	Význam
userCount	Počet klientů přihlášených do místnosti.
data	V této sekci je seznam klientů přihlášených do místnosti.

XML zpráva serveru ostatním klientům
Ostatní přihlášení klienti nedostávají žádnou zprávu.

-----------------------------------------------------------------------------------------------------------------------------------------------------------

roomList - Seznam dostupných místností

XML dotaz odeslaný klientem na server

<protocol>
      <roomList [sid="6"]/>
 </protocol>

Pozn.: Do seznamu jsou vypsány pouze místnosti, které jsou viditelné, tzn. že mají nastaveno v sekci room v konfiguračním souboru isPrivate=false.

XML odpověď serveru klientovi

<protocol>
      <response action="roomList" errorCode="0" [sid="6"]>
           <data roomCount="3">
                 <room name="room1" category="cinema" content="new movies" language="en"/>
                 <room name="room2" category="literature" content="new titles" language="en"/>
                 <room name="room3" category="science" content="science news" language="en"/>
           </data>
      </response>
 </protocol>

Atribut	Význam
roomCount	Počet viditelných místností.
data	V této sekci je seznam viditelných místností a jejich parametry.

XML zpráva serveru ostatním klientům
Ostatní přihlášení klienti nedostávají žádnou zprávu.

-----------------------------------------------------------------------------------------------------------------------------------------------------------

myRoom - Informace, do jaké místnosti je klient přihlášen

XML dotaz odeslaný klientem na server

<protocol>
      <myRoom [sid="7"]/>
 </protocol>

XML odpověď serveru klientovi

<protocol>
      <response action="myRoom" errorCode="0" [sid="7"]>
                 <data roomName="room1"/>
      </response>
 </protocol>

Atribut	Význam
roomName	Název místnosti, do které je klient přihlášen.

XML zpráva serveru ostatním klientům
Ostatní přihlášení klienti nedostávají žádnou zprávu.

-----------------------------------------------------------------------------------------------------------------------------------------------------------

addRoom - Přidání místnosti do domény

XML dotaz odeslaný klientem na server

<protocol>
      <addRoom name="d25" 
                            password="a22" 
                            isPrivate="true" 
                            isPermanent="true" 
                            maxUsers="10" 
                            category="a" 
                            content="b" 
                            languages="en" 
                            [sid="2"] />
 </protocol>

Atribut	Význam
name	Jméno místnosti, kterou chceme do domény přidat.
password	Heslo pro přístup do místnosti.
isPrivate	Volba, zda místnost je nebo není viditelná.
isPermanent	Volba, zda bude místnost smazána po odhlášení uživatele, který místnost založil. Zadáme-li isPermanent="true", místnost nebude po odhlášení zakladatele místnosti smazána. Má-li místnost nastavenu vlastnost isPermanent="true", nebudou smazány ani proměnné, které uživatel v místnosti založil. Pokud ale uživatel, který místnost založil, bude chtít místnost sám smazat pomocí funkce delRoom, samozřejmě místnost smaže.
maxUsers	Maximální počet klientů, který se může do místnosti připojit. Hodnota, kterou můžete nastavit, se pohybuje od 2 do 50.
category	Kategorie, do které chcete zařadit tuto místnost. Tento atribut má pouze informativní charakter a pro práci XML Socket Multiuser Serveru není důležitý.
content	Stručný popis místnosti. Tento atribut má pouze informativní charakter a pro práci XML Socket Multiuser Serveru není důležitý.
language	Jazyk, kterým se v této místnosti bude komunikovat. Tento atribut má pouze informativní charakter a pro práci XML Socket Multiuser Serveru není důležitý.

Pozn. Místnosti můžete přidávat pouze do domén, které mají povoleno přidávání místností. Taková doména musí mít nastaveno maxRoomsPerUser>0 a maxRooms>0.

XML odpověď serveru klientovi

<protocol>
      <response action="addRoom" errorCode="0" [sid="2"]/>
 </protocol>

errorCode	Popis chyby
101	V doméně není povoleno zakládat nové místnosti.
102	Byla překročena hodnota maxRoomsPerUser nebo maxRooms.
103	Není zadána proměnná name.
104	Místnost tohoto jména již v doméně existuje.
105	Nepodařilo se odeslat zprávu o založení místnosti všem klientům.

XML zpráva serveru ostatním klientům

<protocol>
      <received action="addRoom" name="d27" sentFrom="test"/>
</protocol>

Atribut	Význam
name	Jméno nové místnosti.
sentFrom	Jméno klienta, který místnost založil.

Pozn. Ostatní klienti přihlášení do domény dostanou zprávu pouze v případě, že nová místnost je veřejná, tj. isPrivate=false.
Pokud je nově založená místnost neveřejná, ostatní klienti žádnou zprávu neobdrží.

----------------------------------------------------------------------------------------------------------------------------------------------------------

addRoomGame - Přidání herní místnosti do domény

Při zadávání herní místnosti se vytvoří nová místnost, podobně jako u příkazu addRoom, pouze s tím rozdílem, že místnost je založena jako privátní, tj. isPrivate=true, a spolu s místností se zakládají proměnné, které budou využity při hře. Herní místnost vždy zakládá vyzývatel ke hře.

XML dotaz odeslaný klientem na server

<protocol>
      <addRoomGame name="d25" password="a22" userMax="0"  sid="2">
          <variables>
               <a>27</a>   
               <b>179</b>
               <c>John</c>          
          </variables>
      </addRoomGame>
</protocol>

Atribut	Význam
name	Jméno herní místnosti, kterou chceme do domény přidat.
password	Heslo pro přístup do herní místnosti.
maxUsers	Počet hráčů, kteří se hry zúčastní.
variables	V sekci variables zadáváme proměnné, které budeme využívat ve hře. Proměnné se zadávají ve tvaru např. <a>27</a>.

<protocol>
      <response action="addRoomGame" errorCode="0" [sid="2"]/>
 </protocol>

errorCode	Popis chyby
101	V doméně není povoleno zakládat nové místnosti.
102	Byla překročena hodnota maxRoomsPerUser nebo maxRooms.
103	Není zadána proměnná name.
104	Místnost tohoto jména již v doméně existuje.
231	V místnosti není povoleno zakládat nové proměnné.
232	Byla překročena hodnota maxVariablesPerUser nebo maxVariables.
233	Není zadána proměnná name.
234	Proměnná tohoto jména již v místnosti existuje.

XML zpráva serveru ostatním klientům
Ostatní přihlášení klienti nedostávají žádnou zprávu.

----------------------------------------------------------------------------------------------------------------------------------------------------------

delRoom - Zrušení místnosti

XML dotaz odeslaný klientem na server

<protocol>
      <delRoom name="d22" [sid="2"]/>
 </protocol>

Atribut	Význam
name	Jméno místnosti, kterou chceme v doméně zrušit.

Pozn. Místnost může zrušit pouze klient, který ji založil. Odhlásí-li se klient od XML Socket Multiuser Serveru, jsou zrušeny všechny místnosti, které klient založil. Ostatní klienti jsou o tom informováni pomocí XML funkce delRoom.

XML odpověď serveru klientovi

<protocol>
      <response action="delRoom" errorCode="0" [sid="2"]/>
 </protocol>

errorCode	Popis chyby
111	Místnost tohoto jména v doméně neexistuje.
112	Nemáte povolena práva ke zrušení této místnosti.
113	Nepodařilo se odeslat zprávu o zrušení místnosti všem klientům.

XML zpráva serveru ostatním klientům

<protocol>
      <received action="delRoom" name="d27"/>
</protocol>

Atribut	Význam
name	Jméno místnosti, která byla zrušena.

Pozn. Pokud je místnost, kterou mažeme, neveřejná, obdrží zprávu pouze klienti přihlášení do této místnosti. Ostatní klienti žádnou zprávu neobdrží.

-----------------------------------------------------------------------------------------------------------------------------------------------------------

variableList - Zjištění názvů a hodnot všech proměnných v místnosti

XML dotaz odeslaný klientem na server

<protocol>
       <variableList [sid="2"]/>
 </protocol>

Pozn.: Funkce variableList vrací pouze proměnné, které mají atribut isPrivate nastaven na hodnotu false.

XML odpověď serveru klientovi

<protocol>
      <response action="variableList" errorCode="0" [sid="2"]>
           <data variableCount="3">
                <a>18</a>
                <b>118</b>
                <c>28</c>
           </data>
      </response>
 </protocol>

Atribut	Význam
variableCount	Počet proměnných v místnosti
data	V sekci data je vrácena informace o proměnných

errorCode	Popis chyby
201	V místnosti neexistují žádné proměnné

XML zpráva serveru ostatním klientům
Ostatní přihlášení klienti nedostávají žádnou zprávu.

-----------------------------------------------------------------------------------------------------------------------------------------------------------

getVariable - Zjištění hodnoty proměnné v místnosti

XML dotaz odeslaný klientem na server

<protocol>
      <getVariable name="a" [sid="2"]/>
 </protocol>

Atribut	Význam
name	Jméno proměnné v místnosti, u které chceme zjistit její hodnotu.

XML odpověď serveru klientovi

<protocol>
      <response action="getVariable" errorCode="0" [sid="2"]>
           <data><a>18</a></data>
      </response>
 </protocol>

Atribut	Význam
data	V sekci data je vrácena informace o proměnné.

errorCode	Popis chyby
211	Proměnná tohoto jména v místnosti neexistuje.

XML zpráva serveru ostatním klientům
Ostatní přihlášení klienti nedostávají žádnou zprávu.

-----------------------------------------------------------------------------------------------------------------------------------------------------------

setVariable - Nastavení proměnné v místnosti na určitou hodnotu

XML dotaz odeslaný klientem na server

<protocol>
      <setVariable [sid="2"]>
           <data name="a">67</data> 
      </setVariable>
 </protocol>

Atribut	Význam
name	Jméno proměnné v místnosti, u které chceme změnit její hodnotu.
value	Hodnota proměnné.

XML odpověď serveru klientovi

<protocol>
      <response action="setVariable" errorCode="0" [sid="2"]/>
 </protocol>

errorCode	Popis chyby
221	Proměnná tohoto jména v místnosti neexistuje.
222	Nepodařilo se odeslat zprávu o změně proměnné všem klientům.

XML zpráva serveru ostatním klientům

<protocol>
      <received action="setVariable" sentFrom="test">
            <data><a>67</a></data>
      </received>
 </protocol>

Atribut	Význam
sentFrom	Jméno klienta, který proměnnou změnil
data	V sekci data je název změněné proměnné a její hodnota.

-----------------------------------------------------------------------------------------------------------------------------------------------------------

addVariable - Přidání proměnné do místnosti

XML dotaz odeslaný klientem na server

<protocol>
      <addVariable sid="2">
            <data name="abc" isPrivate="false">27</data>       
      </addVariable>
</protocol>

Atribut	Význam
name	Jméno proměnné, kterou chceme do místnosti přidat.
isPrivate	Volba, zda proměnná je nebo není viditelná.
value	Hodnota proměnné.

Pozn. Proměnné můžeme přidávat pouze do místností, které mají povoleno přidávání proměnných. Taková místnost musí mít nastaveno maxVariablesPerUser>0 a maxVariables>0.

XML odpověď serveru klientovi

<protocol>
      <response action="addVariable" errorCode="0" [sid="2"]/>
 </protocol>

errorCode	Popis chyby
231	V místnosti není povoleno zakládat nové proměnné.
232	Byla překročena hodnota maxVariablesPerUser nebo maxVariables.
233	Není zadána proměnná name.
234	Proměnná tohoto jména již v místnosti existuje.
235	Nepodařilo se odeslat zprávu o založení proměnné všem klientům.

XML zpráva serveru ostatním klientům

<protocol>
      <received action="addVariable" sentFrom="test">
            <data><abc>27</abc></data>
      </received>
 </protocol>

Atribut	Význam
sentFrom	Jméno klienta, který proměnnou založil.
data	V sekci data je název nové proměnné a její hodnota.

Pozn. Ostatní klienti přihlášení do místnosti dostanou zprávu pouze v případě, že nová proměnná je veřejná, tj. isPrivate=false.
Pokud je nově založená proměnná neveřejná, klienti žádnou zprávu neobdrží.

----------------------------------------------------------------------------------------------------------------------------------------------------------

delVariable - Zrušení proměnné v místnosti

XML dotaz odeslaný klientem na server

<protocol>
      <delVariable name="abc" [sid="2"]/>
</protocol>

Atribut	Význam
name	Jméno proměnné, kterou chceme v místnosti zrušit.

Pozn. Proměnnou může zrušit pouze klient, který ji založil. Odhlásí-li se klient od XML Socket Multiuser Serveru, jsou zrušeny všechny proměnné, které klient založil. Ostatní klienti jsou o tom informováni pomocí XML funkce delVariable.

XML odpověď serveru klientovi

<protocol>
      <response action="delVariable" errorCode="0" [sid="2"]/>
 </protocol>

errorCode	Popis chyby
241	Proměnná tohoto jména v místnosti neexistuje.
242	Nemáte povolena práva ke zrušení této proměnné.
243	Nepodařilo se odeslat zprávu o zrušení proměnné všem klientům.

XML zpráva serveru ostatním klientům

<protocol>
      <received action="delVariable" name="abc"/>
</protocol>

Atribut	Význam
name	Jméno proměnné, která byla zrušena.

-----------------------------------------------------------------------------------------------------------------------------------------------------------

echo - Test odezvy serveru

XML dotaz odeslaný klientem na server

<protocol>
     <echo [sid="8"]>
           <data>test</data> 
     </echo>
 </protocol>