gloox  0.9.9.12
gloox API Documentation

Contents

Introduction
Event Handlers
Components
Clients
Blocking vs. Non-blocking Connections
Roster Management
Privacy Lists
Authentication
Sending and Receiving of Chat Messages
Protocol Enhancements (XEPs)
File Transfer
HTTP and SOCKS5 Proxy support

Introduction

The design of gloox follows the so-called observer pattern, which basically means that everything is event-driven. There are two ways you can connect to the Jabber/XMPP network using gloox, either as client or as component. A third way, as server, is not supported by gloox, even though it might be possible to get something going.

Note
Section 11.5 of the XMPP specification (RFC 3290) requires that only UTF-8 is used as encoding for any traffic sent over the wire. Since gloox cannot know which encoding is used in any given input, it is a requirement that any input to gloox is valid UTF-8.

Event Handlers

The most important tools of gloox are the event handlers. Currently, there exist 4 handlers for the basic protocol as defined in the RFCs, as well as numerous handlers for events generated by the included XEP-implementations and for additional functionality. Additionally, a log handler, a generic tag handler and a handler for connection events are available.

Basically these handlers are virtual interfaces from which you derive a class and implement a few virtual functions. Then you register such an object with the respective protocol implementation. A short example:

class MyClass : public PresenceHandler
{
public:
// reimplemented from PresenceHandler
virtual void handlePresence( Stanza *stanza );
[...]
};
void MyClass::handlePresence( Stanza *stanza )
{
// extract further information from the stanza
}

Somewhere else you do something like this:

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

Now, everytime a presence stanza (not subscription stanza) is received, handlePresence() is called with the current stanza as argument. You can then use the extensive getters of the Stanza class to extract stanza data.

This works similar for all the other event handlers. Another example, this time using the connection event handler (class ConnectionListener ):

class MyClass : public ConnectionListener
{
public:
virtual void onConnect();
virtual bool onTLSConnect( ... );
};
void MyClass::onConnect()
{
// do something when the connection is established
}
bool MyClass::onTLSConnect( const CertInfo& info )
{
// decide whether you trust the certificate, examine the CertInfo structure
return true; // if you trust it, otherwise return false
}
Note
The ConnectionListener interface is a peculiarity. You MUST re-implement ConnectionListener::onTLSConnect() if you want to be able to connect successfully to TLS/SSL enabled servers. Even though gloox tries to verify the server's certificate it does not automatically trust a server. The client's programmer and/or user have to decide whether to trust a server or not. This trust is expressed by the return value of onTLSConnect(). False means you don't trust the server/certificate and as a consequence the connection is dropped immediately.

Components

A component in the Jabber/XMPP network is an add-on to a server which runs externally to the actual server software, but can have similar privileges. Components use a protocol described in XEP-0114 to connect and authenticate to a server.

The Component class supports this protocol and can be used to create a new Jabber component. It's as simple as:

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

Clients

A client can be an end-user's chat client, a bot, or a similar entity not tied to a particular server. The Client class implements the necessary functionality to connect to an XMPP server. Usage is, again, pretty simple:

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()
{
// connection established, auth done (see API docs for exceptions)
}
bool MyClass::onTLSConnect( const CertInfo& info )
{
// examine certificate info
}
void MyClass::handlePresence( Stanza *stanza )
{
// presence info
}
Note
gloox does not (and will not) support the style of connection which is usually used on port 5223, i.e. SSL encryption before any XML is sent, because it's a legacy method and not standard XMPP.
Client::connect() by default blocks until the connection ends (either Client::disconnect() is called or the server closes the connection).

Blocking vs. Non-blocking Connections

For some kind of bots a blocking connection (the default behaviour) is ideal. All the bot does is react to events coming from the server. However, for end user clients or anything with a GUI this is far from perfect.

