Плагин Update.

Цель документа: описание плагина Update.
Тип документа: руководство разработчика
Составили: Савенко Д.В., Тютюньков В. Е.
Дата: 07.07.2005
Последнее обновление: 19.07.2005
Версия: 1.4

Общее описание.

Update Plug-in — плагин, предназначенный для оповещения пользователя о наличии обновлений ПО на сервере компании. Плагин предоставляет клиентам информацию о доступных обновлениях и возможность скачать эти обновления (предусмотрены два варианта: а) плагин возвращает URL, по которому можно скачать обновление; б) плагин непосредственно передает обновление через TCP-соединение; оба варианта опциональные, можно отключить один из них или оба, таким образом дав пользователю только возможность следить за обновлениями, но не качать их). Также плагин предоставляет систему аутентификации пользователей, позволяющую в зависимости от прав пользователя давать ему различные возможности для проверки и закачки обновлений. 

Описание серверной части плагина.

Серверная часть Update-плагина должна включать не только реализации стандартных интерфейсов, необходимые для подключения плагина к серверу. Также плагин требует реализации интерфейса проверки пользовательских данных. Это нужно, чтобы производитель мог легко встроить в плагин свою собственную систему аутентификации пользователя. Для этого производитель должен реализовать интерфейс следующего вида:

interface IUserAuthorize {
  String authorize(String productID, String username, String password);
}

Функция authorize() возвращает модификатор доступа, определяющий права пользователя. Модификаторы доступа задаются в конфигурационном файле (см. ниже) администратором сервера, однако есть один заданный модификатор, доступный всегда: “denied” — пользователь отклонен. Если authorize() возвращает этот модификатор, соединения с пользователем обрывается с сообщением об ошибке 
- 09 Access denied 
Другие модификаторы доступа могут быть описаны в конфигурационном файле. Если функция возвратила модификатор, который не описан в конфигурационном файле, то он будет обрабатываться так же, как модификатор “denied”.
Конфигурирование плагина. 

Конфигурация плагина имеет примерно следующий вид:

authorizer AuthorizeClassName;
name “Server name”;
<product “Product_name_1”>
	<access “Access_Modifier_1”>
		access_granted On;

	<update update_1_internal_number>
			version “Version”;
			url “ftp://microsoft.com/download/word”;
		file “../updates/word.zip”;
		info “Первая строка комментария”
			“Вторая строка комментария”
			“и еще строка комментария”;
	</update>
		. . . 
	<update update_K_internal_number>
			version “Version”;
			url “http://microsoft.com/old_ver/word”;
		</update>
	</access>
	. . .
	<access “Access_Modifier_N>
		. . . 
	</access>
</product>
. . .
<product “Product_name_M”>
	. . .
</product>

Описание полей:

authorizer <classname>  
Устанавливает имя класса, который будет использоваться для авторизации пользователя.

name <server_name>
Задает имя сервера. Параметр опциональный и по умолчанию равен “Eskimo Update Plugin, protocol <protocol_version>”, где protocol_version — целое положительное число, указывающее номер самой последней версии протокола, поддерживаемой плагином. Пока это 1, и строка выглядит так: “Eskimo Update Plugin, protocol 1”.

<product “product_name”>
Контейнерный тег, описывающий конфигурацию плагина для определенного продукта. Внутри этого тега должен быть набор тегов <access>

<access access_scheme_name>
Этот тег находится внутри тега <product> и задает определенную схему доступа. Access_scheme_name должен совпадать с одним из тех значений, что возвращает функция authorize(). Внутри этого тега должен быть параметр access_granted, а также может находиться несколько  тегов <update>.

access_granted On/Off
Параметр находится внутри тега <access> и определяет, дается ли доступ к обновлениям. Если access_granted = Off, то соединение закрывается с ошибкой
- 09 Access denied

<update update_internal_number>
Контейнерный тег, который должен находиться внутри тега <access>. Описывает конфигурацию определенного апдейта. Update_internal_number — версия обновления, целое положительное число либо набор целых положительных чисел, разделенных точками. Внутри этого тега должны быть параметры version, url и file, а также может быть info.

version <version_name>
Этот параметр находится внутри тега <update> и содержит внешнее имя версии апдейта, доступное пользователю (любая строка символов, записанная по правилам конфигурационного файла). Например, update_internal_number = 9.0.6926, а version_name = “Microsoft Word 2000 SP-3”. 

url <URL_for_download>
Этот параметр находится внутри тега <update> и  описывает URL, откуда можно закачать обновление. Если этот параметр опущен, то это означает, что команда retr_url (см. ниже, команда получения URL, с которого можно загрузить обновление) запрещена для данного обновления в данной схеме доступа. 

