.. only:: html .. _capi-xml-rpc: Интерфейс к файловому хранилищу Cargador по протоколу XML-RPC =============================================================== Вступление -------------------- Cargador поддерживает API посредством XML-RPC поверх протокола HTTP. Доступ протестирован на совместимость с XML-RPC клиентами языков Python и PHP. В системе Cerebro файлы идентифицируются по хэшам их содержимого. Именно значения хэшей хранятся в базе данных. Cargador обеспечивает доступ и работу с файлами по значению хэша. Перед началом работы с файлом его необходимо импортировать в каталог Cargador посредством вызова функций importFile(), ingestFile() или прямой отправкой по HTTP-протоколу. Система вычисляет его хэш. Дальнейшие операции с файлом происходят через этот хэш. Физическое расположение файла можно узнать, вызвав catalogResolve(). Файл можно отправить в каталог удаленного Cargador путем вызова catalogUpload(). Аналогично, отсутствующий файл можно скачать с удаленного Cargador, вызвав catalogDownload(). Эти операции асинхронные. Для мониторинга текущих очередей скачки/закачки используется функция statusTables() . Для управления очередями используется controlIO() . Методы ------------------- Ниже приведен список поддерживаемых методов с описаниями. **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 - дружелюбный к пользователю путь до файла. пример://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