In these cases non-blocking connections can be used. If ClientBase::connect( false ) is called, the function returnes immediately after the connection has been established. It is then the resposibility of the programmer to initiate receiving of data from the socket.

The easiest way is to call ClientBase::recv() periodically with the desired timeout (in microseconds) as parameter. The default value of -1 means the call blocks until any data was received, which is then parsed automatically.

As an alternative to periodic polling you can get a hold of the raw file descriptor used for the connection. You can then use select() on it and use ClientBase::recv() when select indicates that data is available. You should not recv() any data from the file descriptor directly as there is no way to feed that back into the parser.

To get the file descriptor you'll need to set a connection class (e.g. an instance of ConnectionTCPClient ) manually, like so:

Client* client = new Client( ... );
ConnectionTCPClient* conn = new ConnectionTCPClient( client, client->logInstance(), server, port );
client->setConnectionImpl( conn );
client->connect( false );
int sock = conn->socket();
[...]

It would also be possible to fetch the fd like this:

Client* client = new Client( ... );
client->connect( false );
int sock = dynamic_cast<ConnectionTCPClient*>( client->connectionImpl() )->socket();
[...]
Note
This has changed in 0.9. ClientBase::fileDescriptor() is no longer available.

Roster Management

Among others, RFC 3921 defines the protocol to manage one's contact list (roster). In gloox, the RosterManager class implements this functionality. A few easy-to-use functions are available to subscribe to or unsubscribe from the presence of remote entities. It is also possible to add a contact to a roster without actually subscribing to the contacts presence. Additionally, the interface RosterListener offers many callbacks for various roster-related events.

If you create a Client object as shown above, you also get a RosterManager for free. Client::rosterManager() returns a pointer to the object.

Privacy Lists

Also defined in RFC 3921: Privacy Lists. A Privacy List can be used to explicitely block or allow sending of stanzas from and to contacts, respectively. You can define rules based on JID, stanza type, etc. Needless to say that gloox implements Privacy Lists as well. ;) The PrivacyManager class and the PrivacyListHandler virtual interface allow for full flexibility in Privacy List handling.

PrivacyManager *p = new PrivacyManager( ... );
[...]
PrivacyListHandler::PrivacyList list;
PrivacyItem item( PrivacyItem::TypeJid, PrivacyItem::ActionDeny,
PrivacyItem::PacketMessage, "me@there.com" );
list.push_back( item );
PrivacyItem item2( PrivacyItem::TypeJid, PrivacyItem::ActionAllow,
PrivacyItem::PacketIq, "me@example.org" );
list.push_back( item2 );
p->store( "myList", list );

Authentication

gloox supports old-style IQ-based authentication defined in XEP-0078 as well as several SASL mechanisms. See the documentation of the Client class for more information.

Sending and Receiving of Chat Messages

For Messaging it is recommended to use the MessageSession interface. It handles sending and receiving of messages as well as message events and chat states (such as typing notifications, etc.). See MessageSession for more details.

Protocol Enhancements (XEPs)

The XMPP Standards Foundation has published a number of extensions to the core protocols, called XMPP Extension Protocols (XEPs). A couple of these XEPs are implemented in gloox:

File Transfer

For file transfer, gloox implements XEP-0095 (Stream Initiation) as well XEP-0096 (File Transfer) for the signalling, and XEP-0065 (SOCKS5 Bytestreams) for the transport. See SIProfileFT .

Additionally, there is an implementation of XEP-0047 (In-Band Bytestreams) which is currently not integrated into the signalling of XEPs 0095 and 0096. Therefore, this protocol is probably not suited for offering file transfer to end-users. See InBandBytestreamManager .

HTTP and SOCKS5 Proxy support

gloox is capable of traversing HTTP as well as SOCKS5 proxies, even chained. See ConnectionHTTPProxy and ConnectionSOCKS5Proxy .

Generated on Thu Jun 27 2013 13:05:49 for gloox by   doxygen 1.8.1.2