================================================================================ ПРОГРАМНЫЙ ИНТЕРФЕЙС (API) ВНЕШНИХ МОДУЛЕЙ РАСШИРЕНИЯ РЕДАКЦИЯ 0.03 ОТ 25.04.2002 ================================================================================ 1. ВВЕДЕНИЕ Данный документ является описанием програмного интерфейса (API) внешних модулей расширения (plug-ins) для программы JUST. Назначением данного документа является предоставление сторонним разработчикам информации, позволяющей создавать внешние модули расширения для программы JUST. Автор не намерен тратить свое личное время на объяснение дилетантам основ программирования для Win32, поэтому заранее предупреждает, что данный документ не является инструкцией "как сделать модуль для JUST нажатием двух кнопок". Принцип работы интерфейса модулей в программе позволяет создавать модули самого разнообразного назначения и любой сложности. Для гарантии правильного взаимодействия модулей с программой весьма желательно предоставление для анализа тех частей исходного кода модуля, которые используют описываемый в данном документе интерфейс, а так же общее описание тех частей кода, выполнение которых может занять длительное время (например, обращение к базе данных), и описание мер, принятых для обеспечения независимости работы программы от таких действий. Однако, это не является требованием предоставлять для анализа весь исходный код модуля, или тех его частей, которые могут являться коммерческой либо технической тайной. Автор гарантирует, что предоставленная ему информация о работе модуля, вне зависимости от степени её конфиденциальности, не будет предоставлена сторонним лицам. 2. НАЗНАЧЕНИЕ, СТРУКТУРА И ПРИНЦИПЫ РАБОТЫ МОДУЛЕЙ Назначением модулей является экспорт в программу различных функций. Кроме таких функций, модули могут содержать любые необходимые для их работы ресурсы. Модули расширения являются динамическими библиотеками DLL, имеющими расширение JEM (Just Extension Module), и скомпилированными с учётом правил, изложенных ниже. Модуль содержит ресурс в виде таблицы строк определенного вида, где указаны все параметры, необходимые программе для загрузки модуля и работы с ним. Желательно наличие в модуле эмблемы (т.е. значка, пиктограммы) модуля размером 16х16. В таблице строк указываются название модуля длиной не более 32 символов, версия модуля длиной не более 32 символов, возможно так же наличие описания модуля длиной не более 256 символов. При наличии в описании модуля URL их желательно давать в полном виде, например http://www.mypage.com или mailto:mymail@mail.ru. Так как модуль может быть загружен несколькими экземплярами программы, в нём должен быть предусмотрен механизм корректной работы с внутренними данными модуля и с параметрами его настройки. При изменении этих данных работа модуля не должна нарушаться. Параметры настройки желательно сохранять в файле конфигурации модуля, который должен располагаться в той же папке, что и файл модуля. Модули должны располагаться в папке программы MODULES. Если модуль работает с большими объемами данных (например, база данных), рекомендуется создавать или применять (в случае их существования) специализированные внешние программы для обработки этих данных, а модуль создавать как интерфейс взаимодействия (передачи данных) между программами. Все файлы справки модуля должны располагаться в папке HELP. Следует так же тчательно проверять идентичность работы модулей в различных опе- рационных системах и при различных национальных параметрах системы. Нежелательно использовать динамическую линковку необходимых модулю DLL. Настоятельно рекомендуется максимально оптимизировать код модулей, не применять требующих значительного времени для своего выполнения функций, и устанавливать опции компилятора для оптимизации по скорости. 3. ЭКСПОРТИРУЕМЫЕ ФУНКЦИИ МОДУЛЕЙ Функции, экспортируемые модулем в программу, должны быть указаны в таблице описания экспортируемых функций. Количество этих функций не ограничено, однако, в программе общее количество всех функций всех модулей ограничено 10000. В описании функции указывается её название, флаги и номер в модуле. Желательно наличие строки описания назначения функции. Длина названия функции не должна превышать 32 символа, длина описания функции не должна превышать 256 символов. 3.1 ПРИНЦИПЫ РАБОТЫ ФУНКЦИЙ МОДУЛЯ Параметрами функции являются указатели на внутренние структуры данных программы и/или непосредственно сами данные. Число параметров может быть разным для одной и той же функции, в зависимости от места ее вызова. Все функции вызываются как функции С (_сdecl). Вызов функции происходит в потоке (thread) работы самой программы, поэтому для тех функций, работа которых требует значительного времени, следует создавать их собственные отдельные потоки (threads). При необходимости передачи в программу результатов действия таких функций следует воспользоваться механизмами передачи данных между процессами, реализация которых в программе описана в разделе "ВЗАИМОДЕЙСТВИЕ С ВНЕШНИМИ ПРОЦЕССАМИ". 3.2 ТИПЫ ФУНКЦИЙ В МОДУЛЕ Фукнции подразделяются на три типа: - функция инициализации модуля; - добавляемые в меню функции; - функции обработки событий; 3.2.1 ФУНКЦИЯ ИНИЦИАЛИЗАЦИИ МОДУЛЯ Функция инициализации модуля включается в модуль в том случае, если требуется получить из программы данные о ее настройке. Дополнительно модуль может вывести через эту функцию текстовое сообщение, которое будет отображено в стартовом окне программы и записано в лог программы. Функция вызывается непосредственно после загрузки модуля. В модуле может быть только одна такая функция. Допускается изменение функцией некоторых параметров настройки программы. Текстовое сообщение, выводимое модулем через функцию инициализации, не должно быть длинее 255 символов. 3.2.2 ФУНКЦИИ МОДУЛЕЙ, ДОБАВЛЯЕМЫЕ В МЕНЮ Функции модулей могут быть добавлены в следующие меню: - меню настройки в главном окне (функции настройки модуля); - меню средств в главном окне; - меню средств в комнате; - контекстное меню списка комнат в главном окне; - контекстное меню списка пользователей в главном окне; - контекстное меню окна имени пользователя; - контекстное меню окна профайла пользователя; - контекстное меню окна чата в комнате; - контекстное меню списка пользователей в комнате; - контекстное меню окна чата в привате. Функция может быть добавлена в несколько меню, при указании соответствующих флагов в её описании. Исключением являются функции настройки модулей и функции сервисов, добавляемые в меню средств главного окна. 3.2.3 ФУНКЦИИ ОБРАБОТКИ СОБЫТИЙ Функции обработки событий вызываются автоматически после какого-либо события в программе. Функция может обрабатывать несколько событий, в этом случае следует предусмотреть обработку разных типов данных, передаваемых в функцию при разных событиях. Так как реакция на события является наиболее критичной ко времени, необходимо максимально оптимизировать такие функции. Термином "событие" обозначены следующие действия программы: - соединение с сервером; - отсоединение от сервера; - ответ сервера на запрос списка комнат; - ответ сервера на запрос списка пользователей; - открытие окна комнаты; - закрытие окна комнаты; - вход в комнату пользователя; - выход из комнаты пользователя; - вход в приват; - выход из привата; - открытие привата (другим пользователем); - закрытие привата (другим пользователем); - вызов от другого пользователя; - ответ сервера на запрос IP; - изменение пользователем выбранной комнаты; - сообщение от другого пользователя в комнате; - сообщение, посылаемое в комнату; - сообщение другого пользователя в привате; - сообщение, посылаемое в приват; - попытка открытия заблокированного привата (другим пользователем). 4. ВЗАИМОДЕЙСТВИЕ С ВНЕШНИМИ ПРОЦЕССАМИ Модули могут взаимодействовать с любыми внешними процессами с учетом правил, изложенных в разделе 3.1. Для передачи данных от модулей в программу существует специальный интерфейс, позволяющий передавать любой объём любых данных в любое время. 5. ПРОТОКОЛЫ ВТОРОГО УРОВНЯ Расширение сервисных возможностей чата Volano в области взаимодействия клиентов возможно только через протоколы второго уровня, поверх протокола передачи текста (в формате UNICODE). JUST реализует следующую схему использования протоколов второго уровня: - под служебное сообщение протокола второго уровня отводится вся строка; - первым символом в строке служебного сообщения протокола второго уровня должен быть символ #65535 (JUST не отображает такую строку в окне чата, но передает её для обработки модулям); - модуль, обрабатывающий строку служебного сообщения, должен установить первый символ в строке в значение #0 (JUST не обрабатывает далее такую строку). Таким образом, если в JUST нет модулей, обрабатывающих строку протокола второго уровня, это никак не сказывается на работе программы в целом. В целях обеспечения совместимости модулей, использующих для своей работы прото- колы второго уровня, эти протоколы должны быть полностью открыты. 5.1. ИСПОЛЬЗУЕМЫЕ ИМЕНА ПРОТОКОЛОВ Для идентефикации протокола второго уровня предлагается в каждой служебной строке вслед за символом-признаком служебной строки указывать имя протокола из 8 символов. Так как в UNICODE возможно использование весьма большого количества значений для одного символа, число возможных имен протоколов является очень большим. В настоящее время зарезервированы следующие имена протоколов: SENDFILE (UNICODE 0053 0045 004E 0044 0046 0049 004C 0045) - протокол SendFile для передачи файлов через приват