TreasureHuntProtocol10 < TechWeb09

TechWeb09
TechWeb09.TreasureHuntProtocol10r1.46 - 27 Apr 2009 - 15:54 - SilvioPeronitopic end
<h1 align="center">Treasure Hunt Protocol</h1>
<p align="center"><b>Specifiche di protocollo</b></p>
<p align="center"><i>Versione 1.0 Aprile 2009</i></p>

<p><b>Questa versione</b>: TreasureHuntProtocol10 </p>
<p><b>Ultima versione</b>: TreasureHuntProtocol11 </p>
<p><b>Versione Precedente</b>: Non ci sono versioni precedenti </p>
<p><b>Autori</b>: Main.FabioVitali, Main.AngeloDiIorio, Main.SilvioPeroni</p>

%TOC%

<h2>Abstract</h2>

<p>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.</p>
<p>L'architettura generale prevede l'interazione di due componenti fondamentali:</p>
<ul>
   <li>THS (Treasure Hunt Server): un'applicazione server-side che gestisce la caccia al tesoro. L'applicazione ha il compito di erogare indizi, gestire il tempo, verificare le risposte e i messaggi per i giocatori.</li>
   <li>THC (Treasure Hunt Client): un'applicazione integrata in Facebook, che permette ad ogni team di giocare la caccia al tesoro. Il client chiede indizi al server THS, sottomette le risposte relative ad ogni turno e visualizza messaggi. In realtà , il client è implementato come un'applicazione server-side invocata direttamente da Facebook.</li>
</ul>
<p>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. 
</p>
<h2>Stato di questo documento</h2>
<p>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à . <b>Importante: le modifiche al protocollo non sono obbligatorie. E' tuttavia possibile apportare modifiche CON IL CONSENSO DI TUTTI I GRUPPI PARTECIPANTI AL PROGETTO.</b></p>

<h2>1. Protocollo THP</h2>

<p>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.</p>

<p>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.</p>

<p>Il capitolo 2 descrive le query al THS mentre il capitolo 
  3 contiene dettagli sui vari tipi di flussi XML generati dal THS.</p>
  <p>   
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.</p>

<h2>2. Dettagli delle richieste THC -&gt; THS</h2>

<p>L'applicazione THC può inoltrare le seguenti richieste all'applicazione THS:</p>

<ul type=disc>
  <li><b>Elenco delle cacce al tesoro disponibili</b></li>
  <li><b>Iscrizione ad una caccia al tesoro</b></li>
  <li><b>Richiesta di indizio</b></li>
  <li><b>Sottomissione di una risposta</b></li>
  <li><b>Richiesta dello status dei team</b></li>
  <li><b>Sottomissione di un falso indizio</b></li>
  <li><b>Caricamento di una caccia al tesoro</b></li>
  <li><b>Cancellazione di una caccia al tesoro</b></li>
  <li><b>Partenza di una caccia al tesoro</b></li>
</ul>

<p>Le richieste sono effettuate via HTTP, con un approccio REST. In particolare tutti gli URL hanno la stessa struttura:</p>
<pre>http://[URL DEL SERVER]/[NOME DELL'OPERAZIONE TUTTO IN MINUSCOLO]</pre>
<p>Pertanto, un esempio di richiesta è <tt>http://www.cs.unibo.it/server-di-tw/getstatus</tt></p>
<p>La risposta è in formato XML e contenuto nel body della risposta HTTP.</p>
<p>Le seguenti sottosezioni spiegano in dettaglio le caratteristiche ed il formato di ogni operazione prevista dal protocollo.</p>


<h3>2.1 Elenco delle cacce al tesoro disponibili</h3>
  <p>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.</p>
  <p>Il nome dell'operazione è <tt>getTreasureHunts</tt>, pertanto la richiesta sarà un GET HTTP a: </p>
  <pre>http://[nome server]/gettreasurehunts</pre>
  
<h3>2.2 Iscrizione ad una caccia al tesoro</h3>
  <p>Tramite questa richiesta il THC iscrive un utente o un gruppo alla caccia al tesoro.</p>
  <p>La richiesta specifica due parametri:</p>
  <ul>
      <li>Identificativo dell'utente o del gruppo da iscrivere alla caccia al tesoro</li>
      <li>Identificativo della caccia a cui iscriversi</li>
  </ul>
  <p>Il nome dell'operazione è <tt>sendSubscription</tt>, pertanto la richiesta sarà un POST HTTP a: </p>
  <pre>http://[nome server]/sendsubscription</pre>
  <p>Il body della richiesta HTTP contiene i parametri ed è un frammento XML validato dal seguente XML-Schema:</p>
  <verbatim>
