#acl TahitiAdminGroup:read,write All:read
#pragma title Tahiti 4.x, protokol - Type 0
#pragma title-link ProtocolCZ


Jedná se o základní typ umožňující přenos jednoho XML souboru. Ten je určen pro přenos dotazu, resp. odpovědi na dotaz. Formát souboru musí odpovídat standardu XML-RPC (viz. http://www.xmlrpc.com/spec ). Tento typ rámce slouží pro vzdálená volání. Následující popis dostupných metod je zapsán pomocí „pseudo C“ syntaxe.

Součástí každého volání je položka ticker, která slouží k jednoznačné identifikaci volání. Tato položka je vrácena současně s návratovou hodnotou funkce.

== Autorizace ==
Prvním krokem po vytvoření spojení je autorizace klienta. Ta se provede zavoláním metody authorize.

{{{int authorize(string ticker, string user, string password);}}}

Parametrem metody jsou:
|| user || uživatelské jméno ||
|| password || heslo pro přihlášení ||

Příklad převedeného volání do XML-RPC:
{{{
<?xml version="1.0"?>
<methodCall>
  <methodName>authorize</methodName>
  <params>
    <param>
      <value><string>ticker</string></value>
    </param>
    <param>
      <value><string>user</string></value>
    </param>
    <param>
      <value><string>password</string></value>
    </param>
  </params>
</methodCall>
}}}

Jako odpověď je očekáváno číslo:
|| 0 || korektní přihlášení ||
|| 1 || chybné jméno nebo heslo ||
|| 2 || jiná chyba při přihlášení ||

== Vzor odpovědi ==
Formát odpovědi odpovídá standardní odpovědi pro XML-RPC. Navíc vždy jako první parametr obsahuje ticker, který je shodný jako při volání.
{{{
<?xml version="1.0"?>
<methodResponse>
   <params>
      <param>
         <value><string>ticker</string></value>
      </param>
      <param>
         <value><i4>130</i4></value>
      </param>
   </params>
</methodResponse>
}}}

== Popis dokumentu a jeho příjem ==
Dokument je popsán strukturou Document.
{{{
/* Document description */
Struct Document {
    /* Unique document identifacator */
    string documentId;
    /* Document version. Every document 
     * can have more versions. 
     */
    string version;
    /* Document version. This is identification
     * of subversion on server side. Client can
     * safely ignore this value and have to just
     * send it back to server. 
     */
    string serverVersion;  
    /* Document type. Document type define which
     * attributes are valid for document, how-to 
     * display document and organize in logical 
     * structure. Every document have to have 
     * valid type. 
     */
    string type;  
    /* Document modification. 
     * 0 – document is not modified
     * 1 – document attributes are modified
     */
    int modified;  
    /* Document attributes. Array of document 
     * attributes. Used attributes depens on document type
     */
    array attributes {
       /* Structure describes one attribute */        
       struct Attribute  {
           /* Attribute name */
           string name;
           /* Attribute value */
           string value; 
       };
    };
    /* Array of files, pages. */
    array files {  
        /* Structure describing one file, page */
        struct File {
            /* Unique file (page) identifacator */
            string ident;
            /* File mime-type. */
            string mimeType;
            /* Page importance. 
             * 0 – page is not important
             * 1 – page is important
             */
            int important;
            /* Page modification. 
             * 0 – page is not modified
             * 1 – page attributes are modified
             * 2 – page data modified
             * 3 – page attributes and data modified  
             */
            int modified;
            /* Page number */
            int pageNumber;
            /* Page notes or comments. */
            string note;
            /* Original filename. */
            string origName;
            /* Keys for page decryption/encryption. */
            string keys;
            /* Page signature. */
            string signature;
        };
    };
};
}}}

Dokument ze serveru na klienta je možno zaslat metodou pushDocument. Metoda zajistí přeposlání dokumentu, resp. popisu jeho struktury {{{Document}}}. Metoda nemá žádnou návratovou hodnotu. Při příjmu dokumentu klient reaguje na nastavení hodnot {{{modified}}}.

{{{void pushDocument(string ticker, Document document, int state);}}}

Parametr state určuje, zda je možno dokument odeslat zpět, zde je určen pouze k prohlížení či je možno mazat stránky (0 – dokument pouze pro čtení, 1 – dokument pro čtení a zápis). 

== Vyžádání souboru ==
Vyžádání souboru ze serveru se provede metodou {{{requestFile}}}. Metoda zajistí odeslání jedné stránky do klienta. Soubor je odesílán jako rámec typu 1.

{{{void requestFile(string ticker, string fileId);}}}

Parametr {{{fileId}}} je jednoznačný identifikátor souboru.

== Vyžádání dokumentu ==
Klient může zaslat žádost o dokument pomocí metody getDocument. 

{{{GetDocumentResponse getDocument(string ticker, string docId, string version, int state);}}}

|| Parametr || Význam ||
|| docId || jednoznačný identifikátor dokumentu ||
|| version || identifikace verze, pokud je řetězec prázdný je zaslána poslední verze ||
|| state || způsob vyžádání (0 - pouze pro čtení, 1 - čtení i zápis) ||

Metoda jako odpoved strukturu GetDocumentResponse.
{{{
struct GetDocumentResponse {
 string ticker;
 int retCode;
 string version;
}
}}}

Parametr retCode obsahuje 0 v případě platné žádosti. V případě chyby, neplatná žádost nebo nedostupnosti dokumentu je vrácena hodnota >0.
Parametr version obsahuje verzi dokumentu, ktery bude vracen ( slouzi ke sparovani vraceneho dokumentu, pokud byla vyzadana posledni verze a ne konkretni cislo verze).  

Vyžádaný dokument je zaslán zpět pomocí metody pushDocument.

== Vyžádání konfigurace ==
Vyžádání konfiguračního souboru ze serveru se provede metodou requestConfig. Metoda zajistí odeslání požadovaného souboru do klienta. Soubor je odesílán jako rámec typu 2.

{{{void requestConfig(string ticker, string fileId);}}}

|| Parametr || Význam ||
|| fileId || jednoznačný identifikátor souboru ||

V případě chyby vyžádání souboru, tj. soubor je neplatný, neexistuje apod. může server vyslat oznámení o chybě. 

{{{void errorRequestConfig(string ticker, string fileId, int errorCode);}}}

|| Parametr || Význam ||
|| fileId || identifikátor souboru, který není možno vrátit ||
|| errorCode || identifikace chyby ke které došlo ||

== Uložení dokumentu ==
Uložení dokumentu se skládá ze tří kroků. Prvním je vytvoření nové verze na straně serveru, alokace identifikátorů pro ukládané soubory, druhým uložení vlastních datových souborů a třetím potvrzení úspěšného přijetí celého dokumentu.

{{{
/* Structure with newly allocated 
 * identificators, new version
 */
Struct SaveDocument {
     /* Document state:
      *  0 – ok, 1 – lock, 2 – document not up2date, 3 – error
      */
     int state;
     /* Document identifacator. This is unique 
      * document identifacator. If new document 
      * is saved server have to generate this identificator.
      */       
     string documentId;
     /* Identificator of new document version.
      * Each document version have to unique combination of 
      * docId and version.
      */
     string version;
     /* Identificator of new server version.
      * Server version is used by optimistic server locks.
      */
     string serverVersion;
     /* List of new identificators for files. */
     array<string> NewFileIdents;
};
}}}

Funkce pro uložení dokumentu nebo jeho nové verze:

{{{SaveDocument saveDocument(string ticker, Document document);}}}

Parametrem funkce je struktura {{{Document}}}. Musí mít korektně vyplněny všechny položky. Výjimku tvoří identifikátory ukládaných souborů. V případě, kdy soubor není modifikován, tj. nebude odesílán na server, tak je vyplněn současný identifikátor, u změněného nebo nového souboru se identifikátor nevyplňuje a je to prázdný řetězec. Funkce vrací zpět identifikátory všech ukládaných souborů. 

Při ukládání nového dokumentu na server je identifikátor dokumentu i jeho verze prázdný řetězec. Server vrací zpět nově vytvořený identifikátor dokumentu a jeho verzi.

=== Chování serveru při ukládání souborů ===

 1. Jestliže je vyžádán dokument v průběhu ukládání, tak se vrací poslední platně uložená verze.
 2. Jestliže se klient pokouší uložit dokument paralelně s jiným je vrácena informace o uplatněném zámku. Zámek se odemkne při uložení všech souborů, pádu spojení nebo vypršení časového limitu.

Po úspěšném přijetí celého dokumentu je poslána notifikace zpět na klienta, tj. zavolána funkce:

{{{void receivedDocument(string ticker, string documentId, string documentVersion);}}}

Funkce nemá žádnou návratovou hodnotu a slouží pouze pro notifikaci klienta.

V případě chyby při ukládání dokumentu je možno klienta notifikovat o této situaci pomocí {{{errorReceivedDocument}}}:

{{{void errorReceivedDocument(string ticker, string documentId, string documentVersion, int reason);}}}

Funkce nemá žádnou návratovou hodnotu a slouží pouze pro notifikaci klienta. Význam proměnné reason (důvod chyby):
|| 1 || lock ||
|| 2 || document not up2date ||
|| 3 || error ||

== Příjem objektu ==
Protokol umožňuje přenos obecných objektů. Přenášený typ objektu je určen položkou type. Další hodnoty definované pro daný typ objektu jsou popsány dvojicí název/hodnota. Následující struktura popisuje jeden přenášený objekt.

{{{
/* Object description /
Struct Object {
    /* Object type */
    string type;
    /* Array of object attributes */
    array attributes {
        /* One attribute */
        struct Attribute {
            /* Attribute name */
            string name;
            /* Attribute value */
            string value; 
        };
    };
};
}}}

