artmickiewicz / xmbot Goto Github PK

XMBOT - eXtensible Modular Bot || eXtensible Messaging Bot (от XMPP)

Бот предназначен для работы в комнатах конференций протокола Jabber.
Поддерживаются модули, написанные на C. При этом, например посредством
модуля tcl.so, можно выполнять tcl скрипты. Возможно создание модулей
для других скриптовых языков. Без дополнительных модулей бот обрабаты-
вает только команду !xmbot, в ответ на которую выводить информацию о
своём текущем состоянии. Такую как номер версии и список подгруженых
модулей.

	1. ПАРАМЕТРЫ КОМАНДНОЙ СТРОКИ
	
-c 	Указывает файл конфигурации. Если файл не указан - ищется
	xmbot.xml в текущей директории.
-p	Ввод конфигурации в интерактивном режиме. Не используется
	с параметром -c.
-n	Предотвратить уход в background после запуска.

	2. ФАЙЛ КОНФИГУРАЦИИ
	
В файле xmbot.xml.example привидены все возможные параметры
конфигурации. Однако опции модулей могут быть любыми, поэтому модули
документируются отдельно. Параметри, такие как "user", "nick",
"room", будут перекодированы из базовой кодировки в UTF-8.

*	Секция <client></client>
	Описывает необходимую информацию для подключения к серверу и
	захода на канал.
	<host></host>	IP адрес или имя хоста, которое резолвится в
			IP адрес. Этот параметр является обязательным.
	<port></port>	Порт для подключения. Если не указан -
			используется 5222.
<hostname></hostname>	Hostname конкретного Jabber сервера.
			Если не указан - приравнивается к параметру
			<host></host>.
	<user></user>	Имя пользователя. Указать обязательно.
<passowrd></password>	Пароль. Указать обязательно.

**	Подсекция <muc></muc>
	Параметры для захода на канал.
	<room></room>	Комната. Указать обязательно.
    <domain></domain>	Указать, если комната не пренадлежит
    			первичному серверу. "domain" должен быть равен
			домену JID-а.
	<nick></nick>	Ник бота. Если не указан - равен параметру
			<user></user>
<password></password>	Пароль, в случае если ник зарегистрирован.

*	Секция <modules></modules>
	Вся информация о модулях и их параметрах.

**	Подсекция <load file=""></load>
	Основная инструкция. Указывает подгрузить модуль из файла
	"file". Подразумеваются файлы вида shared object, с
	расширением ".so".
<option name="" value=""/>	Параметры для модуля, если такие есть.
				"name" - имя параметра, "value" - значение
			параметра.

*	Секция <common></common>
	Секция разных настроек.
<encoding></encoding>	Устанавливает кодировку, из которой, при
			необходимости, буду перекодироватся данные
			в UTF-8 для передачи на сервер. Также можно
			производить обратные преобразования.

	ДОПОЛНИТЕЛЬНАЯ ИНФОРМАЦИЯ:

	Есть некоторые переменные времени, которые можно использовать
	в частности для задания имени файла лога, а также
	для других случаев. Вот так например может выглядеть
	имя лог-файла: %month.%day.linux-talks.log
	Доступны переменные:
		%year, %month, %day, %hour, %minute, %second

	Для префикса в случае "msg" лога можно дополнительно
	использовать %nick и %room.

	3. НАПИСАНИЕ МОДУЛЕЙ

	Модули по сути являются обработчиками событий, которые может
	перехватывать бот. Писать модули можно как угодно и про что
	угодно ;) . Однако есть некоторые
	
	ТРЕБОВАНИЯ:

1)	Строка #include "modlib.h"
	modlib.h описывает константы типов event_type,
	тип event_hdl, который является (*)(JID *, void *), тип
	OptVal, тип JID, а также прототипы необходимых функций.
	Файл modlib.h находится в папке src/modules дистрибутива
	программы.
2)	Наличие функции Register_Module(OptVal *optval, ssize_t pairs);
	Функция выполняется сразу после подключения модуля базовой
	программой. Опции, указанные в конфигурационном файле,
	передаются в структуре OptVal.
3)	Вызовы внешней функции
	Register_Handler(char event_type, event_hdl);
	Эти вызовы должны находится внутри функции Register_Module.
	У каждого типа события есть свой конвейер в базовой программе.
	Модули публикуют свои обработчики внутри этого конвейера в
	порядке обявления модуле в конфигурационном файле.
	Этим и занимается функция Register_Handler.
4)	Компиляция в формате shared object.
5)*	Каждому обработчику вторым параметром будут передаватся
	данные определённого типа, соответствующего типу события.
	Например для события MSG_EVENT это XMPP_Msg.

	ДОПОЛНИТЕЛЬНАЯ ИНФОРМАЦИЯ:

	Зачем нужны модули, если они не могут постить ответы на
	события в чат? Ну можно конечно представить ведение какого-то
	сверхсекретного лога, с рассылкой по почте и прочую дребедень.
	Но чтобы писать ответ в чат - нужно знать некоторые
	дополнительные функции. Также бывает нужно отправлять
	различные запросы. Или менять текущее состояние (читай
	presence). Ниже приведён перечень как раз таких функций.
	Все они описаны в modlib.h.

*	Отправка сообщения (message):
	void XMPP_Send_Msg(JID *jid, char *to, char *type,
				char *message, char recode_flag);
	В качестве параметров указывается jid(который передаётся
	параметром каждому обработчику), получатель, само сообщение
	и recode_flag. Если recode_flag установлен(равен 1), будет
	выполнена перекодировка в UTF-8 из базовой, указанной
	в конфигурационном файле. В принципе модули могут сами
	менять эту кодировку, изменяя значение глобальной переменной
	char *src_encoding, но желательно чтобы они вернули её
	первоначальное значение после использования.
	
	4. МОДУЛЬ tcl.so
	5. МОДУЛЬ sulci.so