<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.thunt"/>
    </xs:complexType>
  </xs:element>
  <xs:element name="group">
    <xs:complexType>
      <xs:attributeGroup ref="thunt:attribute.id"/>
      <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 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>
  </verbatim>




<h3>2.3 Richiesta di indizio</h3>
  <p>Tramite questa richiesta il THC chiede l'indizio successivo.</p>
  <p>La richiesta specifica due parametri:</p>
  <ul>
      <li>Identificativo dell'utente</li>
      <li>Identificativo della caccia</li>
  </ul>
  <p>Il nome dell'operazione è <tt>getHint</tt>, pertanto la richiesta sarà un POST HTTP a: </p>
  <pre>http://[nome server]/gethint</pre>
  <p>Il body della richiesta HTTP contiene i parametri ed è un frammento XML validato dal seguente XML-Schema:</p>
  <verbatim>
  <?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="thunt" type="xs:string" use="required"/>
      </xs:complexType>
   </xs:element>
</xs:schema>
  </verbatim>









<h3>2.4 Sottomissione di una risposta</h3>
  <p>Tramite questa richiesta il THC spedisce al server la risposta relativa al turno corrente.</p>
  <p>La richiesta specifica tre parametri:</p>
  <ul>
      <li>Identificativo dell'utente</li>
      <li>Identificativo della caccia</li>
      <li>Risposta</li>
  </ul>
  <p>Il nome dell'operazione è <tt>submitAnswer</tt>, pertanto la richiesta sarà un POST HTTP a: </p>
  <pre>http://[nome server]/submitanswer</pre>
  <p>Il body della richiesta HTTP contiene i parametri ed è un frammento XML validato dal seguente XML-Schema.</p>
  <p><b>Importante:</b> lo schema non è completo, ma fa riferimento ai tipi globali descritti nella sezione 5.</p>
  <verbatim>
  <?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="thunt" type="xs:string" use="required"/>
         <!-- Id 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>

  </verbatim>
  

<h3>2.5 Richiesta dello status dei team</h3>
  
  <p>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.</p>
  <p>La richiesta specifica due parametri:</p>
  <ul>
      <li>Identificativo dell'utente</li>
      <li>Identificativo della caccia</li>
  </ul>
  <p>Il nome dell'operazione è <tt>getStatus</tt>, pertanto la richiesta sarà un POST HTTP a: </p>
  <pre>http://[nome server]/getstatus</pre>
  <p>Il body della richiesta HTTP contiene i parametri ed è un frammento XML validato dal seguente XML-Schema:</p>
  <verbatim>
  <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"/>
         <!-- Id 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>
  </verbatim>




<h3>2.6 Sottomissione di un falso indizio</h3>
  <p>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.</p>
  <p>La richiesta specifica quattro parametri:</p>
  <ul>
      <li>Identificativo dell'utente</li>
      <li>Identificativo della caccia</li>
      <li>Identificativo del turno</li>
      <li>il falso indizio</li>
  </ul>
  <p>Il nome dell'operazione è <tt>sendFalseHint</tt>, pertanto la richiesta sarà un POST HTTP a: </p>
  <pre>http://[nome server]/sendfalsehint</pre>
  <p>Il body della richiesta HTTP contiene i parametri ed è un frammento XML validato dal seguente XML-Schema.</p>
  <p><b>Importante:</b> lo schema non è completo, ma fa riferimento ai tipi globali descritti nella sezione 5.</p>
  <verbatim>
<?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 -->
         <!-- Id della caccia al tesoro -->
         <!-- Id del turno -->
         <xs:attribute name="id" 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>

  </verbatim>

<h3>2.7 Caricamento di una caccia al tesoro</h3>
   <p>Tramite questa richiesta il THC carica una nuova caccia al tesoro sul THS.</p>
  <p>La richiesta specifica due parametri:</p>
  <ul>
      <li>Identificativo dell'organizzatore</li>
      <li>La configurazione vera e propria della caccia al tesoro</li>
  </ul>
  <p>Il nome dell'operazione è <tt>loadTreasureHunt</tt>, pertanto la richiesta sarà un POST HTTP a: </p>
  <pre>http://[nome server]/loadtreasurehunt</pre>
  <p>Il body della richiesta HTTP contiene i parametri ed è un frammento XML validato dal file XML-Schema disponibile al seguente URL: [[%ATTACHURL%/thunt-final.xsd][%ATTACHURL%/thunt-final.xsd]].</p>
  
  