file <file_for_transfer>
Этот параметр находится внутри тега <update> и описывает файл с обновлением, который будет передан по сети. Если этот параметр опущен, то это означает, что команда retr_file (см. ниже, команда получения обновления по TCP-соединению) запрещена для данного обновления в данной схеме доступа. 

info <comment_strings>
Необязательный параметр, который определяет произвольный многострочный комментарий к версии продукта. Если он определен, то он должен находиться внутри тега <update>. comment_strings — это список из произвольного числа строк, не превосходящих 1000 символов каждая. Строки оформляются по общим правилам конфигурационных файлов (см. списковый формат в описании конфигурационных файлов).

Описание клиентских библиотек.

В стандартную поставку плагина планируется включить клиентские библиотеки для Java и С++. Они будут представлять собой библиотеки классов со следующим списком возможностей: 
1. Работа с номерами версий в формате несколько чисел через точку (сравнение версий и т.д.)
2. Оболочка, скрывающая от пользователя особенности сетевого протокола и позволяющая прозрачно для пользователя переходить на более новые версии протокола. 

Сетевой протокол плагина. 

Общение с сервером происходит в режиме диалога. Клиент передает определенные текстовые команды, сервер на них отвечает. Ответ сервера всегда начинается либо с символа +, что означает, что предыдущая команда прошла нормально, и далее идет ответ на нее, либо с символа -, что означает, что при обработке предыдущей команды произошла ошибка, код и описание которой идут следом за знаком -.

Определения

Параметр — строка символов любой длины, не содержащая перевода строки. Если строка не содержит специальных символов (пробел, табуляция, кавычка, \), то она может писаться без кавычек. Если строка содержит специальные символы, то она должна обрамляться кавычками. Специальные символы пробел и табуляция не требуют ничего кроме заключения строки в кавычки, другие специальные символы (кавычка и \) должны находиться в строке сразу после символа \. 

Версия — параметр длиной не более 20 символов, представляющий собой либо целое положительное число, либо набор целых положительных чисел, разделенных точками. Пример: 9.0.6926.

Расширенная версия — параметр длиной не более 256 символов. В свободной форме описывает версию продукта. Например: “Microsoft Word 2000 SP-3”

Ошибка — строка, первые 2 символа которой содержат численный код ошибка, дальше идет свободное описание ошибки длиной не более 256 символов.

Все команды клиента и ответы сервера обязательно заканчиваются символом перевода каретки CR (\n).

В случае неправильной команды или неправильных операндов сервер возвращает строку 
- 01 Bad command
Если неизвестно, что послужило причиной ошибки, то возвращается
- 02 Unrecognized error
Эти ошибки могут быть возвращены любой командой. Другие ошибки описаны в комментариях к каждой команде.

При успешном подключении сервер посылает приветствие в виде строки:
+ OK <server_name>
где server_name — любая строка не длиннее 256 символов, указывающая на имя сервера (задается системным администратором). По умолчанию это “Eskimo Update Plugin, protocol <protocol_version>”. где protocol_version — целое положительное число, указывающее номер самой последней версии протокола, поддерживаемой плагином. Пока это 1, и строка выглядит так: “Eskimo Update Plugin, protocol 1”.

Если соединение установлено, но сервер по каким-то причинам не может обрабатывать запросы клиента, он возвращает строку
- Connection dropped
и закрывает соединение.

Команды.

0. Приветствие.
Формат: hello <protocol_version>
Сообщает серверу, с какой версией протокола клиент хочет работать. Protocol_version — целое число, номер версии. Эта команда может быть послана только самой первой командой сессии. Если ее не будет, автоматически будет использоваться самая старая версия протокола. Пока доступна единственная версия под номером 1. 
В случае успеха возвращается ответ «+ OK». 
Может вернуть следующие ошибки:
- 08 Invalid protocol version

1. Авторизация.
Формат: login <productID> <username> <password>
Если работаем с номерами лицензий, то username можно задать licensed, а в password передать номер лицензии. ProductID — это некий текстовый идентификатор продукта, обновления которого хочет посмотреть клиент, так как может быть несколько продуктов и соответственно несколько ветвей обновлений. 
Если авторизация прошла успешно, возвращается строка «+ OK». 
Ошибки, которые могут возникнуть:
- 03 Incorrect username or password
- 04 Incorrect product ID
- 09 Access denied
После ошибки 09 Access denied соединение разрывается.

