3. Cargador XML-RPC API

3.1. Introduction

Cargador supports API through XML-RPC over HTTP protocol. The access was compatibility-tested with Python and PHP XML-RPC clients.

In Cerebro, files are identified by hash sums of their content. Those hash sums are stored in the database. Caragador delivers access to all the files by their hash sums.

Before starting to work with file, it needs to be imported to Cargador catalogue by executing importFile() / ingestFile() functions, or by sending it directly through HTTP protocol.The system detects the hash. Further operations with the file will go through this hash.

The physical location of the file can be found by executing catalogResolve().

File can be sent to remote Cargador’s catalogue by executing catalogUpload (). Similarly, missing file can be downloaded from a remone Cargador, executing catalogDownload ().These operations are asynchronous.

In order to monitor the current download/upload queue, statusTables () function is used. To manage the queues use, controlIO() .

3.2. Methods

Below is the list of supported methods with descriptions.

statusInfo()

is used to recieve the information avaiable for reading on the Caragador service status.

returns:info STR

statusTables(tablesBitMask INT, flags INT)

Gets a table with information about the current or previous file operations.

statusTableMask : bit mask with tables that are requested. See TableKind description below.

flags : flags that modify results. See StatusTableFlags description below.

TableKind

{
pc_tkDomestricDown = 1, // загрузки, запрошенные внутренними пользователями
pc_tkDomestricUp = 2, // выгрузки, запрошенные внутренними
пользователями
pc_tkForeignArrive = 4, // прибывающие от внешних пользователей файлы
pc_tkForeignDepart = 8,// отправляемые внешним пользователям файлы
pc_tkArchiveDown = 0x10, // архивные записи о прошедших операциях
pc_tkArchiveUp = 0x20,
pc_tkArchiveArrive = 0x40,
pc_tkArchiveDepart = 0x80,
};

StatusTableFlags

{
tqIncludeTemporar = 1, // "Временные" закачки фактически относятся к
загрузке миниатюр. Получение данных о них может вернуть большое
количество случайно возникающих/исчезающих закачек.
};

Status

{
tsReady = 10, // готова к старту, ждет очереди
tsFirstCheck = 20, // сервисный статус, первичная проверка
tsInstantDown = 30, // сервисный статус, скачивание по контрольному соединению
tsSecondCheck = 40,// сервисный статус, вторичная проверка
tsConnecting = 50, //// сервисный статус, соединение с удаленным Cargador
tsRun = 60, // идет закачка
tsRestarting = 70, // перезапуск после ошибки
tsCompleted = 80, // завершено
tsStopped = 90, // остановлено пользователем
tsError = 0x7fffffff, // ошибка
};

returns: SET OF

{
tableKind INT
hash HASH
status INT // см. Status ниже
creationTime TIMESTAMP
user STR
url STR // дружелюбный к пользователю путь к файлу
fileName STR
fileSize INT
fileOfs INT // если status==tsRun (закачка в процессе), текущее обрабатываемое положение
}

catalogResolve(hash HASH)

Specifies file path and its attributes in Cargador catalogue

returns:SET OF

{
path (net-rooted) TXT
mtm TIMESTAMP
size INT
}

catalogDelete(hash HASH, password STR)

Removes (actually just moves to temporary directory) a file in catalogue.

hash - file hash for removal

password - should match with value set in cargador.conf/config/catalog/del_password configuration file

Delete operation will be rejected in case when a ‘password’ parameter is not defined in the configuration file.

Mind, that password will be sent as plain text.

returns: VOID

catalogUpload(hash HASH, siteList STR, CommenceFlags INT, userName STR, url STR, retryCount INT)

catalogDownload(hash HASH, siteList STR, CommenceFlags INT, userName STR, url STR, retryCount INT)

Commands Cargador to upload/download the file onto remote Cargador(s). This method does not wait until the operation is finished, instead it places a task in queue and shuts down. Use statusTables() to monitor current operations, and controlIO() to control them.

hash - file hash for uploading/downloading

siteList - string which stores deleted Cargador systems list. String format:

addr1:port1[?name1][;addr2:port2[?name2]]

addr - IP or DNS name of remote Cargador

port - ‘foreign’ port (usually 45431)

‘name’ - optional user-friendly Cargador server name

CommenceFlags - see below

userName - operation creator’s username. For informational purposes. url - user-friendly file path, example:/<project>/task /sub-task/file.name

retryCount - number of retries before operation gets error status. System will restart those operations anyway, but it won’t occur often.

returns: VOID

controlIO(hash HASH, TableKind INT, Action INT)

Controls current file operations.

hash - file hash

TableKind - table where we control. Only current (i.e. not archived) tables can be used.

Action - what to do (see below).

returns: VOID

Action

{
kUp = 0,
kDown = 1,
kTop = 2,
kBottom = 3,
kStop = 4,
kGo = 6,
kDelete = 7,
}

importFile(absLocalPath TEXT, [localCargadorFile TEXT])

ingestFile(absLocalPath TEXT, localCargadorFile TEXT)

Imports file using absLocalPath, an absolute path to Cargador catalogue. ingestFile moves file to Cargador catalogue, while importFile leaves a file as is.

absLocalPath must point to file available for cargador-server, i.e. you cannot use this method to import a local file from your workstation to Cargador.

You can use the HTTP PUT method to import file into Cargador catalogue. Python API library has a function for this.

returns: importedHash HASH