<h3>2.8 Cancellazione di una caccia al tesoro</h3>
  <p>Tramite questa richiesta il THC chiede al THS di eliminare una caccia al tesoro tra quelle disponibili agli utenti.</p>
  <p>La richiesta specifica due parametri:</p>
  <ul>
      <li>Identificativo dell'utente</li>
      <li>Identificativo della caccia</li>
  </ul>
  <p>Il nome dell'operazione è <tt>removeTreasureHunt</tt>, pertanto la richiesta sarà un POST HTTP a: </p>
  <pre>http://[nome server]/removetreasurehunt</pre>
  <p>Il body della richiesta HTTP contiene i parametri ed è un frammento XML validato dal seguente XML-Schema:</p>
  <verbatim>
<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="hunt" type="xs:string" use="required"/>
         <!-- Id dell'organizzatore -->
         <!-- Id della caccia -->
      </xs:complexType>
   </xs:element>
</xs:schema>  
  </verbatim>


<h3>2.9 Partenza di una caccia al tesoro</h3>
   <p>Tramite questa richiesta il THC chiede al THS di far partire una caccia al tesoro.</p>
  <p>La richiesta specifica due parametri:</p>
  <ul>
      <li>Identificativo dell'utente</li>
      <li>Identificativo della caccia</li>
  </ul>
  <p>Il nome dell'operazione è <tt>startTreasureHunt</tt>, pertanto la richiesta sarà un POST HTTP a: </p>
  <pre>http://[nome server]/starttreasurehunt</pre>
  <p>Il body della richiesta HTTP contiene i parametri ed è un frammento XML validato dal seguente XML-Schema:</p>
  <verbatim>
<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="hunt" type="xs:string" use="required"/>
         <!-- Id dell'organizzatore -->
         <!-- Id della caccia al tesoro -->
      </xs:complexType>
   </xs:element>
</xs:schema>
  </verbatim>


<h2>3. Dettagli delle risposte THS -&gt; THC</h2>

<p>L'applicazione THS risponde alle seguenti richieste provenienti dall'applicazione THC:</p>

<ul type=disc>
  <li><b>Elenco delle cacce al tesoro disponibili</b></li>
  <li><b>Iscrizione ad una caccia al tesoro</b></li>
  <li><b>Richiesta di indizio</b></li>
  <li><b>Sottomissione di una risposta</b></li>
  <li><b>Richiesta dello status dei team</b></li>
  <li><b>Sottomissione di un falso indizio</b></li>
  <li><b>Caricamento di una caccia al tesoro</b></li>
  <li><b>Cancellazione di una caccia al tesoro</b></li>
  <li><b>Partenza di una caccia al tesoro</b></li>
</ul>
  <h3>3.1 Elenco delle cacce al tesoro disponibili</h3>
     <p>Il THS ritorna una lista di identificatori di cacce. La risposta è relativa alla richiesta specificata in sezione 2.1.</p>
     <p>La risposta del THS è un frammento XML (contenuto nel body della risposta HTTP) validato dal seguente XML-Schema:</p>
<verbatim>
<?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:attribute name="id" type="xs:string" use="required"/>
      </xs:complexType>
   </xs:element>
