gloox: Документация API
(версия библиотеки 1.0)
(черновик перевода / 04.06.2012/ iboxjo.h1.ru)
вернуться на страницу проекта gloox

Содержание


Введение
Обработчики событий (Event Handlers)
Компоненты (Components)
Клиенты (Clients)
Блокируемые подключения против неблокируемых
Управление ростером (списков контактов)
Конфиденциальные списки
Аутентификация
Отправка и получение сообщений чата
Расширения протокола (XEP)
Передача файлов
Поддержка HTTP и SOCKS5 Proxy
Обновление с предыдущих версий

Введение
Дизайн gloox следует так называемым поведенческим шаблонам (observer pattern[wiki]), что по существу означает, что всё управляется событиями. Существует два способа подключения к Jabber/XMPP сети с использованием gloox - в качестве клиента или в качестве компонента. Библиотеку для создания C++ XMPP сервера можно найти на http://camaya.net/glooxd.

Обработчики событий (Event Handlers)
Наиболее важными инструментами gloox являются обработчики событий. В настоящее время существуют четыре обработчика для базового протокола, в соответствии с определением RFC, а так же множество обработчиков для событий генерируемых XEP-реализациями и для целей дополнительной функциональности. Кроме того доступны, обработчик журнала, универсальный обработчик тэгов и обработчик событий подключения.

В основном, это обработчики виртуальных интерфейсов, из которых наследуются классы и реализуются некоторые виртуальные функции. Затем, эти объекты регистрируются с соответствующей реализацией протокола. Вот короткий пример:

class MyClass : public PresenceHandler
 {
   public:
     // переопределяется PresenceHandler
     virtual void handlePresence( const Presence& presence );

   [...]
 };

 void MyClass::handlePresence( const Presence& presence )
 {
   // извлекаем дополнительную информацию из объекта Presence
 }

В другом месте, вы можете сделать нечто подобное:

OtherClass::doSomething()
 {
   Client* client = new Client( ... );
   [...]
   MyClass* handler = new MyClass( ... );
   client->registerPresenceHandler( handler );
 }


Теперь, всякий раз, когда принимается станза представления(presence) (неподписанная станза), вызывается обработчик handlePresence() с текущей станзой в качестве аргумента. Вы можете использовать многочисленные получатели (геттеры) класса Stanza для извлечения данных из станзы (строфы).

Аналогично работают все остальные обработчики событий. Другой пример использует обработчик событий соединения (класс ConnectionListener):

class MyClass : public ConnectionListener
 {
   public:
     virtual void onConnect();

     virtual bool onTLSConnect( ... );
 };

 void MyClass::onConnect()
 {
   // действия выполняемые когда установлено соединение
 }

 bool MyClass::onTLSConnect( const CertInfo& info )
 {
   // исследуя структуру CertInfo принимаем решение о доверии сертификату
   return true; // если доверяем, иначе return false
 }

Примечание:
  Интерфейс ConnectionListener особенный. Вам необходимо повторно реализовать ConnectionListener::onTLSConnect(), если вы хотите получить возможность успешного соединения к серверам с поддержкой TLS/SSL. Хотя gloox пытается проверить сертификат сервера, автоматически он не доверяет серверу. Программист или пользователь клиента, должен принять решение доверять или не доверять серверу. Это доверие выражается в возврате значения onTLSConnect()  false, означает, что вы не доверяете серверу/сертификату, и как следствие соединение немедленно обрывается.
 

Компоненты (Components)
 В сети Jabber/XMPP, компоненты, это дополнения (add-on) к серверу, который работает на внешней стороне серверного ПО, однако может иметь аналогичные полномочия. Компоненты используют протокол описаный в XEP-0114 для соединения и аутентификации на сервере.

 Класс Component поддерживает этот протокол и может использоваться для создания нового компонента Jabber. Это достаточно просто:

Component* comp = new Component( ... );
 comp->connect();

Клиенты (Clients)
 Клиент может быть клиентом чата, ботом или аналогичным лицом не привязанным к конкретному серверу. Класс Client реализует необходимую функциональность для подключения к серверу XMPP. Реализация, так же, достаточно простая:

class MyClass : public ConnectionListener, PresenceHandler
 {
   public:
     void doSomething();

     virtual void handlePresence( ... );

     virtual void onConnect();

     virtual bool onTLSConnect( const CertInfo& info );
 };

 void MyClass::doSomething()
 {
   JID jid( "jid@server/resource" );
   Client* client = new Client( jid, "password" );
   client->registerConnectionListener( this );
   client->registerPresenceHandler( this );
   client->connect();
 }

 void MyClass::onConnect()
 {
   // соединение установлено, аутентификация выполнена (смотри документацию API о исключениях)
 }

 bool MyClass::onTLSConnect( const CertInfo& info )
 {
   // проверяем информацию о сертификате
 }

 void MyClass::handlePresence( Presence* presence )
 {
   // информация о присутствии
 }

Примечание
 Официально, gloox не поддерживает стиль соединения, который обычно использует порт 5223, например SSL шифрование перед любой передачей XML, поскольку это традиционный метод, а не стандартизованный XMPP. Однако, gloox включает класс ConnectionTLS, который позволяет установить такое соединение.

Client::connect() по умолчанию блокируется, пока соединение не завершится (либо вызовом Client::disconnect(), или сам сервер закроет соединение).

Блокируемые подключения против неблокируемых
---