File: UPGRADING

package info (click to toggle)
gloox 1.0.18-1
  • links: PTS, VCS
  • area: main
  • in suites: stretch
  • size: 6,732 kB
  • ctags: 6,556
  • sloc: cpp: 45,479; sh: 11,344; makefile: 1,018
file content (324 lines) | stat: -rw-r--r-- 11,838 bytes parent folder | download | duplicates (6)
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
324
/**
 * @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.
 * 
 */