</xs:schema>
</verbatim>

  <h3>3.2 Iscrizione ad una caccia al tesoro</h3>
       <p>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.</p>
       <p>I possibili output di questa operazione sono:</p>
       <ul>
        <li><i>Accepted</i>: iscrizione avvenuta con successo</li>
        <li><i>notExist</i>: la caccia al tesoro specificata non esiste</li>
        <li><i>noUser</i>: l'utente specificato non esiste</li>
        <li><i>noPermission</i>: non si hanno i permessi necessari per partecipare alla caccia al tesoro specificata</li>
        <li><i>alreadySubscripted</i>: si è già iscritti a questa caccia al tesoro</li>
      </ul>
     <p>La risposta del THS è pertanto un frammento XML (contenuto nel body della risposta HTTP) validato dal seguente XML-Schema:</p>
   <verbatim>
   <?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="noUser"/>
                  <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
        - 'noUser' -> l'utente specificato non esiste
        - '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>
   </verbatim>
  
  
  
  
  <h3>3.3 Richiesta di indizio</h3>
       <p>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.</p>
       <p>I possibili output di questa operazione sono:</p>
        <ul>
        <li><i>Accepted</i>: indizio disponibile (ed è contenuto nella risposta)</li>
        <li><i>notExist</i>: la caccia al tesoro specificata non esiste</li>
        <li><i>noUser</i>: l'utente specificato non esiste</li>
        <li><i>notsubscribed</i>: l'utente non è iscritto alla caccia al tesoro</li>
        </ul>
     <p>La risposta del THS è pertanto un frammento XML (contenuto nel body della risposta HTTP) validato dal seguente XML-Schema.</p>
     <p><b>Importante:</b> lo schema non è completo, ma fa riferimento ai tipi globali descritti nella sezione 5.</p>
   <verbatim>
   <?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="noUser"/>
                  <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
        - 'noUser' -> l'utente specificato non esiste
        - 'notSubscribed' -> l'utente non è iscritto alla caccia al tesoro
      -->
      </xs:complexType>
   </xs:element>
</xs:schema>
   </verbatim>
  
  
  <h3>3.4 Sottomissione di una risposta</h3>
 <p>Il THS valuta la risposta e ritorna un messaggio all'utente. La risposta è relativa alla richiesta specificata in sezione 2.4.</p>
       <p>I possibili output di questa operazione sono:</p>
        <ul>
        <li><i>Right</i>: risposta corretta</li>
        <li><i>Wrong</i>: risposta sbagliata</li>
        <li><i>Win</i>: risposta corretta e caccia al tesoro vinta</li>
        <li><i>notExist</i>: la caccia al tesoro specificata non esiste</li>
        <li><i>noUser</i>: l'utente specificato non esiste</li>
        <li><i>notsubscribed</i>: l'utente non è iscritto alla caccia al tesoro</li>
        </ul>
     <p>La risposta del THS è pertanto un frammento XML (contenuto nel body della risposta HTTP) validato dal seguente XML-Schema.</p>
     <p><b>Importante:</b> lo schema non è completo, ma fa riferimento ai tipi globali descritti nella sezione 5.</p>
   <verbatim>
   <?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="noUser"/>
                  <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:
        - 'noUser' -> l'utente specificato non esiste
        - 'notExist' -> la caccia al tesoro specificata non esiste
        - 'notSubscribed' -> non si è iscritti alla caccia specificata
      -->
      </xs:complexType>
   </xs:element>
</xs:schema>

   </verbatim>
  
  
  
  
  
  <h3>3.5 Richiesta dello status dei team</h3>
  <p>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.</p>
       <p>I possibili output di questa operazione sono:</p>
       <ul>
        <li><i>Accepted</i>: possibile vedere lo status degli altri team. Il body della risposta contiente questo status e specifica, per ogni team, numero, nome e id del turno corrente e numero dell'indizio corrente</li>
        <li><i>notExist</i>: la caccia al tesoro specificata non esiste</li>
        <li><i>noUser</i>: l'utente specificato non esiste</li>
        <li><i>noPermission</i>: non si hanno i permessi necessari per partecipare alla caccia al tesoro specificata</li>
        <li><i>noTransparency</i>: la caccia al tesoro non è trasparente</li>
      </ul>
     <p>La risposta del THS è pertanto un frammento XML (contenuto nel body della risposta HTTP) validato dal seguente XML-Schema:</p>
   <verbatim>
