UPGRADING

/**
 * @page upgrading Upgrading from earlier versions
 *
 * This page contains information about upgrading gloox from an earlier version to the current one.
 * It lists the API changes that were made and how to change your code to achieve the same
 * (or better) functionality as with the earlier version.
 *
 * @tableofcontents
 * 
 * @section upgrading_09_10 1. Upgrading from 0.9.x to 1.0
 *
 * Besides the changes detailed below, a major change is that the Stanza class now is an abstract
 * base for more specialized
 * @link gloox::Message Message @endlink, @link gloox::Presence Presence @endlink,
 * @link gloox::IQ IQ @endlink, and @link gloox::Subscription Subscription @endlink classes.
 * Therefore,
 * @link gloox::PresenceHandler PresenceHandler @endlink,
 * @link gloox::MessageHandler MessageHandler @endlink,
 * @link gloox::SubscriptionHandler SubscriptionHandler @endlink, and
 * @link gloox::IqHandler IqHandler @endlink no longer take a Stanza* argument, but receive
 * a pointer to the respective specialized class. Additionally, in a move to get away from
 * unsafe pointers to safer references, these pointer-taking functions have been deprecated
 * (but will continue to be available throughout the 1.0.x cycle).
 * The recommended usage looks as follows:
 *
 * Old code:
 * @code
 * void MyClass::handlePresence( Stanza* stanza )
 * {
 *   // ...
 * }
 * @endcode
 *
 * New code (deprecated):
 * @code
 * void MyClass::handlePresence( Presence* pres )
 * {
 *   // ...
 * }
 * @endcode
 * or
 * New code (recommended):
 * @code
 * void MyClass::handlePresence( const Presence& pres )
 * {
 *   // ...
 * }
 * @endcode
 *
 * @subsection deprecated_10 1.1 Deprecated classes and functions
 *
 * @subsubsection func_MUCRoomHandler_handleMucMessage 1.1.1 MUCRoomHandler::handleMUCMessage( MUCRoom*, string, string, bool, string, bool ),
 *
 * Use @link gloox::MUCRoomHandler::handleMUCMessage( MUCRoom*, const Message&, bool ) handleMUCMessage( MUCRoom*, Message&, bool ) @endlink instead.
 *
 * Due to the newly available StanzaExtensions, some of handleMUCMessage()'s arguments are obsolete:
 * Instead of single values, all of these are included in the new @c msg parameter, which is the
 * full Message stanza:
 *
 * @li the speaker's nick name,
 * @code const std::string nick = msg.from().resource(); @endcode
 * @li the message body,
 * @code const std::string body = msg.body(); @endcode
 * @li whether this message is part of the room history,
 * @code
 * bool history = msg.when() ? true : false;
 * @endcode
 * @li the message's time stamp.
 * @code
 * const DelayedDelivery* dd = msg.when();
 * if( dd )
 *   printf( "message was sent at %s\n", dd->stamp().c_str() );
 * @endcode
 *
 * @subsubsection func_ClientBase_trackID 1.1.2 ClientBase::trackID()
 *
 * The functionality provided by this function really makes sense only for IQ stanzas of type
 * get or set. As a result, there is a new function
 * @link gloox::ClientBase::send( IQ&, IqHandler*, int, bool ) ClientBase::send( IQ&, IqHandler*, int ) @endlink
 * that combines trackID()'s and send()'s functionality.
 *
 * Old code:
 * @code
 * const std::string& id = m_client->getID();
 * Tag* iq = ...
 * iq->addAtrribute( "id", id );
 * ...
 * m_client->trackID( this, id, SomeContext );
 * m_client->send( iq );
 * @endcode
 *
 * New code:
 * @code
 * IQ iq( IQ::Set, recipientJID );
 * ...
 * m_client->send( iq, this, SomeContext );
 * @endcode
 *
 * Further, it is no longer necessary to explicitely add an ID to the IQ (for requests of type
 * 'get' or 'set; 'result' and 'error' IQs need to have the IQ's ID passed they are supposed
 * to answer). send() will take care of this.
 *
 * @subsubsection func_DiscoHandler_handleDiscoInfoResult 1.1.3 DiscoHandler::handleDiscoInfoResult()
 *
 * The function
 * gloox::DiscoHandler::handleDiscoInfoResult()
 * has been removed. Replacement is:
 * @link gloox::DiscoHandler::handleDiscoInfo() DiscoHandler::handleDiscoInfo() @endlink.
 *
 * @subsubsection func_DiscoHandler_handleDiscoItemsResult 1.1.4 DiscoHandler::handleDiscoItemsResult()
 *
 * The function
 * gloox::DiscoHandler::handleDiscoItemsResult()
 * has been removed. Replacement is:
 * @link gloox::DiscoHandler::handleDiscoItems() DiscoHandler::handleDiscoItems() @endlink.
 *
 * @subsubsection func_DiscoHandler_handleDiscoError 1.1.5 DiscoHandler::handleDiscoError()
 *
 * The function
 * gloox::DiscoHandler::handleDiscoError( IQ*, int )
 * has been removed. Replacement is:
 * @link gloox::DiscoHandler::handleDiscoError( const JID&, const Error*, int ) DiscoHandler::handleDiscoError( const JID&, const Error*, int ) @endlink.
 *
 * @subsubsection func_MUCRoom_destroy 1.1.6 MUCRoom::destroy()
 *
 * The default argument now is a const reference to a JID -- defaulting to en empty JID --
 * instead of a pointer to a JID object.
 *
 *
 *
 *
 * @subsection removed_10 1.2 Removed classes and functions
 *
 * @subsubsection class_XDelayedDelivery 1.2.1 XDelayedDelivery
 *
 * The class XDelayedDelivery has been removed as the XSF replaced XEP-0091 with XEP-0203. The class
 * @link gloox::DelayedDelivery DelayedDelivery @endlink covers both XEPs.
 *
 * @subsubsection func_JID_fullJID 1.2.2 JID::fullJID()
 *
 * Use the copy constructor instead. E.g.:
 *
 * Old code:
 * @code
 * JID j( "somejid" );
 * JID copy = j.fullJID();
 * @endcode
 *
 * New code:
 * @code
 * JID j( "somejid" );
 * JID copy( j );
 * @endcode
 *
 * @subsubsection func_JID_empty 1.2.3 JID::empty()
 *
 * This function has been replaced by JID::operator bool(). This has the added benefit of validity
 * checking. E.g.:
 *
 * Old code:
 * @code
 * JID j;
 * // ...
 * if( !j.empty() )
 * {
 *   // do something
 * }
 * @endcode
 *
 * New code:
 * @code
 * JID j;
 * // ...
 * if( j ) // this evaluates to true only if the JID is not empty and if the contained JID
 *         // is in fact valid, i.e. if no prepping operation failed.
 * {
 *   // do something
 * }
 * @endcode
 *
 * @subsubsection func_Tag_empty 1.2.4 Tag::empty()
 *
 * This function has been replaced by Tag::operator bool(). This has the added benefit of validity
 * checking. E.g.:
 *
 * Old code:
 * @code
 * Tag t;
 * // ...
 * if( !t.empty() )
 * {
 *   // do something
 * }
 * @endcode
 * Or:
 * @code
 * Tag* t = new Tag( "foo" );
 * // ...
 * if( !t->empty() )
 * {
 *   // do something
 * }
 * @endcode
 *
 * New code:
 * @code
 * Tag t;
 * // ...
 * if( t )
 * {
 *   // do something
 * }
 * @endcode
 * Or:
 * @code
 * Tag* t = new Tag( "foo" );
 * // ...
 * if( *t )
 * {
 *   // do something
 * }
 * @endcode
 *
 * @subsubsection func_Tag_attributes 1.2.5 Tag::attributes() (non-const)
 *
 * This function has been removed. Use the const version instead. To delete an attribute,
 * use the new @link gloox::Tag::removeAttribute() removeAttribute() @endlink.
 *
 * @subsubsection func_Tag_attributes 1.2.6 Tag::children() (non-const)
 *
 * This function has been removed. Use the const version instead. To delete a child element,
 * use @link gloox::Tag::removeChild() removeChild() @endlink.
 *
 * @subsubsection func_createStanzas 1.2.7 Stanza::createMessageStanza(), Stanza::createPresenceStanza(), Stanza::createIqStanza(), Stanza::createSubscriptionStanza()
 *
 * These functions have been removed in favour of the more specialized classes
 * @link gloox::Message Message @endlink, @link gloox::Presence Presence @endlink,
 * @link gloox::IQ IQ @endlink, and @link gloox::Subscription Subscription @endlink.
 *
 * @subsubsection class_InBandBytestreamManager 1.2.8 InBandBytestreamManager
 *
 * The Message-based Inband Bytestream implementation has been removed in favour of an IQ-based one.
 * Also, Inband Bytestreams are now handled (transparently) by @link gloox::SIProfileFT SIProfileFT @endlink.
 *
 * @subsubsection func_AdhocHandler_handleAdhocError 1.2.9 AdhocHandler::handleAdhocError( const JID&, StanzaError )
 *
 * This function has been removed in favor of
 * @link gloox::AdhocHandler::handleAdhocError( const JID&, const Error* ) handleAdhocError( const JID&, const Error* ) @endlink.
 *
 * @subsubsection func_SIProfileFTHandler_handleFTRequestError 1.2.10 SIProfileFTHandler::handleFTRequestError( IQ*, const std::string& )
 *
 * This function has been removed in favor of
 * @link gloox::SIProfileFTHandler::handleFTRequestError( const IQ&, const std::string& ) handleFTRequestError( const IQ&, const std::string& ) @endlink.
 *
 * @subsubsection func_BytestreamHandler_handelBytestreamError 1.2.11 BytestreamHandler::handleBytestreamError( IQ* iq, const std::string& sid )
 *
 * This function has been removed in favor of
 * @link gloox::BytestreamHandler::handleBytestreamError( const IQ& iq, const std::string& ) handleBytestreamError( const IQ& iq, const std::string& sid ) @endlink.
 *
 * @subsubsection func_BytestreamDataHandler_handelBytestreamError 1.2.12 BytestreamDataHandler::handleBytestreamError( Bytestream* bs, IQ* )
 *
 * This function has been removed in favor of
 * @link gloox::BytestreamDataHandler::handleBytestreamError( Bytestream* bs, const IQ& ) handleBytestreamError( Bytestream* bs, const IQ& ) @endlink.
 *
 * @subsubsection func_Disco_category 1.2.13 Disco::category()
 *
 * This function has been removed. Use @link gloox::Disco::identities() Disco::identities() @endlink
 * instead.
 *
 * @subsubsection func_Disco_type 1.2.14 Disco::type()
 *
 * This function has been removed. Use @link gloox::Disco::identities() Disco::identities() @endlink
 * instead.
 *
 * @subsubsection func_PrivateXMLHandler_handlePrivateXML 1.2.15 PrivateXMLHandler::handlePrivateXML( const std::string&, Tag* )
 *
 * This function has been removed in favor of
 * @link gloox::PrivateXMLHandler::handlePrivateXML() PrivateXMLHandler::handlePrivateXML( const Tag* ) @endlink.
 *
 * @subsubsection func_PrivateXML_storeXML 1.2.16 PrivateXML::storeXML( Tag*, PrivateXMLHandler* )
 *
 * This function has been removed in favor of
 * @link gloox::PrivateXML::storeXML() PrivateXML::storeXML( const Tag*, PrivateXMLHandler* ) @endlink.
 *
 * @subsubsection func_Client 1.2.17 Client::Client( string, string, string, string, int )
 *
 * This function has been removed. The only recommended alternative is
 * @link gloox::Client::Client() Client::Client( const JID&, const std::string&, int ) @endlink.
 *
 *
 *
 *
 *
 *
 * @subsection semantics_10 1.3 Semantic Changes
 *
 * @subsubsection param_handleFTRequest 1.3.1 SIProfileFTHandler::handleFTRequest()
 *
 * The second parameter is now a Session ID (sid). This should be used with
 * @link gloox::SIProfileFT::acceptFT() SIProfileFT::acceptFTRequest() @endlink or
 * @link gloox::SIProfileFT::declineFT() SIProfileFT::declineFTRequest() @endlink.
 *
 * @subsubsection param_acceptFTRequest 1.3.2 SIProfileFT::acceptFTRequest()
 *
 * The second parameter is now a Session ID (sid). It must be the same value as the Session ID (sid)
 * passed to
 * @link gloox::SIProfileFTHandler::handleFTRequest() SIProfileFTHandler::handleFTRequest() @endlink.
 * Further, the function has been renamed to
 * @link gloox::SIProfileFT::acceptFT() acceptFT() @endlink.
 *
 * @subsubsection param_declineFTRequest 1.3.3 SIProfileFT::declineFTRequest()
 *
 * The second parameter is now a Session ID (sid). It must be the same value as the Session ID (sid)
 * passed to
 * @link gloox::SIProfileFTHandler::handleFTRequest() SIProfileFTHandler::handleFTRequest() @endlink.
 * Further, the function has been renamed to
 * @link gloox::SIProfileFT::declineFT() declineFT() @endlink.
 *
 * @section upgrading_10_101 2. Upgrading from to 1.0 to 1.0.1
 * 
 * NB: 1.0.1 is not binary-compatible to 1.0. The reason for that is the addition of support for XEP-0174, which made it
 * necessary to add a parameter to @link gloox::ClientBase::handleStartNode( const Tag* ) ClientBase::handleStartNode() @endlink.
 * 
 */