XML-RPC

XML-RPC je protokol, s jehož pomocí lze velice jednoduše provádět vzdálené volání procedur. XML-RPC nepřineslo do světa vzdáleného volání procedur novou technologii. Jedná se totiž o soubor pravidel, které pouze říkají, jak použít již funkční a dokonce standardizované technologie pro potřeby RPC. Data jsou zapouzdřena pomocí značkovacího jazyka XML (eXtensible Markup Language) a přenášena díky protokolu HTTP. Taková koncepce umožňuje aplikacím, napsaným v různých programovacích jazycích, komunikaci mezi různými počítačovými architekturami a jejich operačními systémy.

V současné době je projekt ukončen, nicméně stal se předlohou pro protokol SOAP.

Specifikace

Komunikace probíhá na bázi klient-server. Klient odešle serveru požadavek na vykonání činnosti, server požadavek zpracuje a zpět klientovi vrátí buď odpověď, nebo chybu. Každá ze zpráv, které si mezi sebou klient se serverem vyměňují, se skládá z hlavičky a samotného těla zprávy.

Specifikace požadavku

Hlavička

První údaj v prvním řádku hlavičky požadavku indikuje druh dotazu, což je v případě XML-RPC vždy „POST“. Druhá položka nese informaci o umístění XML-RPC serveru (tzv. URI). Neexistuje žádný zvláštní požadavek na URI, může být zadáno třeba jen lomítko, nebo může být dokonce prázdné. Třetím údaj definuje verzi a druh protokolu – pro potřeby XML-RPC se používá „HTTP/1.0“. Další čtyři řádky se skládají vždy z názvu položky a hodnoty („název: hodnota“) a jsou povinné. První ze čtveřice – „User-agent“ – obvykle informuje druh a verzi implementace. Řádek „Host“ určuje adresu počítače, na kterém běží XML-RPC server. „Content-Type“ značí druh odesílaných dat, musí mít vždy hodnotu „text/xml“. „Content-length“ udává délku dokumentu a ta musí být správně určena.

 POST /server HTTP/1.0
 User-Agent: identifikace_klienta
 Host: xmlrpc.moje-domena.cz
 Content-Type: text/xml
 Content-length: pocet_znaku

Tělo

Tělo požadavku musí uvozovat značka „<methodCall>“. Jedná se o párovou značku, jejímž uzavíracím ekvivalentem „</methodCall>“ je potřeba tělo, respektive celý dokument, ukončit. Uvnitř této značky se nachází párová značka „<methodName>“, udávající název volané procedury (volaná procedura nemusí být ve skutečnosti procedurou, lze stejně dobře jako proceduru volat například tabulku či sloupec tabulky v databázi, záleží na konkrétní implementaci XML-RPC). V názvu procedury se smí vyskytovat pouze velká a malá písmenka A-Z, číslice 0-9, podtržítko, tečka, pomlčka a lomítko. Zároveň podle specifikace záleží jen na serveru, jak se vypořádat se znaky v názvu procedury. Po značkách „<methodName>“ následuje seznam parametrů předávaných vzdálené proceduře (pokud tato nějaké vyžaduje, v opačném případě není nutné, dokonce ani povolené, je uvádět). Parametry se uvozují párovými značkami „<params>“, mezi něž lze vložit libovolný počet parametrů (slovem „libovolný“ míním, že specifikace jejich počet nikterak neomezuje, počet omezuje pouze definice procedury). Každý parametr je uzavřen mezi značkami „<param>“, v nichž se nachází jeho hodnota mezi značkami „<value>“ s volitelnou definicí datového typu (obecně se doporučuje datový typ uvádět vždy pro zlepšení čitelnosti nebo pro předejití chyb z nepozornosti). Pokud existuje definice parametru, musí být vnořena do značky „<value>“.

 POST /server HTTP/1.0
 User-Agent: Mozilla/5.0 (Windows; U; Windows NT 5.1; cs-CZ; rv:1.9.0.11) Gecko/2009060215 Firefox/3.0.11 
 Host: xmlrpc.example.com
 Content-Type: text/xml
 Content-length: 314

 <?xml version="1.0"?>
 <methodCall>
   <methodName>trida.jmenoMetody</methodName>
   <params>
     <param>
       <value><int>250</int></value>
     </param>
     <param>
       <value><base64>WiBXaWtpcGVkaWUsIG90ZXbFmWVuw6kgZW5jeWtsb3BlZGll</base64></value>
     </param>
   </params>
 </methodCall>

