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.
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:
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:
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>
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 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.
Klient může zaslat žádost o dokument pomocí metody getDocument.
int getDocument(string ticker, string docId, string version);
Tabulka 4.
Parametr | Význam |
docId | jednoznačný identifikátor dokumentu |
version | identifikace verze, pokud je řetězec prázdný je zaslána poslední verze |
Metoda vrací 0 v případě platné žádosti. V případě chyby, neplatná žádost nebo nedostupnosti dokumentu je vrácena hodnota >0.
Vyžádaný dokument je zaslán zpět pomocí metody pushDocument.
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);
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);
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.
Jestliže je vyžádán dokument v průběhu ukládání, tak se vrací poslední platně uložená verze.
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);
Funkce nemá žádnou návratovou hodnotu a slouží pouze pro notifikaci klienta.
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.
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í: