Skip to topic | Skip to bottom
Home

TechWeb09
TechWeb09.TreasureHuntProtocol12r1.7 - 21 May 2009 - 17:17 - AngeloDiIoriotopic end

Start of topic | Skip to actions

Treasure Hunt Protocol

Specifiche di protocollo

Versione 1.2 Maggio 2009

Questa versione: TreasureHuntProtocol12

Ultima versione: TreasureHuntProtocol12

Versione Precedente: TreasureHuntProtocol11

Autori: FabioVitali, AngeloDiIorio, SilvioPeroni

Abstract

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:

  • 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.
  • 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.

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.

Stato di questo documento

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.

1. Protocollo THP

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.

2. Dettagli delle richieste THC -> THS

L'applicazione THC pu inoltrare le seguenti richieste all'applicazione THS:

  • Elenco delle cacce al tesoro disponibili
  • Iscrizione ad una caccia al tesoro
  • Richiesta di indizio
  • Sottomissione di una risposta
  • Richiesta dello status dei team
  • Sottomissione di un falso indizio
  • Caricamento di una caccia al tesoro
  • Cancellazione di una caccia al tesoro
  • Partenza di una caccia al tesoro

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.

2.1 Elenco delle cacce al tesoro disponibili

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

2.2 Iscrizione ad una caccia al tesoro

Tramite questa richiesta il THC iscrive un utente o un gruppo alla caccia al tesoro.

La richiesta specifica tre parametri:

  • Identificativo dell'utente o del gruppo da iscrivere alla caccia al tesoro
  • Password dell'utente o del gruppo da iscrivere alla caccia al tesoro
  • Identificativo della caccia a cui iscriversi

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>

2.3 Richiesta di indizio

Tramite questa richiesta il THC chiede l'indizio successivo.

La richiesta specifica due parametri:

  • Identificativo dell'utente o del gruppo
  • Password dell'utente o del gruppo
  • Identificativo della caccia

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>

2.4 Sottomissione di una risposta

Tramite questa richiesta il THC spedisce al server la risposta relativa al turno corrente.

La richiesta specifica tre parametri:

  • Identificativo dell'utente o del gruppo
  • Password dell'utente o del gruppo
  • Identificativo della caccia
  • Risposta

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 4.

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

2.5 Richiesta dello status dei team

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:

  • Identificativo dell'utente o del gruppo
  • Password dell'utente o del gruppo
  • Identificativo della caccia

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>

2.6 Sottomissione di un falso indizio

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:

  • Identificativo dell'utente o del gruppo
  • Password dell'utente o del gruppo
  • Identificativo della caccia
  • Identificativo del turno
  • il falso indizio

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>

2.7 Caricamento di una caccia al tesoro

Tramite questa richiesta il THC carica una nuova caccia al tesoro sul THS.

La richiesta specifica due parametri:

  • Identificativo dell'organizzatore
  • Password dell'organizzatore
  • La configurazione vera e propria della caccia al tesoro

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.

2.8 Cancellazione di una caccia al tesoro

Tramite questa richiesta il THC chiede al THS di eliminare una caccia al tesoro tra quelle disponibili agli utenti.

La richiesta specifica due parametri:

  • Identificativo dell'organizzatore
  • Password dell'organizzatore
  • Identificativo della caccia

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>  

2.9 Partenza di una caccia al tesoro

Tramite questa richiesta il THC chiede al THS di far partire una caccia al tesoro.

La richiesta specifica due parametri:

  • Identificativo dell'organizzatore
  • Password dell'organizzatore
  • Identificativo della caccia

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>

3. Dettagli delle risposte THS -> THC

L'applicazione THS risponde alle seguenti richieste provenienti dall'applicazione THC:

  • Elenco delle cacce al tesoro disponibili
  • Iscrizione ad una caccia al tesoro
  • Richiesta di indizio
  • Sottomissione di una risposta
  • Richiesta dello status dei team
  • Sottomissione di un falso indizio
  • Caricamento di una caccia al tesoro
  • Cancellazione di una caccia al tesoro
  • Partenza di una caccia al tesoro

3.1 Elenco delle cacce al tesoro disponibili

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>

3.2 Iscrizione ad una caccia al tesoro

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:

  • Accepted: iscrizione avvenuta con successo
  • 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

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>

3.3 Richiesta di indizio

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:

  • Accepted: indizio disponibile (ed contenuto nella risposta)
  • 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

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>

3.4 Sottomissione di una risposta

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:

  • Right: risposta corretta
  • Wrong: risposta sbagliata
  • Win: risposta corretta e caccia al tesoro vinta
  • 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

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>

3.5 Richiesta dello status dei team

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:

  • Accepted: 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
  • notExist: la caccia al tesoro specificata non esiste
  • wrongPass: la password specificata non associata all'utente
  • noPermission: non si hanno i permessi necessari per partecipare alla caccia al tesoro specificata
  • noTransparency: la caccia al tesoro non trasparente

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>

3.6 Sottomissione di un falso indizio

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:

  • Accepted: falso indizio accettato
  • notExist: la caccia al tesoro specificata non esiste
  • wrongPass: la password specificata non associata all'utente
  • noTransparency: la caccia al tesoro non trasparente
  • outOfBound: l'utente ha gi mandato il numero massimo di falsi indizi per questa caccia al tesoro
  • outOfMaxAllowedTurn: superato il numero massimo di falsi indizi permessi per questo turno
  • noTurn: il turno specificato non esiste
  • notSubscribed: non si iscritti alla caccia specificata

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>

3.7 Caricamento di una caccia al tesoro

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:

  • Accepted: caccia al tesoro caricata
  • passAlreadyAssigned: la password specificata gi stata assegnata
  • notWellFormed: il documento di configurazione non ben formato
  • notValid: il documento di configurazione non valido

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>

3.8 Cancellazione di una caccia al tesoro

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:

  • Accepted: caccia al tesoro cancellata
  • wrongPass: la password specificata non associata all'utente
  • notExist: la caccia specificata non esiste
  • noPermission: l'utente non ha i permessi per rimuovere la caccia al tesoro

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>

3.9 Partenza di una caccia al tesoro

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:

  • Accepted: caccia al tesoro avviata senza errori
  • wrongPass: la password specificata non associata all'utente
  • notExist: la caccia specificata non esiste
  • noPermission: l'utente non ha i permessi per lanciare la caccia al tesoro
  • alreadyStarted: la caccia al tesoro gi in corso

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>

4. Tipi globali

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>    

5. Modifiche rispetto alle versioni precedenti

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.


to top

You are here: TechWeb09 > TreasureHuntProtocol12

to top

Copyright © Fabio Vitali 2017 Last update of TreasureHuntProtocol12 on 21 May 2009 - 17:17 by AngeloDiIorio