Objekt je přenesen pomocí metody {{{pushObject}}}.

{{{void pushObject(ticker, Object);}}}

Metoda zajistí přeposlání objektu, resp. jeho struktury. Metoda nemá žádnou návratovou hodnotu.

== Seznam úkolů ==
Seznam úkolů na straně serveru je možno získat metodou {{{requestTaskList}}}

{{{void requestTaskList(string ticker, array<string> tasks);}}}

Parametr {{{tasks}}} je seznam ůkolů, které má již žadatel k dispozici.

Server může zaslat seznam úkolů klientovi pomocí metody {{{pushTaskList}}}.

{{{void pushTaskList(string ticker, array<string> tasks, int flag);}}}

Parametr {{{tasks}}} je seznam úkolů. Význam proměnné flag je:
|| 1 || Úplný seznam - nahrazuje současný na klientovi - odpověď na volání {{{requestTaskList}}} ||
|| 2 || Doplnění seznamu - úkoly v seznamu by měly být přidány k již aktuálně vyžádaným ||

Celkový počet vrácených úkolů (dostupných na klientovi) může být nastaven jako limit na serveru. Úkoly, které klient odeslal v seznamu svých úkolů a nejsou obsaženy ve vráceném seznamu jsou považovány za neplatné a klient je uvolní z UI.