<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="noUser"/>
                  <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:
        - 'noUser' -> l'utente specificato non esiste
        - '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>
   </verbatim>
  
  
  
  
  
  
  
  
  <h3>3.6 Sottomissione di un falso indizio</h3>
  <p>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.</p>
       <p>I possibili output di questa operazione sono:</p>
       <ul>
        <li><i>Accepted</i>: falso indizio accettato</li>
        <li><i>notExist</i>: la caccia al tesoro specificata non esiste</li>
        <li><i>noUser</i>: l'utente specificato non esiste</li>
        <li><i>noTransparency</i>: la caccia al tesoro non è trasparente</li>
        <li><i>outOfBound</i>: l'utente ha già mandato il numero massimo di falsi indizi per questa caccia al tesoro</li>
        <li><i>noTurn</i>: il turno specificato non esiste</li>
        <li><i>notSubscribed</i>: non si è iscritti alla caccia specificata</li>
      </ul>
     <p>Il messaggio può contenere inoltre testo che lo descrive in linguaggio naturale.</p>
     <p>La risposta del THS è pertanto un frammento XML (contenuto nel body della risposta HTTP) validato dal seguente XML-Schema:</p>
   <verbatim>
   <?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="noUser"/>
                  <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
        - 'noUser' -> l'utente specificato non esiste 
        - '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>
   </verbatim>
  
  
  
  
  <h3>3.7 Caricamento di una caccia al tesoro</h3>
 <p>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.</p>
       <p>I possibili output di questa operazione sono:</p>
       <ul>
        <li><i>Accepted</i>: caccia al tesoro caricata</li>
        <li><i>noUser</i>: l'utente specificato non esiste</li>
        <li><i>notWellFormed</i>:  il documento di configurazione non è ben formato</li>
        <li><i>notValid</i>: il documento di configurazione non è valido</li>
       </ul>
     <p>Il messaggio può contenere inoltre testo che lo descrive in linguaggio naturale.</p>
     <p>La risposta del THS è pertanto un frammento XML (contenuto nel body della risposta HTTP) validato dal seguente XML-Schema:</p>
   <verbatim>
   <?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="noUser"/>
                  <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:
        - 'noUser' -> l'utente specificato non esiste 
        - 'notWellFormed' -> il documento di configurazione non è ben formato
        - 'notValid' -> il documento di configurazione non è valido
      -->
      </xs:complexType>
   </xs:element>
</xs:schema>
   </verbatim>
  
  
  <h3>3.8 Cancellazione di una caccia al tesoro</h3>
  <p>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.</p>
       <p>I possibili output di questa operazione sono:</p>
       <ul>
        <li><i>Accepted</i>: caccia al tesoro cancellata</li>
        <li><i>noUser</i>: l'utente specificato non esiste</li>
        <li><i>notExist</i>: la caccia specificata non esiste</li>
        <li><i>noPermission</i>: l'utente non ha i permessi per rimuovere la caccia al tesoro</li>
       </ul>                  
     <p>La risposta del THS è pertanto un frammento XML (contenuto nel body della risposta HTTP) validato dal seguente XML-Schema:</p>
   <verbatim>
   <?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="noUser"/>
                  <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:
        - 'noUser' -> l'utente specificato non esiste 
        - '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>
   </verbatim>
  
  
  
  <h3>3.9 Partenza di una caccia al tesoro</h3>
   <p>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.</p>
       <p>I possibili output di questa operazione sono:</p>
       <ul>
        <li><i>Accepted</i>: caccia al tesoro avviata senza errori</li>
        <li><i>noUser</i>: l'utente specificato non esiste</li>
        <li><i>notExist</i>: la caccia specificata non esiste</li>
        <li><i>noPermission</i>: l'utente non ha i permessi per lanciare la caccia al tesoro</li>
        <li><i>alreadyStarted</i>:  la caccia al tesoro è già in corso</li>
       </ul>                  
     <p>La risposta del THS è pertanto un frammento XML (contenuto nel body della risposta HTTP) validato dal seguente XML-Schema:</p>
   <verbatim>
   <?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="noUser"/>
                  <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:
        - 'noUser' -> l'utente specificato non esiste 
        - '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>
   </verbatim>

<h2>4. Tipi globali</h2>
<p>Questa sezione contiene le dichiarazioni XML-Schema di alcuni tipi globali, usati in vari frammenti XML di questo protocollo.</p>
<p>I riferimenti a questi tipi sono contenuti ad esempio negli schemi relativi agli indizi o ai messaggi ritornati dal THS al THC.</p>

<verbatim>
   <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>    

</verbatim>

<h2>5. Modifiche rispetto alle versioni precedenti</h2>

<p>Non esistono versioni precedenti. Non si hanno dunque modifiche.</p>      
      

%HIDE%
   * Set ALLOWTOPICCHANGE =  Main.FabioVitali, Main.SilvioPeroni, Main.AngeloDiIorio, Main.AlessandroCaponi
%E%
to top
End of topic
Skip to action links | Back to top
Edit | Attach image or document | Printable version | Raw text | More topic actions
Revisions: | r1.46 | > | r1.45 | > | r1.44 | Total page history | Backlinks
You are here: TechWeb09 > TreasureHuntProtocol10

to top