2. Получить номер самой новой версии.
Формат: newest_version
В случае успеха возвращает строку вида
+ <newest_version_number> <newest_version_name>
newest_version_number — версия продукта.
Newest_version_name — расширенная версия продукта. Обратите внимание, что в данном случае если строка содержит пробелы или иные специальные символы за исключением перевода строки, то она все равно не обрамляется кавычками.
Например:
Client:		 	newest_version
Server: 			+ 9.0.6926 Microsoft Word 2000 SP-3
Ошибки, которые может возвратить команда newest_version.
- 05 Not authorized

3. Получить комментарий к определенной версии.
Формат: version_info [version_number]
Version_number — версия продукта. Если этот параметр не указан, то возвращается информация о самой новой из имеющихся версий. В случае успеха первой строкой идет количество строк информации, которые будут переданы следом:
Client: 	version_info 9.0.6926
Server:	+ 3
Затем идут эти строки (без кавычек, каждая строка не более 256 символов):
Server:	+ Microsoft Word 2000
Server:	+ The foolest text editor over the world
Server:	+ Updates: 2000 new bugs.
Команда может вернуть следующие ошибки:
- 05 Not authorized
- 06 Invalid version

4. Получить список доступных версий.
Формат: version_list [end_version]
Если задан параметр end_version (версия), возвращает список доступных для обновления версий, которые новее, чем end_version. Если этот параметр не задан, возвращает список всех доступных версий, начиная с самой первой. В случае успеха список возвращается в следующем формате. Первой строкой идет количество строк, которые будут поданы следом. Пример:
Client: 	version_list 9.0.6899
Server:	+ 3
Далее идут строки, описывающие версии в следующем формате:
+ <version_number> <version_name>
Где version_number — версия, version_name — расширенная версия. Обратите внимание, что в данном случае если строка расширенной версии содержит пробелы или иные специальные символы за исключением перевода строки, то она все равно не обрамляется кавычками.
Пример:
Server:	+ 9.0.6926 Microsoft Word 2000 SP-3
Server:	+ 9.0.6920 Microsoft Word 2000 notSP :)
Server:	+ 9.0.6900 Microsoft Word 2000
Обратите внимание, что сама 9.0.6899 не выводится. Более того, такой версии может вообще не существовать, главное, чтобы номер версии был задан синтаксически корректно. Также гарантируется, что версии будут выдаваться в убывающем порядке, то есть первой будет идти самая новая, потом старше и т.д.
Никаких особых ошибок, кроме общих, не возвращает. 

5. Получение обновления в виде URL.
Формат: retr_url [version_number]
version_number — версия.
Если указан номер версии, возвращает URL, по которому можно скачать обновление для этой версии. Если же номер опущен, возвращает URL обновления для самой новой версии. 
Ссылка возвращается в два этапа: сначала сервер отправляет размер URL: в байтах, а потом уже саму ссылку. Например:
Client: 	retr_url 9.0.6926
Server:	+ 50
Server:	+ http://linux.org/windows/download.php?ver=9.0.6926
Может вернуть следующие ошибки:
- 06 Invalid version
- 07 Command forbidden
Примечание: данная команда может быть запрещена администратором сервера. В этом случае возвращается ошибка с кодом 07 Command forbidden.

6. Получение обновления в виде файла.
Формат: retr_file [version_number]
version_number — версия.
Если указан номер версии, возвращает файл, соответствующий данной версии. Если версия не указана, возвращает файл, соответствующий самой новой версии. Файл возвращается следующим образом. Сначала возвращается строка с размером файла в байтах, который будет передан следом. Следом идет сам файл в двоичном виде без какой-либо дополнительной или оформительской информации. Пример:
Client:	retr_file 9.0.6926
Server:	+ 102400
Server:	{файл в байтовом представлении (102400 байт)}
Может вернуть следующие ошибки:
- 06 Invalid version
- 07 Command forbidden
Примечание: данная команда может быть запрещена администратором сервера. В этом случае возвращается ошибка с кодом 07 Command forbidden.

7. Получение размера обновления.
Формат: version_size [version_number]
version_number — версия.
Возвращает размер определенной версии или размер самой новой версии, если параметр version_number не указан. Размер возвращается в байтах. Пример:
Client: 	version_size 9.0.6926
Server:	+ 102400
Может вернуть следующие ошибки:
- 06 Invalid version
- 07 Command forbidden
Последняя ошибка возвращается, если запрещена команда retr_file.

8. Отключение.
Формат: logout
Сервер не посылает ответ на эту команду, а просто закрывает соединение.