Specifikace odpovědi

Hlavička

První položka prvního řádku značí verzi protokolu (vždy HTTP/1.1), za ní následuje stavový kód, který má ve většině případů hodnotu 200 OK, což znamená, že server obdržel požadavek a posílá odpověď (jiný stavový kód může být vrácen například v případě, že serverová část je napsána v jazyce PHP, jenž se dost často zavádí jako modul do webového serveru Apache, ten může v případě chyby vyslat i jiný, než „200 OK“ stavový kód).

Řádek „Connection“ obsahuje hodnotu „close“, díky čemuž klient pozná, že pokud chce serveru opět vyslat požadavek, musí navázat nové připojení. „Content-Length“ opět udává délku dokumentu a taktéž vyžaduje korektní hodnotu. Pole „Content-type“, stejně jako v hlavičce požadavku, nabývá pouze hodnot „text/xml“. Řádek „Date“ předává informaci o době odeslání odpovědi a to ve formátu RFC 822, updatovaném RFC 1123, který je považován za internetový standard (existují ještě dva další formáty data a času, s nimiž si musí být případní klienti/servery schopní poradit; je to důsledek zpětné kompatibility mezi protokoly HTTP/1.0 a HTTP/1.1, přestože odpověď není možné odeslat jinak než v HTTP/1.1, tento protokol však umožňuje odesílat datum pouze ve zmíněném formátu RFC 822/RFC 1123). Poslední položka hlavičky, a sice položka „Server“, informuje o jménu serveru odesílajícího odpověď.

 HTTP/1.1 200 OK
 Connection: close
 Content-Length: pocet_znaku
 Content-Type: text/xml
 Date: Fri, 29 May 2007 16:31:06 GMT
 Server: identifikace_serveru

Tělo

Tělo odpovědi tvoří velice jednoduchá XML struktura – značky „<methodResponse>“, mezi kterými se, na rozdíl od dotazu, musí vyskytnout párová značka „<params>“. Taktéž uvnitř musí existovat alespoň jedna značka „<param>“ obsahující hodnotu, případně datový typ.

 HTTP/1.1 200 OK
 Connection: close
 Content-Length: pocet_znaku
 Content-Type: text/xml
 Date: Fri, 29 May 2007 16:35:15 GMT
 Server: identifikace_serveru

 <?xml version="1.0"?>
 <methodResponse>
 	<params>
 		<param>
 			<value><string>Text odpovědi</string></value>
 		</param>
 	</params>
 </methodResponse>

Specifikace chybové odpovědi

Hlavička

Stejná jako hlavička odpovědi, protože chybová odpověď je také odpovědí, pouze se striktně definovanou strukturou těla.

Tělo

Tělo chybové odpovědi se uvozuje značkami „<methodResponse>“ následovanými značkami „<fault>“ – jakýsi ekvivalent k „<param>“, ovšem bez vnějšího „<params>“. Uvnitř se nachází značka „<value>“ obsahující datový typ „struct“. Struct má zde dva členy, první – „faultCode“ – udává číslo chyby, „faultString“ v sobě nese textovou část chyby. Toto číslo ani text není definováno, pouze se musí dodržet datové typy, jinak záleží čistě na implementátorovi serveru, jaká čísla si pro chyby vymyslí (existuje rozšíření definující několik běžných chyb, má však pouze doporučující charakter, nikoliv závazný).

Důležité upozornění: odpověď, ať už běžná nebo chybová, smí obsahovat buď „<params>“, nebo „<fault>“. Jiné struktury nejsou přípustné a slovo „nebo“ je míněno ve vylučovacím smyslu (tzn. nemohou nastat obě možnosti zároveň).

 HTTP/1.1 200 OK
 Connection: close
 Content-Length: pocet_znaku
 Content-Type: text/xml
 Date: Fri, 29 May 2007 16:35:15 GMT
 Server: identifikace_serveru

 <?xml version="1.0"?>
 <methodResponse>
 	<fault>
 		<value>
 			<struct>
 				<member>
 					<name>faultCode</name>
 					<value><int>32001</int></value>
 				</member>
 				<member>
 					<name>faultString</name>
 					<value><string>Text chyby</string></value>
 				</member>
 			</struct>
 		</value>
 	</fault>
 </methodResponse>

