1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323
|
/**
* @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.
*
*/
|