Simple authorization by username and plaintext password.

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

Return value is number. List of error codes is in the following table

Extended authorization. Authorize user by username and password encrypted by selected method. (Compatibility notice AUTHORIZE2)

AuthorizeResponse authorize2(string ticker, string method, string user, string password);

Return value is structure containing error code and error description. Set errorCode to 0 when authorization process was successfull.

/* AuthorizeResponse description */
struct AuthorizeResponse {
    /* error code 0-OK, >0 - fail*/ 
    int errorCode;
    /* string containing error description message */
    string errorDescription;
}

Structure Document is usually used to send/receive 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; 
  };
 };
};

Document can be send from server to client using method pushDocument.

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

Client receiving this method call should display received document. Document can be in read-only or with full access rights.

Client can request document using method getDocument.

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

Method will return structure GetDocumentResponse. Requested document will be send using method pushDocument (Section 6.2, “Push Document”).

struct GetDocumentResponse { 
 string ticker;
 int retCode;
 string version;
} 

Item retCode is 0 if success. If method failed item retCode will be greater then 0.

Item version contains returned version ( can be used to pair pushDocument with this request ).

Changed or new document is saved using method saveDocument. Save operation is done in three steps:

/* Structure with newly allocated
 * Identifiers, new version
 */
Struct SaveDocument {
 /* Document state:
  * 0 – ok, 
  * 1 – lock, 
  * 2 – document not up2date, 
  * 3 – error 
  * 4 - error with detail, error details are stored in version and serverVersion fields */ 
 int state;
 /* Document identifier. This is unique
  * document identifier. If new document
  * is saved server has to generate this 
  * identifier. When error is returned this field is empty string*/
 string documentId;
 /* Identifier of new document version.
  * Each document version has unique combination of
  * docId and version. 
  * 
  * Error message is stored here when state is 4. This message will be shown in UI to user.
  */
 string version;
 /* Identifier of new server version.
  * Server version is used by optimistic 
  * server locks. 
  *
  * Detailed error message is stored here when state is 4. This message will be logged on client side and/or shown as detail or error.
  */
 string serverVersion;
 /* List of new Identifiers for files. */
 array<string> NewFileIdents;
};      

Function for saving new document or new version:

SaveDocument saveDocument(string ticker, Document document);

Structure Document is parameter of the funcion. All requested items have to be correctly filled in the structure. Document identifier is empty string if document is saved for first time (new document). Server will return new document identifier.

Page identifiers are set only for existing unmodified pages. If page is modified or new identifier is empty string.

Function will return list of new file identifiers and identifier of new document. Server behavioure:

Compatibility notice: error state 4 is valid only when STOREDOCUMENT is set to 1.

Notification about succefull save operation:

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

Function has no return value and is used only for client notification.

Existing document can be deleted using method deleteDocument. Function has parameter document id as parameter.

int deleteDocument(string ticker, string documentId);

Function return 0 if success, 1 - document is locked, 2 - no permissions, 3 - other error

File from server can be requested using method requestFile. When server receive such request it has to send page to the client. File is send in frame type 1 (Chapter 5, Frame Type 1).

void requestFile(string ticker, string fileId);

If file is not available server can send notification requestFileFailed (Section 7.2, “Failed File Request”).

If file request (Section 7.1, “Request File”) failed other side should send response requestFileFailed. It is up to the caller to correctly display this error to the user.

void requestFileFailed(string ticker, string fileId, int errorCode, string description);

Parameter fileId is unique file identifier.

Parameter errorCode is error code.

Parameter description is error description.

Configuration file can be requested using method requestConfig. Method will send configuration file to the client. File is send as frame, type 2.

void requestConfig(string ticker, string fileId);

If file is not available server can send notification requestFileFailed (Section 7.5, “Failed Config Request”).

Configuration file can be updated/requested using method requestConfig2.

void requestConfig2(string ticker, string fileId, string hashType, string fileHash)

Method will send configuration file if hash of the configuration file on the server is different from the hash of the current configuration file on the client. File is send as frame type 2. Server have to send new configuration file or respond errorRequestConfig. Method errorRequestConfig is used to signal that current configuration is up-to-date (errorCode is set to 0) or to signal wrong request (errorCode greater then 0 ).

requestConfig2("ticker", "config.zip", "md5", 
               "fcd66e666a77a18ca8d08c24f40bc439");

If configuration file does not exists or some other error occur server should send followinf notification about error.

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

Method requestTaskList can be used to request list of tasks.

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

Parameter tasks is list of currently available taks on the client.

Server can send list of tasks to the client using method pushTaskList.

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

Parametr tasks is list of tasks. Flag values are in the following table:

Total number of displayed tasks on the client can be limitied in the server configuration. Tasks which client sent to the server in the requestTaskList and are not part of the response are not valid anymore and client have to delete them from UI.

Specific task can be requested using method requestTask.

void requestTask(string ticker, string taskId);

Method request task from the server. Way of sending task to the client is up to server implementation, common way is to use method pushDocument. Server can notify about error in task request using method errorRequestTask.

void errorRequestTask(string ticker, string taskId);

Methods allows to open folder. Client will receive for opened folder notifications about changes. Notifications are send until the folder is closed (Section 9.2, “Close Folder”).

Folder openFolder(string ticker, string folderId);

struct Folder { 
 // Status of folder 
 // -3 - no permission to open
 // -2 - folder is locked 
 // -1 - folder not exists 
 // 0 - ok
 int status;
 // Items in the folder 
 array items { 
  struct FolderItem { 
   // Type
   // 0 - folder, 1 - document
   int type;
   // Item id
   // id of folder or id of document
   string itemId;
   // Item name
   string name;
  };
 };
};

Close folder. Closing folder will also stop sending notifications about folder changes.

void closeFolder(string ticker, string folderId);

Client (subscriber) will receive notification about folder changes. Following notifications are available:

void updateItem(string ticker, string folderId, int oper, FolderItem item);

Function has three parameters: path, type of change, item with new data.

Possible types:

Folder or item can be renamed using method renameItem.

int renameItem(string ticker, string parentFolderId, string itemId, string name);

parentFolderId is id of the folder.

Return values: 0 - ok, 1 - wrong id, 2 - no permissions, 3 - other error

New document is added to the tree calling bindDocument. Document have to be saved before it can be add to the tree.

int bindDocument(string ticker, string parentFolderId, string name, string docId);

Return values: 0 - ok, 1 - wrong id, 2 - no permissions, 3 - other error

It is possible to move any tree item to another folder. Method also allows to remove item from the tree.

int moveItem(string ticker, string parentFolderId, string itemId, string newFolderId);

parentFolderId is id of the original folder

newFolderId is id of new folder. If this parameter is empty string item will be removed from the tree.

Return values: 0 - ok, 1 - wrong id, 2 - no permissions, 3 - other error

It is possible to delete folder using method removeFolder.

int removeFolder(string ticker, string folderId);

Only empty folder can be removed.

Possible return values: