/**
* @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.
*
* @section contents Contents
* @ref upgrading_09_10 <br>
* @ref deprecated_10 <br>
* @ref removed_10 <br>
* @ref semantics_10 <br>
*
* @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.
*
*/
