3. Интерфейс к файловому хранилищу Cargador по протоколу XML-RPC

3.1. Вступление

Cargador поддерживает API посредством XML-RPC поверх протокола HTTP. Доступ протестирован на совместимость с XML-RPC клиентами языков Python и PHP.

В системе Cerebro файлы идентифицируются по хэшам их содержимого. Именно значения хэшей хранятся в базе данных. Cargador обеспечивает доступ и работу с файлами по значению хэша.

Перед началом работы с файлом его необходимо импортировать в каталог Cargador посредством вызова функций importFile(), ingestFile() или прямой отправкой по HTTP-протоколу. Система вычисляет его хэш. Дальнейшие операции с файлом происходят через этот хэш.

Физическое расположение файла можно узнать, вызвав catalogResolve().

Файл можно отправить в каталог удаленного Cargador путем вызова catalogUpload(). Аналогично, отсутствующий файл можно скачать с удаленного Cargador, вызвав catalogDownload(). Эти операции асинхронные.

Для мониторинга текущих очередей скачки/закачки используется функция statusTables() . Для управления очередями используется controlIO() .

3.2. Методы

Ниже приведен список поддерживаемых методов с описаниями.

statusInfo()

Получить доступную для чтения пользователем информацию о статусе сервиса Cargador

returns:info STR

statusTables(tablesBitMask INT, flags INT)

Получить таблицу с данными о текущих или прошедших файловых операциях.

statusTableMask : битовая маска с желаемыми к получению таблицами. Смотрите описание TableKind ниже.

flags :модифицирующие результат флаги. Смотрите описание StatusTableFlags ниже.

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)

Определяет путь к файлу и его атрибуты в каталоге Cargador

returns:SET OF

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

catalogDelete(hash HASH, password STR)

Удаляет (фактически переносит во временную директорию) файл в каталоге.

hash - хэш файла к удалению

password - должно совпадать со значением, заданным в конфигурационном файле cargador.conf/config/catalog/del_password.

Операция удаления будет отвергаться в случае, когда параметр „password“ не задан в конфигурационном файле.

Имейте в виду: пароль пересылается в открытом виде.

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)

Дает команду Cargador приступить к загрузке или выгрузке файла на удаленный(-ые) Cargador. Метод не дожидается завершения операции, вместо этого он размещает задание в очереди и завершается. Используйте statusTables() для мониторинга текущих операций и controlIO() для их контроля

hash - хэш файла для загрузки / выгрузки

siteList - строка соспискомудаленных систем Cargador. Формат строки:

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

addr - IP или DNS имя удаленного cargador.

port - „foreign“ порт (обычно 45431).

„name“ - необязательное дружелюбное к пользователю название удаленного сервера Cargador.

CommenceFlags - смотрите ниже

userName - имя создавшего файловую операцию. Для информационных целей. url - дружелюбный к пользователю путь до файла. пример:/<project>/task /sub-task/file.name

retryCount - количество попыток перед тем, как задача перейдет в статус ошибки. Система в любом случае перезапускает ошибочные задачи, но делает это реже.

returns: VOID

controlIO(hash HASH, TableKind INT, Action INT)

Контролирует текущие файловые операции.

hash -хэш файла.

TableKind - таблица, в которой контролируем. Только текущие (т.е. не архивные) таблицы могут использоваться.

Action - что делать (смотрите ниже).

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)

Импортирует файл по абсолютному пути absLocalPath в каталог Cargador. ingestFile при этом перемещает файл в каталог Cargador, в то время как importFile оставляет файл как есть.

absLocalPath должен указывать на доступный для cargador-сервера файл, т.е. вы не можете, используя этот метод, импортировать локальный файл со своей рабочей станции в Cargador.

Вы можете использовать HTTP PUT метод для того, чтобы импортировать файл в каталог Cargador. В составе библиотеки Python API имеется функция для этого.

returns: importedHash HASH