Specifiche di protocollo
Versione 1.2 Maggio 2009
Questa versione: TreasureHuntProtocol12
Ultima versione: TreasureHuntProtocol12
Versione Precedente: TreasureHuntProtocol11
Autori: FabioVitali, AngeloDiIorio, SilvioPeroni
Il protocollo THP (Treasure Hunt Protocol) consente ad una applicazione web di interrogare un server che eroga indizi ed informazioni relative ad un'applicazione di caccia al tesoro. Tale applicazione, chiamata Treasure Hunt, è sviluppata all'interno del corso di Tecnologie Web 2009.
L'architettura generale prevede l'interazione di due componenti fondamentali:
Questo documento descrive le specifiche del protocollo THP, protocollo di comunicazione tra ogni THC ed il THS che gestisce la caccia al tesoro. In questo documento sono quindi riportati sia il formato delle richieste da inoltrare verso il THS, sia il formato delle risposte che il THS manda al THC.
Questo documento è stato redatto da Fabio Vitali, Angelo Di Iorio e Silvio Peroni. Deve essere utilizzato come materiale di riferimento per il progetto Treasure Hunt per garantire l'interoperabilità fra i gruppi. Questo documento è la versione 1.0 del protocollo ed è soggetto a modifiche, se i vari team lo riterranno opportuno. E' possibile, infatti, emettere i documenti di riferimento aggiornati, numerati e versionati, che verranno usati per le specifiche di interoperabilità . Importante: le modifiche al protocollo non sono obbligatorie. E' tuttavia possibile apportare modifiche CON IL CONSENSO DI TUTTI I GRUPPI PARTECIPANTI AL PROGETTO.
Lo scopo del protocollo THP è permettere ad un'applicazione web (THC) di comunicare con un'altra applicazione che gestisce la caccia al tesoro, in modo centralizzato.
Tutte le comunicazioni avvengono su canali HTTP e le risposte del THS sono in formato XML. Le richieste, invece, sono gestite con architettura REST. Questo vuol dire che per ogni richiesta (risposta) il protocollo specifica sia la struttura dell'URL per indicare i parametri della richiesta (risposta) e sia il corpo della richiesta (risposta) HTTP.
Il capitolo 2 descrive le query al THS mentre il capitolo 3 contiene dettagli sui vari tipi di flussi XML generati dal THS.
Questo protocollo specifica il formato dei vari frammenti XML usando XML-Schema. Poichè alcuni elementi e tipi sono comuni a più content-model, il capitolo 4 descrive questi tipi globali.
NB: lo scambio dei vari frammenti XML tra THC e THS deve avvenire inserendo le stringhe che essi descrivono come valore del parametro xml
da utilizzare nella comunicazione.
L'applicazione THC può inoltrare le seguenti richieste all'applicazione THS:
Le richieste sono effettuate via HTTP, con un approccio REST. In particolare tutti gli URL hanno la stessa struttura:
http://[URL DEL SERVER]/[NOME DELL'OPERAZIONE TUTTO IN MINUSCOLO]
Pertanto, un esempio di richiesta è http://www.cs.unibo.it/server-di-tw/getstatus
La risposta è in formato XML e contenuto nel body della risposta HTTP.
Le seguenti sottosezioni spiegano in dettaglio le caratteristiche ed il formato di ogni operazione prevista dal protocollo.
Tramite questa richiesta il THC chiede al THS l'elenco delle cacce caricate sul server. La risposta sarà una lista di identificatori di cacce, come specificato in sezione 3.1.
Il nome dell'operazione è getTreasureHunts, pertanto la richiesta sarà un GET HTTP a:
http://[nome server]/gettreasurehunts
Tramite questa richiesta il THC iscrive un utente o un gruppo alla caccia al tesoro.
La richiesta specifica tre parametri:
Il nome dell'operazione è sendSubscription, pertanto la richiesta sarà un POST HTTP a:
http://[nome server]/sendsubscription
Il body della richiesta HTTP contiene i parametri ed è un frammento XML validato dal seguente XML-Schema:
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified"
targetNamespace="http://vitali.web.cs.unbo.it/thunt" xmlns:thunt="http://vitali.web.cs.unbo.it/thunt">
<xs:element name="sendSubscription">
<xs:complexType>
<xs:choice>
<xs:element ref="thunt:user"/>
<xs:element ref="thunt:group"/>
</xs:choice>
</xs:complexType>
</xs:element>
<xs:element name="user">
<xs:complexType>
<xs:attributeGroup ref="thunt:attribute.id"/>
<xs:attributeGroup ref="thunt:attribute.pwd"/>
<xs:attributeGroup ref="thunt:attribute.thunt"/>
</xs:complexType>
</xs:element>
<xs:element name="group">
<xs:complexType>
<xs:attributeGroup ref="thunt:attribute.id"/>
<xs:attributeGroup ref="thunt:attribute.pwd"/>
<xs:attributeGroup ref="thunt:attribute.thunt"/>
</xs:complexType>
</xs:element>
<!-- Id dell'utente o del gruppo che vuole effettuare l'iscrizione -->
<xs:attributeGroup name="attribute.id">
<xs:attribute name="id" use="required" type="xs:string"/>
</xs:attributeGroup>
<!-- Id dell'utente o del gruppo che vuole effettuare l'iscrizione -->
<xs:attributeGroup name="attribute.pwd">
<xs:attribute name="pwd" use="required" type="xs:string"/>
</xs:attributeGroup>
<!-- Id della caccia al tesoro a cui si ci vuole iscrivere -->
<xs:attributeGroup name="attribute.thunt">
<xs:attribute name="thunt" use="required" type="xs:string"/>
</xs:attributeGroup>
</xs:schema>
Tramite questa richiesta il THC chiede l'indizio successivo.
La richiesta specifica due parametri:
Il nome dell'operazione è getHint, pertanto la richiesta sarà un POST HTTP a:
http://[nome server]/gethint
Il body della richiesta HTTP contiene i parametri ed è un frammento XML validato dal seguente XML-Schema:
<?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:thunt="http://vitali.web.cs.unbo.it/thunt"
targetNamespace="http://vitali.web.cs.unbo.it/thunt" elementFormDefault="qualified">
<xs:element name="getHint">
<xs:complexType>
<xs:attribute name="id" type="xs:string" use="required"/>
<xs:attribute name="pwd" type="xs:string" use="required"/>
<xs:attribute name="thunt" type="xs:string" use="required"/>
</xs:complexType>
</xs:element>
</xs:schema>
Tramite questa richiesta il THC spedisce al server la risposta relativa al turno corrente.
La richiesta specifica tre parametri:
Il nome dell'operazione è submitAnswer, pertanto la richiesta sarà un POST HTTP a:
http://[nome server]/submitanswer
Il body della richiesta HTTP contiene i parametri ed è un frammento XML validato dal seguente XML-Schema.
Importante: lo schema non è completo, ma fa riferimento ai tipi globali descritti nella sezione 5.
<?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:thunt="http://vitali.web.cs.unbo.it/thunt"
targetNamespace="http://vitali.web.cs.unbo.it/thunt" elementFormDefault="qualified">
<xs:element name="submitAnswer">
<xs:complexType>
<xs:choice>
<xs:element name="URI" type="xs:anyURI"/>
<xs:element name="geoloc" type="Tlocation"/>
<xs:element name="picture" type="Tpicture"/>
<xs:element name="video" type="Tvideo"/>
<xs:element name="string" type="xs:string"/>
</xs:choice>
<xs:attribute name="id" type="xs:string" use="required"/>
<xs:attribute name="pwd" type="xs:string" use="required"/>
<xs:attribute name="thunt" type="xs:string" use="required"/>
<!-- Id dell'utente o del gruppo che vuole ricevere l'indizio attuale -->
<!-- Password dell'utente o del gruppo che vuole ricevere l'indizio attuale -->
<!-- Id della caccia al tesoro di cui si vuole l'indizio -->
</xs:complexType>
</xs:element>
...
</xs:schema>
Tramite questa richiesta il THC chiede al THS lo status degli altri team. In base alla configurazione della caccia al tesoro, il THS fornirà o meno queste informazioni.
La richiesta specifica due parametri:
Il nome dell'operazione è getStatus, pertanto la richiesta sarà un POST HTTP a:
http://[nome server]/getstatus
Il body della richiesta HTTP contiene i parametri ed è un frammento XML validato dal seguente XML-Schema:
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:thunt="http://vitali.web.cs.unbo.it/thunt"
targetNamespace="http://vitali.web.cs.unbo.it/thunt" elementFormDefault="qualified">
<xs:element name="getStatus">
<xs:complexType>
<xs:attribute name="id" type="xs:string" use="required"/>
<xs:attribute name="thunt" type="xs:string" use="required"/>
<xs:attribute name="pwd" type="xs:string" use="required"/>
<!-- Id dell'utente o del gruppo che vuole richiedere lo status degli altri client -->
<!-- Password dell'utente o del gruppo che vuole richiedere lo status degli altri client -->
<!-- Id della caccia al tesoro relativa -->
</xs:complexType>
</xs:element>
</xs:schema>
Tramite questa richiesta il THC manda al THS un falso indizio da spedire agli altri concorrenti della caccia. In base alla configurazione della caccia al tesoro, il THS fornirà o meno queste informazioni.
La richiesta specifica quattro parametri:
Il nome dell'operazione è sendFalseHint, pertanto la richiesta sarà un POST HTTP a:
http://[nome server]/sendfalsehint
Il body della richiesta HTTP contiene i parametri ed è un frammento XML validato dal seguente XML-Schema.
Importante: lo schema non è completo, ma fa riferimento ai tipi globali descritti nella sezione 5.
<?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns="http://vitali.web.cs.unbo.it/thunt" xmlns:thunt="http://vitali.web.cs.unbo.it/thunt"
targetNamespace="http://vitali.web.cs.unbo.it/thunt" elementFormDefault="qualified">
<xs:element name="sendFalseHint">
<xs:complexType>
<xs:sequence>
<xs:element name="para" maxOccurs="unbounded" type="TBlockInline"/>
</xs:sequence>
<!-- Id dell'utente o del gruppo che vuole mandare un falso indizio -->
<!-- Password dell'utente o del gruppo che vuole mandare un falso indizio -->
<!-- Id della caccia al tesoro -->
<!-- Id del turno -->
<xs:attribute name="id" type="xs:string" use="required"/>
<xs:attribute name="pwd" type="xs:string" use="required"/>
<xs:attribute name="thunt" type="xs:string" use="required"/>
<xs:attribute name="turn" type="xs:string" use="required"/>
</xs:complexType>
</xs:element>
...
</xs:schema>
Tramite questa richiesta il THC carica una nuova caccia al tesoro sul THS.
La richiesta specifica due parametri:
Il nome dell'operazione è loadTreasureHunt, pertanto la richiesta sarà un POST HTTP a:
http://[nome server]/loadtreasurehunt
Il body della richiesta HTTP contiene i parametri ed è un frammento XML validato dal file XML-Schema disponibile al seguente URL: http://vitali.web.cs.unibo.it/twiki/pub/TechWeb09/TreasureHuntProtocol12/thunt-final-1.2.xsd.
Tramite questa richiesta il THC chiede al THS di eliminare una caccia al tesoro tra quelle disponibili agli utenti.
La richiesta specifica due parametri:
Il nome dell'operazione è removeTreasureHunt, pertanto la richiesta sarà un POST HTTP a:
http://[nome server]/removetreasurehunt
Il body della richiesta HTTP contiene i parametri ed è un frammento XML validato dal seguente XML-Schema:
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:thunt="http://vitali.web.cs.unbo.it/thunt"
targetNamespace="http://vitali.web.cs.unbo.it/thunt" elementFormDefault="qualified">
<xs:element name="removeTreasureHunt">
<xs:complexType>
<xs:attribute name="id" type="xs:string" use="required"/>
<xs:attribute name="pwd" type="xs:string" use="required"/>
<xs:attribute name="hunt" type="xs:string" use="required"/>
<!-- Id dell'organizzatore -->
<!-- Password dell'organizzatore -->
<!-- Id della caccia -->
</xs:complexType>
</xs:element>
</xs:schema>
Tramite questa richiesta il THC chiede al THS di far partire una caccia al tesoro.
La richiesta specifica due parametri:
Il nome dell'operazione è startTreasureHunt, pertanto la richiesta sarà un POST HTTP a:
http://[nome server]/starttreasurehunt
Il body della richiesta HTTP contiene i parametri ed è un frammento XML validato dal seguente XML-Schema:
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:thunt="http://vitali.web.cs.unbo.it/thunt"
targetNamespace="http://vitali.web.cs.unbo.it/thunt" elementFormDefault="qualified">
<xs:element name="startTreasureHunt">
<xs:complexType>
<xs:attribute name="id" type="xs:string" use="required"/>
<xs:attribute name="pwd" type="xs:string" use="required"/>
<xs:attribute name="hunt" type="xs:string" use="required"/>
<!-- Id dell'organizzatore -->
<!-- Password dell'organizzatore -->
<!-- Id della caccia al tesoro -->
</xs:complexType>
</xs:element>
</xs:schema>
L'applicazione THS risponde alle seguenti richieste provenienti dall'applicazione THC:
Il THS ritorna una lista di identificatori di cacce. La risposta è relativa alla richiesta specificata in sezione 2.1.
La risposta del THS è un frammento XML (contenuto nel body della risposta HTTP) validato dal seguente XML-Schema:
<?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:thunt="http://vitali.web.cs.unbo.it/thunt"
targetNamespace="http://vitali.web.cs.unbo.it/thunt" elementFormDefault="qualified">
<!-- Il contenitore di tutte le cacce disponibili -->
<xs:element name="getTreasureHunts">
<xs:complexType>
<xs:sequence>
<xs:element ref="thunt:treasureHunt" minOccurs="0" maxOccurs="unbounded"/>
</xs:sequence>
</xs:complexType>
</xs:element>
<!-- L'elemento utilizzato per specificare una particolare caccia disponibile, identificata da un id -->
<xs:element name="treasureHunt">
<xs:complexType>
<xs:sequence>
<xs:element name="description" type="Tblocks"/>
</xs:sequence>
<xs:attribute name="id" type="xs:string" use="required"/>
<xs:attribute name="title" type="xs:string" use="required"/>
</xs:complexType>
</xs:element>
</xs:schema>
Il THS iscrive un utente alla caccia al tesoro. Ritorna un messaggio che indica se l'operazione ha avuto successo o c'è stato un errore. La risposta è relativa alla richiesta specificata in sezione 2.2.
I possibili output di questa operazione sono:
La risposta del THS è pertanto un frammento XML (contenuto nel body della risposta HTTP) validato dal seguente XML-Schema:
<?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:thunt="http://vitali.web.cs.unbo.it/thunt"
targetNamespace="http://vitali.web.cs.unbo.it/thunt" elementFormDefault="qualified">
<!--
L'elemento contenente la risposta da parte del server per l'operazione di sottoscrizione.
Può contenere facoltativamente del testo di descrizione del risultato dell'operazione.
-->
<xs:element name="sendSubscriptionResult">
<xs:complexType mixed="true">
<xs:attribute name="status" use="required">
<xs:simpleType>
<xs:restriction base="xs:token">
<xs:enumeration value="accepted"/>
<xs:enumeration value="passAlreadyAssigned"/>
<xs:enumeration value="notExist"/>
<xs:enumeration value="noPermission"/>
<xs:enumeration value="alreadySubscribed"/>
</xs:restriction>
</xs:simpleType>
</xs:attribute>
<!--
Definisce se la sottoscrizione è andata a buon fine ('accepted') o se si è presentato un problema nella sottoscrizione:
- 'notExist' -> la caccia al tesoro specificata non esiste
- 'passAlreadyAssigned' -> la password specificata è già stata assegnata
- 'noPermission' -> non si hanno i permessi necessari per partecipare alla caccia al tesoro specificata
- 'alreadySubscripted' -> si è già iscritti a questa caccia al tesoro
-->
</xs:complexType>
</xs:element>
</xs:schema>
Il THS ritorno il prossimo indizio all'utente, se ciò è possibile, oppure un messaggio di errore. La risposta è relativa alla richiesta specificata in sezione 2.3.
I possibili output di questa operazione sono:
La risposta del THS è pertanto un frammento XML (contenuto nel body della risposta HTTP) validato dal seguente XML-Schema.
Importante: lo schema non è completo, ma fa riferimento ai tipi globali descritti nella sezione 5.
<?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:thunt="http://vitali.web.cs.unbo.it/thunt"
targetNamespace="http://vitali.web.cs.unbo.it/thunt" elementFormDefault="qualified">
<!--
L'elemento contenente la risposta da parte del server per l'operazione di richiesta di indizio.
Contiene l'indizio.
-->
<xs:element name="getHintResult">
<xs:complexType>
<xs:sequence>
<xs:element name="para" type="TBlockInline" minOccurs="0" maxOccurs="unbounded"/>
</xs:sequence>
<xs:attribute name="hint" type="xs:string"/>
<xs:attribute name="status" use="required">
<xs:simpleType>
<xs:restriction base="xs:token">
<xs:enumeration value="accepted"/>
<xs:enumeration value="wrongPass"/>
<xs:enumeration value="notExist"/>
<xs:enumeration value="notSubscribed"/>
</xs:restriction>
</xs:simpleType>
</xs:attribute>
<!-- L'id dell'indizio (hint) è presente solo se non si sono verificati problemi nell'operazione -->
<!--
Definisce se la richiesta è andata a buon fine ('accepted') o se si è presentato un problema nella richiesta dell'indizio:
- 'notExist' -> la caccia al tesoro specificata non esiste
- 'wrongPass' -> la password specificata non è associata all'utente
- 'notSubscribed' -> l'utente non è iscritto alla caccia al tesoro
-->
</xs:complexType>
</xs:element>
</xs:schema>
Il THS valuta la risposta e ritorna un messaggio all'utente. La risposta è relativa alla richiesta specificata in sezione 2.4.
I possibili output di questa operazione sono:
La risposta del THS è pertanto un frammento XML (contenuto nel body della risposta HTTP) validato dal seguente XML-Schema.
Importante: lo schema non è completo, ma fa riferimento ai tipi globali descritti nella sezione 5.
<?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:thunt="http://vitali.web.cs.unbo.it/thunt"
targetNamespace="http://vitali.web.cs.unbo.it/thunt" elementFormDefault="qualified">
<!--
L'elemento indicante la validità o meno della risposta data da un client per un turno.
Può contenere facoltativamente del testo di descrizione del risultato dell'operazione.
-->
<xs:element name="submitAnswerResult">
<xs:complexType>
<xs:sequence>
<xs:element name="para" type="TBlockInline" minOccurs="0" maxOccurs="unbounded"/>
</xs:sequence>
<xs:attribute name="status" use="required">
<xs:simpleType>
<xs:restriction base="xs:token">
<xs:enumeration value="right"/>
<xs:enumeration value="wrong"/>
<xs:enumeration value="win"/>
<xs:enumeration value="wrongPass"/>
<xs:enumeration value="notExist"/>
<xs:enumeration value="notSubscribed"/>
</xs:restriction>
</xs:simpleType>
</xs:attribute>
<!--
Definisce se la risposta è esatta ('right'), sbagliata ('wrong'), se il client ha vinto la caccia al tesoro ('win')
o se si è presentato un problema:
- 'wrongPass' -> la password specificata non è associata all'utente
- 'notExist' -> la caccia al tesoro specificata non esiste
- 'notSubscribed' -> non si è iscritti alla caccia specificata
-->
</xs:complexType>
</xs:element>
</xs:schema>
Il THS ritorna lo status degli altri team, se è possibile, o un messaggio di errore. La risposta è relativa alla richiesta specificata in sezione 2.5.
I possibili output di questa operazione sono:
La risposta del THS è pertanto un frammento XML (contenuto nel body della risposta HTTP) validato dal seguente XML-Schema:
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:thunt="http://vitali.web.cs.unbo.it/thunt"
targetNamespace="http://vitali.web.cs.unbo.it/thunt" elementFormDefault="qualified">
<!-- L'elemento utilizzato per indicare gli status attuali degli altri client per una determinata caccia al tesoro. -->
<xs:element name="getStatusResult">
<xs:complexType>
<xs:sequence>
<xs:element ref="thunt:status" minOccurs="0" maxOccurs="unbounded"/>
</xs:sequence>
<xs:attribute name="status" use="required">
<xs:simpleType>
<xs:restriction base="xs:token">
<xs:enumeration value="accepted"/>
<xs:enumeration value="wrongPass"/>
<xs:enumeration value="notExist"/>
<xs:enumeration value="notSubscribed"/>
<xs:enumeration value="noTransparency"/>
</xs:restriction>
</xs:simpleType>
</xs:attribute>
<!--
Definisce se la richiesta è andata a buon fine ('accepted') o se si è presentato un problema:
- 'wrongPass' -> la password specificata non è associata all'utente
- 'notExist' -> la caccia al tesoro specificata non esiste
- 'notSubscribed' -> non si è iscritti alla caccia specificata
- 'noTransparency' -> la caccia al tesoro non è trasparente
-->
</xs:complexType>
</xs:element>
<xs:element name="status">
<xs:complexType>
<xs:attribute name="id" type="xs:string" use="required"/>
<xs:attribute name="turnNumber" type="xs:integer" use="required"/>
<xs:attribute name="turnId" type="xs:string" use="required"/>
<xs:attribute name="turnName" type="xs:string" use="required"/>
<xs:attribute name="hintNumber" type="xs:integer" use="required"/>
</xs:complexType>
</xs:element>
</xs:schema>
Il THS carica il falso indizio ricevuto dal client, se è possibile, e ritorna un messaggio di conferma o errore. La risposta è relativa alla richiesta specificata in sezione 2.6.
I possibili output di questa operazione sono:
Il messaggio può contenere inoltre testo che lo descrive in linguaggio naturale.
La risposta del THS è pertanto un frammento XML (contenuto nel body della risposta HTTP) validato dal seguente XML-Schema:
<?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:thunt="http://vitali.web.cs.unbo.it/thunt"
targetNamespace="http://vitali.web.cs.unbo.it/thunt" elementFormDefault="qualified">
<!--
L'elemento indicante la validità o meno della risposta data da un client per un turno.
Può contenere facoltativamente del testo di descrizione del risultato dell'operazione.
-->
<xs:element name="sendFalseHintResult">
<xs:complexType mixed="true">
<xs:attribute name="status" use="required">
<xs:simpleType>
<xs:restriction base="xs:token">
<xs:enumeration value="accepted"/>
<xs:enumeration value="outOfBound"/>
<xs:enumeration value="noTransparency"/>
<xs:enumeration value="wrongPass"/>
<xs:enumeration value="noTurn"/>
<xs:enumeration value="notExist"/>
<xs:enumeration value="notSubscribed"/>
</xs:restriction>
</xs:simpleType>
</xs:attribute>
<!--
Definisce se il falso indizio è stato accettato ('accepted') o se si è presentato un problema:
- 'outOfBound' -> l'utente ha già mandato il numero massimo di falsi indizi per questa caccia al tesoro
- 'noTransparency' -> la caccia non è trasparente e, conseguentemente, non ammette falsi indizi
- 'wrongPass' -> la password specificata non è associata all'utente
- 'noTurn' -> il turno specificato non esiste
- 'notExist' -> la caccia al tesoro specificata non esiste
- 'notSubscribed' -> non si è iscritti alla caccia specificata
-->
</xs:complexType>
</xs:element>
</xs:schema>
Il THS carica la caccia al tesoro ricevuta dal client, se è possibile, e ritorna un messaggio di conferma o errore. La risposta è relativa alla richiesta specificata in sezione 2.7.
I possibili output di questa operazione sono:
Il messaggio può contenere inoltre testo che lo descrive in linguaggio naturale.
La risposta del THS è pertanto un frammento XML (contenuto nel body della risposta HTTP) validato dal seguente XML-Schema:
<?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:thunt="http://vitali.web.cs.unbo.it/thunt"
targetNamespace="http://vitali.web.cs.unbo.it/thunt" elementFormDefault="qualified">
<!-- Può contenere facoltativamente del testo di descrizione del risultato dell'operazione. -->
<xs:element name="loadTreasureHuntResult">
<xs:complexType mixed="true">
<xs:attribute name="hunt" type="xs:string"/>
<xs:attribute name="status" use="required">
<xs:simpleType>
<xs:restriction base="xs:token">
<xs:enumeration value="accepted"/>
<xs:enumeration value="passAlreadyAssigned"/>
<xs:enumeration value="notWellFormed"/>
<xs:enumeration value="notValid"/>
</xs:restriction>
</xs:simpleType>
</xs:attribute>
<!-- L'id della caccia, presente solo se non si sono verificati problemi nell'operazione -->
<!--
Definisce se il caricamento si è concluso con successo ('accepted') o se si è presentato un problema:
- 'wrongPass' -> la password specificata è già stata assegnata
- 'notWellFormed' -> il documento di configurazione non è ben formato
- 'notValid' -> il documento di configurazione non è valido
-->
</xs:complexType>
</xs:element>
</xs:schema>
Il THS cancella la caccia specificata dal client, se è possibile, e ritorna un messaggio di conferma o errore. La risposta è relativa alla richiesta specificata in sezione 2.8.
I possibili output di questa operazione sono:
La risposta del THS è pertanto un frammento XML (contenuto nel body della risposta HTTP) validato dal seguente XML-Schema:
<?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:thunt="http://vitali.web.cs.unbo.it/thunt"
targetNamespace="http://vitali.web.cs.unbo.it/thunt" elementFormDefault="qualified">
<xs:element name="removeTreasureHuntResult">
<xs:complexType>
<xs:attribute name="status" use="required">
<xs:simpleType>
<xs:restriction base="xs:token">
<xs:enumeration value="accepted"/>
<xs:enumeration value="wrongPass"/>
<xs:enumeration value="notExist"/>
<xs:enumeration value="noPermission"/>
</xs:restriction>
</xs:simpleType>
</xs:attribute>
<!--
Definisce se la rimozione si è conclusa con successo ('accepted') o se si è presentato un problema:
- 'wrongPass' -> la password specificata non è associata all'utente
- 'notExist' -> la caccia al tesoro specificata non esiste
- 'noPermission' -> l'utente non ha i permessi per rimuovere la caccia al tesoro
-->
</xs:complexType>
</xs:element>
</xs:schema>
Il THS fa partire la caccia al tesoro specificata dal client, se è possibile, e ritorna un messaggio di conferma o errore. La risposta è relativa alla richiesta specificata in sezione 2.9.
I possibili output di questa operazione sono:
La risposta del THS è pertanto un frammento XML (contenuto nel body della risposta HTTP) validato dal seguente XML-Schema:
<?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:thunt="http://vitali.web.cs.unbo.it/thunt"
targetNamespace="http://vitali.web.cs.unbo.it/thunt" elementFormDefault="qualified">
<!-- Può contenere facoltativamente del testo di descrizione del risultato dell'operazione. -->
<xs:element name="startResult">
<xs:complexType>
<xs:attribute name="time" type="xs:time"/>
<xs:attribute name="status" use="required">
<xs:simpleType>
<xs:restriction base="xs:token">
<xs:enumeration value="accepted"/>
<xs:enumeration value="wrongPass"/>
<xs:enumeration value="notExist"/>
<xs:enumeration value="noPermission"/>
<xs:enumeration value="alreadyStarted"/>
</xs:restriction>
</xs:simpleType>
</xs:attribute>
<!-- Il tempo in cui è partita la caccia al tesoro, presente solo se non si sono verificati problemi nell'operazione -->
<!--
Definisce se il caricamento si è concluso con successo ('accepted') o se si è presentato un problema:
- 'wrongPass' -> la password specificata non è associata all'utente
- 'notExist' -> la caccia al tesoro specificata non esiste
- 'noPermission' -> l'utente non ha i permessi per rimuovere la caccia al tesoro
- 'alreadyStarted' -> la caccia al tesoro è già in corso
-->
</xs:complexType>
</xs:element>
</xs:schema>
Questa sezione contiene le dichiarazioni XML-Schema di alcuni tipi globali, usati in vari frammenti XML di questo protocollo.
I riferimenti a questi tipi sono contenuti ad esempio negli schemi relativi agli indizi o ai messaggi ritornati dal THS al THC.
<xs:complexType name="Tblocks">
<xs:sequence>
<xs:element name="para" type="TBlockInline" maxOccurs="unbounded"/>
</xs:sequence>
</xs:complexType>
<xs:complexType name="TBlockInline" mixed="true">
<xs:choice>
<xs:element name="bold" type="TBlockInline"/>
<xs:element name="italic" type="TBlockInline"/>
<xs:element name="link" type="Tlink"/>
<xs:element name="image" type="Timage"/>
<xs:element name="location" type="Tlocation"/>
<xs:element name="picture" type="Tpicture"/>
<xs:element name="video" type="Tvideo"/>
<xs:element name="article" type="Tarticle"/>
</xs:choice>
</xs:complexType>
<xs:complexType name="Tlink">
<xs:complexContent>
<xs:extension base="TBlockInline">
<xs:attribute name="href" type="xs:anyURI" use="required"/>
</xs:extension>
</xs:complexContent>
</xs:complexType>
<xs:complexType name="Timage">
<xs:attribute name="type" type="TimageType" use="required"/>
<xs:attribute name="src" type="xs:anyURI" use="required"/>
</xs:complexType>
<xs:simpleType name="TimageType">
<xs:restriction base="xs:string">
<xs:enumeration value="inline"/>
<xs:enumeration value="block"/>
</xs:restriction>
</xs:simpleType>
<xs:complexType name="Tlocation">
<xs:attribute name="lat" type="xs:double" use="required"/>
<xs:attribute name="long" type="xs:double" use="required"/>
<xs:attribute name="planet" type="xs:string" fixed="Earth"/>
<xs:attribute name="radius" type="xs:positiveInteger" use="optional"/>
</xs:complexType>
<xs:complexType name="Tpicture">
<xs:attribute name="type" type="xs:string" default="flickr"/>
<xs:attribute name="usr" type="xs:string" use="required"/>
<xs:attribute name="id" type="xs:ID" use="required"/>
</xs:complexType>
<xs:complexType name="Tvideo">
<xs:attribute name="type" type="TvideoType" use="required"/>
<xs:attribute name="id" type="xs:ID" use="required"/>
</xs:complexType>
<xs:simpleType name="TvideoType">
<xs:restriction base="xs:string">
<xs:enumeration value="youtube"/>
<xs:enumeration value="googlevideo"/>
</xs:restriction>
</xs:simpleType>
<xs:complexType name="Tarticle">
<xs:attribute name="type" type="xs:string" default="wikipedia"/>
<xs:attribute name="id" type="xs:ID" use="required"/>
<xs:attribute name="lang" type="xs:language" use="required"/>
</xs:complexType>
In questa versione l'elemento looserMessage è stato sostituito con l'elemento loserMessage (nome corretto in inglese) e il tipo di TfakeHints è stato aggiornato in xs:nonNegativeInteger, per permettere di indicare un numero di falsi indizi pari a zero.
E' stato inoltre modificato il tipo di treasureHunt (usato dal THS per ritornare l'elenco di cacce al tesoro al THC) per includere anche titolo e descrizione, oltre all'id di una caccia al tesoro.