gloox.h

Jabber code library, developed with c

/*
  Copyright (c) 2005-2008 by Jakob Schroeter <[e-mail]>
  This file is part of the gloox library. http://camaya.net/gloox

  This software is distributed under a license. The full license
  agreement can be found in the file LICENSE in this distribution.
  This software may not be copied, modified, sold or distributed
  other than expressed in the named license agreement.

  This software is distributed without any warranty.
*/

/*! @mainpage gloox API Documentation
 *
 * @section contents Contents
 * @ref intro_sec <br>
 * @ref handlers_sec <br>
 * @ref comp_sec <br>
 * @ref client_sec <br>
 * @ref block_conn_sec <br>
 * @ref roster_sec <br>
 * @ref privacy_sec <br>
 * @ref auth_sec <br>
 * @ref msg_sec <br>
 * @ref xeps_sec <br>
 * @ref filetransfer_sec <br>
 * @ref proxy_sec <br>
 * <br>
 *
 * @section intro_sec 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.
 *
 * @section handlers_sec 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:
 * @code
 * class MyClass : public PresenceHandler
 * {
 *   public:
 *     // reimplemented from PresenceHandler
 *     virtual void handlePresence( Stanza *stanza );
 *
 *   [...]
 * };
 *
 * void MyClass::handlePresence( Stanza *stanza )
 * {
 *   // extract further information from the stanza
 * }
 * @endcode
 *
 * Somewhere else you do something like this:
 * @code
 * OtherClass::doSomething()
 * {
 *   Client *client = new Client( ... );
 *   [...]
 *   MyClass *handler = new MyClass( ... );
 *   client->registerPresenceHandler( handler );
 * }
 * @endcode
 *
 * 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 @link gloox::ConnectionListener
 * ConnectionListener @endlink):
 * @code
 * 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
 * }
 * @endcode
 *
 * @note The ConnectionListener interface is a peculiarity. You MUST re-implement
 * @link gloox::ConnectionListener::onTLSConnect() ConnectionListener::onTLSConnect() @endlink 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(). @b False means you don't trust the server/certificate and as a consequence
 * the connection is dropped immediately.
 *
 * @section comp_sec 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 @link gloox::Component Component @endlink class supports this protocol and can be used to create
 * a new Jabber component. It's as simple as:
 * @code
 * Component *comp = new Component( ... );
 * comp->connect();
 * @endcode
 *
 * @section client_sec Clients
 *
 * A client can be an end-user's chat client, a bot, or a similar entity not tied to a particular
 * server. The @link gloox::Client Client @endlink class implements the necessary functionality to
 * connect to an XMPP server. Usage is, again, pretty simple:
 * @code
 * 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
 * }
 * @endcode
 *
 * @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.
 *
 * @note @link gloox::Client::connect() Client::connect() @endlink by default blocks until the
 * connection ends (either @link gloox::Client::disconnect() Client::disconnect() @endlink is called
 * or the server closes the connection).
 *
 * @section block_conn_sec 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
 * @link gloox::ClientBase::connect() ClientBase::connect( false ) @endlink 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 @link gloox::ClientBase::recv() ClientBase::recv() @endlink
 * 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
 * @link gloox::ClientBase::recv() ClientBase::recv() @endlink when select indicates that data is
 * available. You should @b 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
 * @link gloox::ConnectionTCPClient ConnectionTCPClient @endlink) manually, like so:
 *
 * @code
 * Client* client = new Client( ... );
 * ConnectionTCPClient* conn = new ConnectionTCPClient( client, client->logInstance(), server, port );
 * client->setConnectionImpl( conn );
 *
 * client->connect( false );
 * int sock = conn->socket();
 *
 * [...]
 * @endcode
 *
 * It would also be possible to fetch the fd like this:
 *
 * @code
 * Client* client = new Client( ... );
 * client->connect( false );
 * int sock = dynamic_cast<ConnectionTCPClient*>( client->connectionImpl() )->socket();
 *
 * [...]
 * @endcode
 *
 *
 * @note This has changed in 0.9. ClientBase::fileDescriptor() is no longer available.
 *
 * @section roster_sec Roster Management
 *
 * Among others, RFC 3921 defines the protocol to manage one's contact list (roster). In gloox, the
 * @link gloox::RosterManager RosterManager @endlink 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 @link gloox::RosterListener RosterListener @endlink
 * offers many callbacks for various roster-related events.
 *
 * If you create a Client object as shown above, you also get a RosterManager for free.
 * @link gloox::Client::rosterManager() Client::rosterManager() @endlink returns a pointer to the
 * object.
 *
 * @section privacy_sec 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
 * @link gloox::PrivacyManager PrivacyManager @endlink class and the
 * @link gloox::PrivacyListHandler PrivacyListHandler @endlink virtual interface allow for full
 * flexibility in Privacy List handling.
 *
 * @code
 * PrivacyManager *p = new PrivacyManager( ... );
 * [...]
 * PrivacyListHandler::PrivacyList list;
 * PrivacyItem item( PrivacyItem::TypeJid, PrivacyItem::ActionDeny,
 *                   PrivacyItem::PacketMessage, "[e-mail]" );
 * list.push_back( item );
 *
 * PrivacyItem item2( PrivacyItem::TypeJid, PrivacyItem::ActionAllow,
 *                    PrivacyItem::PacketIq, "[e-mail]" );
 * list.push_back( item2 );
 *
 * p->store( "myList", list );
 * @endcode
 *
 * @section auth_sec Authentication
 *
 * gloox supports old-style IQ-based authentication defined in XEP-0078 as well as several SASL mechanisms.
 * See the documentation of the @link gloox::Client Client @endlink class for more information.
 *
 * @section msg_sec 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
 * @link gloox::MessageSession MessageSession @endlink for more details.
 *
 * @section xeps_sec 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:
 *
 * @li XEP-0004 @link gloox::DataForm Data Forms @endlink
 * @li XEP-0012 @link gloox::LastActivity  Last Activity @endlink
 * @li XEP-0013 @link gloox::FlexibleOffline Flexible Offline Message Retrieval @endlink
 * @li XEP-0022 Message Events (see @link gloox::MessageSession MessageSession @endlink for examples)
 * @li XEP-0027 Current Jabber OpenPGP Usage (see @link gloox::GPGSigned GPGSigned @endlink
 * and @link gloox::GPGEncrypted GPGEncrypted @endlink)
 * @li XEP-0030 @link gloox::Disco Service Discovery @endlink
 * @li XEP-0045 @link gloox::MUCRoom Multi-User Chat @endlink
 * @li XEP-0047 @link gloox::InBandBytestreamManager In-Band Bytestreams @endlink
 * @li XEP-0048 @link gloox::BookmarkStorage Bookmark Storage @endlink
 * @li XEP-0049 @link gloox::PrivateXML Private XML Storage @endlink
 * @li XEP-0050 @link gloox::Adhoc Ad-hoc Commands @endlink
 * @li XEP-0054 @link gloox::VCardManager vcard-temp @endlink
 * @li XEP-0065 @link gloox::SOCKS5BytestreamManager SOCKS5 Bytestreams @endlink, used with
 * @ref filetransfer_sec and @ref proxy_sec