Описание протокола клиент-сервер¶
- Описание протокола клиент-сервер
- Инициализация файлового менеджера
- Список команд
- Описание команд
- open
- mkdir
- mkfile
- rename
- upload
- ping
- paste
- rm
- duplicate
- read
- edit
- extract
- archive
- tmb
- resize
Коннектор (connector) - обрабатывается на сервере (PHP, Python). Клиент (client) - обрабатывается на стороне пользователя в браузере (JavaScript). Когда пользователь выполняет какое-либо действие с файлами клиент отправляет на сервер (в коннектор) запрос и получает ответ. Коннектор получает данные от клиента через GET или через POST (только при загрузке upload и редактировании edit). Коннектор всегда возвращает клиенту объект JSON.
Обязятельный параметр, всегда ожидаемый коннектором - cmd - имя команды, пример: http://localhost/connector.php?cmd=open
- current : (String) hash пути текущей директории
- target : (String) hash пути файла над которым совержается действие
- targets : (Array) массив hash'ей путей файлов/директорий над которыми совершается действие
- error : (String) строка с сообщением об ошибке
- errorData : (Object) объект с сообщениями о нефатальных ошибках, ключ - имя файла/директори, значение - сообщение об ошибке
- select : (Array) массив hash'ей файлов/директорий, которые необходимо выделить после выполнения команды (upload, mkdir, mkfile и т.д.)
- debug : (Object) объект с отладочной информацией
- reload, back - реализуются серверной командой open
- list, icons, quicklook, copy, cut - работают только на клиенте и не обращаются к коннектору
Любая команда, получившая некорректные аргументы, прекращает дальнейшее выполнение и возвращает error (сообщение об ошибке); исключение open - возвращает сообщение об ошибке и контент корневой директории.
Внимание! Пути к файлам не передаются в чистом виде, только hash от пути (md5 или любая другая hash-функция).
Инициализация файлового менеджера¶
Аргументы передаваемые клиентом коннектору (клиент -> сервер):- cmd : open
- init : true
- tree : true
Пример: http://localhost:8001/~troex/cgi/connector.py?cmd=open&init=true&tree=true
Ответ (сервер -> клиент): смотрите описание команды open, плюс дополнительно ответ включает:
- disabled : (Array) список отключенных команд
- params: (Object)
- dotFiles : (Boolean) разрешено ли показывать скрытые файлы, начинающиеся с точки
- uplMaxSize : (String) макимальный разрешенный размер загружаемых файлов (например: 128M)
- archives : (Array) Список mime-типов архивов, которые могут быть созданы коннектором
- extract : (Array) Список mime-типов архивов, которые коннектор может распаковать
- url : (String) URL где расположен корень файлов коннектора
Пример корректного ответа:
JSON:
1 {
2 "cwd": {
3 "name" : "Home",
4 "hash" : "b4473c8c08d1d499ecd7112f3398f125",
5 "rel" : "Home",
6 "date" : "30 Jan 2010 14:25",
7 "mime" : "directory",
8 "size" : 0,
9 "read" : true,
10 "write" : true,
11 "rm" : false
12 },
13 "cdc": [
14 {
15 "name" : "test",
16 "hash" : "ac4b61565950a73395c871f9c3fc7362",
17 "date" : "Today 14:11",
18 "mime" : "directory",
19 "size" : 102,
20 "read" : true,
21 "write" : true,
22 "rm" : true
23 },
24 {
25 "name" : "link to README",
26 "hash" : "4fc059e61577f0267fbd6c1c5bafb1b4",
27 "url" : "http://localhost:8001/~troex/git/elfinder/files/wiki/README.txt",
28 "date" : "Today 16:50",
29 "mime" : "text/plain",
30 "size" : 10,
31 "read" : true,
32 "write" : true,
33 "rm" : true,
34 "link" : "8d331825ebfbe1ddae14d314bf81a712",
35 "linkTo": "Home/README.txt",
36 "parent": "b4473c8c08d1d499ecd7112f3398f125"
37 },
38 {
39 "name" : "logo.png",
40 "hash" : "a696323d7fd86513754004ba8bc12967",
41 "url" : "http://localhost:8001/~troex/git/elfinder/files/wiki/logo.png",
42 "date" : "11 Nov 2009 21:57",
43 "mime" : "image/png",
44 "size" : 18782,
45 "read" : true,
46 "write" : true,
47 "rm" : true
48 },
49 {
50 "name" : "README.txt",
51 "hash" : "8d331825ebfbe1ddae14d314bf81a712",
52 "url" : "http://localhost:8001/~troex/git/elfinder/files/wiki/README.txt",
53 "date" : "Today 14:25",
54 "mime" : "text/plain",
55 "size" : 1171,
56 "read" : true,
57 "write" : true,
58 "rm" : true
59 }
60 ],
61 "tree": {
62 "name" : "Home",
63 "hash" : "b4473c8c08d1d499ecd7112f3398f125",
64 "read" : true,
65 "write" : true,
66 "dirs" : [
67 {
68 "name" : "test",
69 "hash" : "ac4b61565950a73395c871f9c3fc7362",
70 "read" : true,
71 "write" : true,
72 "dirs" : [
73 {
74 "name" : "test2",
75 "hash" : "b3615611cf9f8f6a8821ef20eda450b5",
76 "read" : true,
77 "write" : true,
78 "dirs" : []
79 }
80 ]
81 }
82 ],
83 },
84 "disabled" : [],
85 "params" : {
86 "url" : "http://localhost:8001/~troex/git/elfinder/files/wiki",
87 "dotFiles" : true,
88 "uplMaxSize" : "15M",
89 "extract" : [
90 "application/x-7z-compressed",
91 "application/x-tar",
92 "application/x-gzip",
93 "application/x-bzip2",
94 "application/zip"
95 ],
96 "archives" : [
97 "application/x-7z-compressed",
98 "application/x-tar",
99 "application/x-gzip",
100 "application/x-bzip2",
101 "application/zip"
102 ]
103 }
104 }
Список команд¶
open - открыть директорию или вывести содержимое файла в браузер
mkdir - создать директорию
mkfile - создать текстовый файл
rename - переименовать директорию или файл
upload - загрузить файлы
ping - служебная команда. необходима для Safari (загрузка файлов)
paste - скопировать или переместить файлы/директории в указанную директорию
rm - удалить директорию/файлы
duplicate - сделать копию директории/файла
read - вернуть содержимое текстового файла
edit - сохранить текст в файл
extract - распаковать архив
archive - сжать директории/файлы в архив
tmb - создать миниатюрки для картинок, не имеющих их
resize - изменить размер изображения
Описание команд¶
open¶
Возвращает содержимое директории или выводит файл в браузер.
1. Открытие директории
Аргументы:- cmd : open
- target : hash пути директории
- tree : Не обязательный параметр. Если задан - дополнительно вернуть дерево директорий
Ответ должен содержать (Object) cwd и массив (Array) cdc, дополнительно может присутствовать (Object) tree, пример:
1 {
2 "cwd" : { // (Object) Current Working Directory - Информация о текущей директории
3 "name" : "Home", // (String) Имя директории
4 "hash" : "b4473c8c08d1d499ecd7112f3398f125", // (String) hash от абсолютного пути директории
5 "mime" : "directory", // (String) всегда "directory"
6 "rel" : "Home", // (String) относительный путь до текущей директории
7 "size" : 0, // (Number) размер директории в байтах
8 "date" : "30 Jan 2010 14:25", // (String) время изменения (mtime)
9 "read" : true, // (Boolean) право на чтение
10 "write" : true, // (Boolean) право на запись
11 "rm" : false // (Boolean) право на удаление
12 },
13 "cdc" : [ // (Array) (of Objects) Current Directory Content - Информация о содержимом текущей директории
14 {
15 "name" : "link to README", // (String) Имя директории/файла
16 "hash" : "4fc059e61577f0267fbd6c1c5bafb1b4", // (String) hash
17 "url" : "http://localhost:8001/~troex/git/elfinder/files/wiki/README.txt", // (String) URL
18 "date" : "Today 16:50", // (String) время изменения (mtime)
19 "mime" : "text/plain", // (String) MIME тип файла или "directory"
20 "size" : 10, // (Number) размер файла/директории в байтах
21 "read" : true, // (Boolean) право на чтение
22 "write" : true, // (Boolean) право на запись
23 "rm" : true, // (Boolean) право на удаление
24 "link" : "8d331825ebfbe1ddae14d314bf81a712", // (String) только для ссылок, hash файла
25 // на который ведёт ссылка
26 "linkTo": "Home/README.txt", // (String) только для ссылок, относительный путь
27 // до файла, на который указывает ссылка
28 "parent": "b4473c8c08d1d499ecd7112f3398f125" // (String) только для ссылок, hash директории
29 // в который находиться файл, на который
30 // указывает ссылка
31 },
32 {
33 // ...
34 }
35 ],
36 "tree" : { // (Object) Дерево директорий. Не обязательный параметр, только если был передан аргумент "tree"
37 "name" : "Home", // (String) Имя директории
38 "hash" : "b4473c8c08d1d499ecd7112f3398f125", // (String) hash
39 "read" : true, // (Boolean) право на чтение
40 "write" : true, // (Boolean) право на запись
41 "dirs" : [ // (Array) (of Objects) массив дочерних директории
42 {
43 "name" : "test",
44 "hash" : "ac4b61565950a73395c871f9c3fc7362",
45 "read" : true,
46 "write" : true,
47 "dirs" : [
48 {
49 // ...
50 },
51 {
52 // ...
53 }
54 ]
55 }
56 }
57 }
Внимание! Если передан некорректный аргумент target, возвращает контент корневой директории (cdc, cdw) и сообщение об ошибке (error).
2. Открытие файла (вывод содержимого в браузер).
Аргументы:- cmd : open
- target : hash пути файла
- current : hash пути к директории, где находится файл
Ответ:
Файл выводится в браузер с соответствующими заголовками.
mkdir¶
Создать новую директорию.
Аргументы:- cmd : mkdir
- current : hash директории, в которой создаем новую директорию
- name : имя новой директории
Ответ: open с деревом директорий tree и select - hash новой директории
1 {
2 // open
3 "cwd" : {
4 // ...
5 },
6 "cdc" : [
7 // ...
8 ],
9 "tree" : {
10 // ...
11 },
12 "select": "ac4b61565950a73395c871f9c3fc7362" // (String) hash новой директории
13 }
mkfile¶
Создать новый файл.
Аргументы:- cmd : mkfile
- current : hash директории, в которой создаем файл
- name : имя нового файла
Ответ: open и select - hash нового файла
rename¶
Переименование директории/файла
Аргументы:- cmd : rename
- current : hash директории, где файл находится
- target : hash директории/файла для переименования
- name : новое имя директории/файла
Ответ: open (если переименовали директорию, то open возвращается с деревом директорий) и select - hash переименованной директории/файла
upload¶
Загрузка файлов
Аргументы (передаются методом POST):- cmd : upload
- current : hash директории, в которую загружаем файлы
- targets : массив файлов
Ответ:
1. Если ни одного файла не удалось загрузить, возвращаем только
1 {
2 "error" : "Unable to upload files"
3 }
2. Если хотя бы один файл был загружен, ответ open и select. Если не были загружены не все файлы от выведутся сообщения об ошибках error и errorData:
1 {
2 // open
3 "select" : [ "8d331825ebfbe1ddae14d314bf81a712" ], // (Array) массив hash'ей путей загруженных файлов
4 "error" : "Some files was not uploaded", // (String) если не все файлы были загружены
5 "errorData" : { // (Object) инф. о файлах, которые не удалось загрузить
6 "some-file.exe" : "Not allowed file type" // (String) "имя файла": "ошибка"
7 }
8 }
ping¶
Служебная команда, необходима для исправления бага Safari при загрузке файлов http://www.webmasterworld.com/macintosh_webmaster/3300569.htm
Аргументы:- cmd : ping
Ответ: отсылает пустую страницу с заголовком Connection: close
paste¶
Копирует или перемещает директории/файлы
Аргументы:- cmd : paste
- src : hash директории, из которой перемещаем/копируем файлы
- dst : hash директории, в которую перемещаем/копируем файлы
- targets : массив hash'ей копируемых директорий/файлов
- cut : 1 если файлы перемещаются, аргумент отсутствует если файлы копируются
Ответ:
Если копирование/перемещение прошло успешно, возвращает open с деревом директорий, если нет, то к ответу добавляются сообдения об ошибках error и errorData
Внимание! Команда должна прекращать копирование при первой же ошибке. Не допускается перезапись файлов/директорий с одинаковыми именами.
rm¶
Удаление файлов и рекурсивное удаление директорий
Аргументы:- cmd : rm
- current : hash директории, из которой удалем файлы
- targets : массив hash'ей удаляемых директорий/файлов
Ответ: open с деревом директорий, при ошибках error и errorData.
duplicate¶
Создает копию директории/файла. Имя копии формируется следующим образом: базовое_имя_файла copy+порядковый номер.расширение (если есть)
Аргументы:- cmd : duplicate
- current : hash директории, в которой создаем дубликат
- target : hash директории/файла, для которого создаем дубликат
Ответ: open (если скопировали директорию, то open возвращается с деревом директорий), select - hash пути дубликата.
read¶
Возвращает содержимое текстового файла.
Аргументы:- cmd : edit
- current : hash директории, в которой читаем файл
- target : hash файла
Ответ: content - содержимое текстового файла
1 {
2 "content": "Hello world!" // (String) содержимое текстового фала
3 }
edit¶
Сохраняет полученный текст в файл.
Аргументы (передаются методом POST):- cmd : edit
- current : hash директории, в которой сохраняется файл
- target : hash файла
- content : новое содержимое файла
Ответ: file - объект, аналогичный описывающему файл в секции cdc команды open
1 {
2 "file" : {
3 "name" : "README.txt",
4 "hash" : "8d331825ebfbe1ddae14d314bf81a712",
5 "url" : "http://localhost:8001/~troex/git/elfinder/files/wiki/README.txt",
6 "date" : "Today 14:25",
7 "mime" : "text/plain",
8 "size" : 1171,
9 "read" : true,
10 "write" : true,
11 "rm" : true
12 }
13 }
extract¶
Распаковывает архив.
Аргументы:- cmd : extract
- current : hash директории, в которой находится файл
- target : hash файла архива
Ответ: open с деревом директорий
archive¶
Упаковывает директории/файлы в архив.
Аргументы:- cmd : archive
- type : mime-тип создаваемого архива
- current : hash директории, в которой находятся добавляемые в архив директории/файлы
- targets : массив хэшей директорий/файлов
Ответ: open, select - hash нового архива
tmb¶
Фоновая команда. Создает миниатюрки для картинок, не имеющих их. Кол-во создаваемых за раз миниатюрок, указывается в конфиге коннектора опцией tmbAtOnce. По умолчанию - 5.
Аргументы:- cmd : tmb
- current : hash пути к директории, в которой создаем миниатюрки
Ответ:
1 {
2 "current": "b4473c8c08d1d499ecd7112f3398f125", // (String) hash пути к директории, в которой были созданы миниатюрки
3 "images" : { // (Object)
4 "a696323d7fd86513754004ba8bc12967": // (String) hash пути файла
5 "http://localhost:8001/~troex/git/elfinder/files/.tmb/a696323d7fd86513754004ba8bc12967.png"
6 // (String) URL миниатюрки
7 },
8 "tmb": true // (Boolean) возвращает true если ещё остались картинки для которых не были созданы миниатюрки,
9 // иначе параметр отсутствует
10 }
resize¶
Изменение размера изображения.
Аргументы:- cmd : resize
- current : hash директории, в которой находится файл
- target : hash пути изображения
- width : новая ширина изображения
- height : новая высота изображения
Ответ: open, select - hash пути изображения