== Vyžádání úkolu ==
Konkrétní úkol je možno vyžádat metodou {{{requestTask}}}.

{{{void requestTask(string ticker, string taskId);}}}

Metoda pošle požadavek na vyžádání úkolu. Způsob zaslání úkolu závisí na serveru, obvykle voláním metody {{{pushDocument}}}. V případě chyby vyžádání úkolu musí server notifikovat klienta o této skutečnosti.

{{{void errorRequestTask(string ticker, string taskId);}}}

== Stav připojení ==
Po provedení autorizace nemohou přicházet nevyžádané dokumenty na klienta, tj. nelze posílat dokumenty pomocí pushDocument. Změnit stav připojení je možno pomocí metody {{{setState:}}}

{{{void setState(string ticker, int iNewState);}}}

Povolené stavy připojení:
|| 0 || výchozí stav neumožňující příjem dokumentů metodou pushDocument ||
|| 1 || příjem dokumentů pomocí pushDocument je možný ||

== Odpojení ==
Před odpojením jedné ze stran je možno tuto skutečnost signalizovat protistraně voláním metody {{{disconnect}}}. 

{{{void disconnect(int iReason, string description);}}}

Důvod odpojení je uveden v proměnné {{{iReason}}}. Důvody odpojení:
|| 0 || timeout ||
|| 1 || ukonceni aplikace ||
|| 2 || jiný důvod, popis je uveden v proměnné description ||