Datové typy

XML-RPC v základním rozšíření definuje šest jednorozměrných a dva vícerozměrné datové typy.

Jednorozměrné

Tabulka 1: datové typy

Značka	Typ	Příklad
<i4> nebo <int>	32bitové celé číslo (integer)	<int>-12</int>
<double>	Číslo s plovoucí řádovou tečkou a dvojnásobnou přesností dle IEEE 754 (double)	<double>-123.21</double>
<boolean>	Booleovská hodnota – pouze 0 (pro hodnotu `false`) nebo 1 (pro hodnotu `true`)	<boolean>1</boolean>
<string>	Textový řetězec (string)	<string>Pozdravuj doma</string>
<dateTime.iso8601>	Datum a čas podle normy ISO 8601	<dateTime.iso8601>20070529T16:00:00</dateTime.iso8601>
<base64>	zakódovaná binární data podle algoritmu base64	<base64>eW91IGNhbid0IHJlYWQgdGhpcyE=</base64>
rozšířené typy	musí být podporovány vlastností `enabledForExtensions`
<ex:nil>	beztypová prázdná hodnota (obdoba null)	<ex:nil></ex:nil>
<ex:i1>, <ex:i2>, <ex:i8>, <ex:biginteger>	celá čísla s různou bitovou šířkou (8, 16 resp. 64 bitů pro i1, i2 resp. i8, které doplňují 32bitové <i4>) a volitelný počet číslic pro <biginteger>.	<ex:i1>127</ex:i1>
<ex:float>, <ex:bigdecimal>	číslo s plovoucí desetinnou tečkou. U <float> s jednoduchou přesností dle IEEE 754, u bigdecimal s přesností volitelnou	<ex:float>5.4</ex:float>
<ex:dateTime>	rozšířená reprezentace data, včetně milisekund a časové zóny	<dateTime>20070529T16:00:00.99 +0100</dateTime>

Zdroj: [1]

Poznámka: Integer se smí skládat pouze z číslic, případně znaménkem před číslem samotným, nesmí obsahovat mezeru. Double navíc obsahuje desetinnou tečku, zároveň ale jeho rozsah záleží na konkrétní implementaci. Typ string povoluje jakékoliv znaky kromě znaku „<“ (menší než) a „&“, tyto dva znaky se převádějí na příslušné entity „<“ a „&“. String lze také použít pro přenos binárních dat. XML-RPC neumí vyjádřit nekonečno, záporné nekonečno nebo NaN (not a number).

Vícerozměrné datové typy

Array

Značka „<array>“ obsahuje jediný blok ohraničený pomocí „<data>“. Vnitřek bloku je složen z libovolného počtu hodnot, každou z nich obklopují dříve popsané značky „<value>“. Hodnoty pole nemají názvy ani indexy, na druhou stranu mohou obsahovat další pole, nebo strukturu.

 <array>
 	<data>
 		<value><i4>8</i4></value>
 		<value><string>Pepa</string></value>
 		<value><boolean>false</boolean></value>
 		<value><double>2100.45</double></value>
 	</data>
 </array>

Struct

Druhým datovým typem je „struct“ (struktura), uvozený značkou „<struct>“, v jejímž těle lze uvést libovolný počet prvků „<member>“, z nichž každý nese informaci o jméně – „<name>“ – a o hodnotě – „<value>“. Obdobně jako pole, i struktura může být rekurzivní, tzn. že jako hodnota se dá uložit další struktura, nebo pole.

 <struct>
 	<member>
 		<name>prvniPolozka</name>
 		<value><string>Text prvni polozky</string></value>
 	</member>
 	<member>
 		<name>druhaPolozka</name>
 		<value><string>Text druhe polozky</string></value>
 	</member>
 </struct>

Rozšířené vícerozměrné typy

Značka	Typ
<ex:dom>	uzel DOM
<ex:serializable>	speciálně uložený (serializovaný) objekt, zkonvertovaný podle algoritmu base64

Literatura

SCHLOSSNAGLE, George. Pokročilé programování v PHP 5. Brno: Zoner Press, 2004. ISBN 80-86815-14-5.

Externí odkazy