Skip to content
This repository was archived by the owner on Mar 4, 2023. It is now read-only.

Commit 8dd24a3

Browse files
Skycoder42Skycoder42
committed
added exchange doc
1 parent 96be0c4 commit 8dd24a3

File tree

3 files changed

+304
-11
lines changed

3 files changed

+304
-11
lines changed

‎doc/userexchangemanager.dox‎

Lines changed: 285 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,285 @@
1+
/*!
2+
@class QtDataSync::UserInfo
3+
4+
This class is used by the UserExchangeManager class to provide information about discovered
5+
users. The name can be choosen by the remote that sent the user information, address and port
6+
are detected from the message.
7+
8+
@sa UserExchangeManager, UserExchangeManager::devices
9+
*/
10+
11+
/*!
12+
@property QtDataSync::UserInfo::name
13+
14+
@default{`"<Unnamed>"` (Translated)}
15+
16+
The name can be choosen by whoever sent the message. It is
17+
typically used to identify a device from a users view.
18+
19+
@accessors{
20+
@readAc{name()}
21+
@constantAc
22+
}
23+
24+
@sa UserExchangeManager::deviceName
25+
*/
26+
27+
/*!
28+
@property QtDataSync::UserInfo::address
29+
30+
@default{<i>Unknown</i>}
31+
32+
The address from where the message came. Is also used
33+
as target address to send a message back.
34+
35+
@accessors{
36+
@readAc{address()}
37+
@constantAc
38+
}
39+
40+
@sa UserInfo::port
41+
*/
42+
43+
/*!
44+
@property QtDataSync::UserInfo::port
45+
46+
@default{<i>Unknown</i>}
47+
48+
The port from where the message came. Is also used
49+
as target port to send a message back.
50+
51+
@accessors{
52+
@readAc{port()}
53+
@constantAc
54+
}
55+
56+
@sa UserInfo::address
57+
*/
58+
59+
60+
61+
/*!
62+
@class QtDataSync::UserExchangeManager
63+
64+
This class can be used to exchange the user identity af a setup via the local network. It
65+
provides an easy way to transfer the identity between devices, without any need of external
66+
transport mediums to get the exported data to another device.
67+
68+
@note The class makes use of UDP-Broadcasts to discover other devices on the local network.
69+
This only works if both devices have an active UserExchangeManager running and if the network
70+
they both are connected to supports broadcasts. It does <b>not</b> work across networks.
71+
72+
@sa AccountManager
73+
*/
74+
75+
/*!
76+
@property QtDataSync::UserExchangeManager::active
77+
78+
@default{`false`}
79+
80+
The UserExchangeManager is considered active when actively searching for other devices, ready
81+
to export or import data from and to other devices.
82+
83+
When inactive, the device is disconnected from the network and does not send or receive any
84+
data.
85+
86+
@accessors{
87+
@readAc{isActive()}
88+
@notifyAc{activeChanged()}
89+
}
90+
91+
@sa UserExchangeManager::startExchange, UserExchangeManager::stopExchange
92+
*/
93+
94+
/*!
95+
@property QtDataSync::UserExchangeManager::devices
96+
97+
@default{<i>Empty</i>}
98+
99+
This list contains all devices discovered on the local network (excluding yourself). It only can
100+
find devices that have the exchange active on the same port. The list will only contain any
101+
users if active.
102+
103+
@accessors{
104+
@readAc{users()}
105+
@notifyAc{usersChanged()}
106+
}
107+
108+
@sa UserInfo, UserExchangeManager::active, UserExchangeManager::userDataReceived,
109+
UserExchangeManager::exportTo, UserExchangeManager::exportTrustedTo,
110+
UserExchangeManager::importFrom, UserExchangeManager::importTrustedFrom
111+
*/
112+
113+
/*!
114+
@fn QtDataSync::UserExchangeManager::UserExchangeManager(AccountManager *, QObject *)
115+
116+
@param manager The account manager to use to import and export account data
117+
@param parent The parent object
118+
119+
@attention The exchange manager does **not** take ownership of the passed account manager. Thus,
120+
the account manager must stay valid as long as the exchange manager exists.
121+
*/
122+
123+
/*!
124+
@fn QtDataSync::UserExchangeManager::accountManager
125+
126+
@returns A pointer to the interal account manager object
127+
128+
Returns a reference to the internally used manager. The manager is only valid as long as the
129+
UserExchangeManager exists. You can use the manager reference to get information about it's
130+
state etc.
131+
*/
132+
133+
/*!
134+
@fn QtDataSync::UserExchangeManager::port
135+
136+
@returns The currently used port, if active
137+
138+
The returned port is only valid whne activly exchanging. Can be used to retrieve the choosen
139+
port when working with random ports. If not connected, 0 is returned
140+
141+
@sa UserExchangeManager::active, UserExchangeManager::startExchange
142+
*/
143+
144+
/*!
145+
@fn QtDataSync::UserExchangeManager::exportTo
146+
147+
@param userInfo The user to send the identity to
148+
@param includeServer Specify whether the server address and configuration should be included
149+
into the export data
150+
151+
The identity of the current user for the setup used on this instance is exported and sent to the
152+
address represented by the passed userInfo. The userInfo should be a user discovered by the
153+
exchange from UserExchangeManager::devices
154+
155+
Internally, AccountManager::exportAccount is used to perform the actual export. That data is
156+
then sent over the network to the partner device. See that documentation for more details.
157+
158+
@sa UserExchangeManager::userDataReceived, UserExchangeManager::importFrom,
159+
UserExchangeManager::exportTrustedTo, AccountManager::exportAccount
160+
*/
161+
162+
/*!
163+
@fn QtDataSync::UserExchangeManager::exportTrustedTo
164+
165+
@param userInfo The user to send the identity to
166+
@param includeServer Specify whether the server address and configuration should be included
167+
into the export data
168+
@param password The password used to encrypt the exported data with
169+
170+
The identity of the current user for the setup used on this instance is exported and sent to the
171+
address represented by the passed userInfo. The userInfo should be a user discovered by the
172+
exchange from UserExchangeManager::devices
173+
174+
Internally, AccountManager::exportAccountTrusted is used to perform the actual export. That data
175+
is then sent over the network to the partner device. See that documentation for more details.
176+
177+
@sa UserExchangeManager::userDataReceived, UserExchangeManager::importTrustedFrom,
178+
UserExchangeManager::exportTo, AccountManager::exportAccountTrusted
179+
*/
180+
181+
/*!
182+
@fn QtDataSync::UserExchangeManager::importFrom
183+
184+
@param userInfo The user to that sent the data to import
185+
@param completedFn A function that is called once the import has been finished
186+
@param keepData Specify whether the stored data should be preserved
187+
188+
Use this method to perform the actual import of an identity after receiving it via
189+
userDataReceived(). This only works if data has been received from the user that way. Otherwise
190+
the operation will fail.
191+
192+
Internally, AccountManager::importAccount is used to perform the actual import. The received
193+
data is simply passed to that method. See that documentation for more details.
194+
195+
@sa UserExchangeManager::userDataReceived, UserExchangeManager::exportTo,
196+
UserExchangeManager::importTrustedFrom, AccountManager::importAccount
197+
*/
198+
199+
/*!
200+
@fn QtDataSync::UserExchangeManager::importTrustedFrom
201+
202+
@param userInfo The user to that sent the data to import
203+
@param password The password used to decrypt the imported data with. Must be the same as used
204+
for the export
205+
@param completedFn A function that is called once the import has been finished
206+
@param keepData Specify whether the stored data should be preserved
207+
208+
Use this method to perform the actual import of an identity after receiving it via
209+
userDataReceived(). This only works if data has been received from the user that way. Otherwise
210+
the operation will fail.
211+
212+
Internally, AccountManager::importAccountTrusted is used to perform the actual import. The
213+
received data is simply passed to that method. See that documentation for more details.
214+
215+
@sa UserExchangeManager::userDataReceived, UserExchangeManager::exportTrustedTo,
216+
UserExchangeManager::importFrom, AccountManager::importAccountTrusted
217+
*/
218+
219+
/*!
220+
@fn QtDataSync::UserExchangeManager::startExchange(quint16)
221+
222+
@param port The port to start the exchange on
223+
@returns true, if successfully started, false if not
224+
225+
The exchange is run for all addresses, allowing connections from anywhere and broadcasting to
226+
anyone in the local network.
227+
228+
If the function fails, the error string describing what went wrong is emitted via
229+
exchangeError().
230+
231+
@sa UserExchangeManager::active, UserExchangeManager::exchangeError,
232+
UserExchangeManager::stopExchange
233+
*/
234+
235+
/*!
236+
@fn QtDataSync::UserExchangeManager::startExchange(const QHostAddress &, quint16)
237+
238+
@param listenAddress The address to listen on for incoming messages
239+
@param port The port to start the exchange on
240+
@returns true, if successfully started, false if not
241+
242+
The exchange is run for the given addresses, allowing connections only from addresses matching
243+
the given address and broadcasting to anyone in the local network.
244+
245+
If the function fails, the error string describing what went wrong is emitted via
246+
exchangeError().
247+
248+
@sa UserExchangeManager::active, UserExchangeManager::exchangeError,
249+
UserExchangeManager::stopExchange
250+
*/
251+
252+
/*!
253+
@fn QtDataSync::UserExchangeManager::stopExchange
254+
255+
Stops sending and receiving messages, clears all users and pending imports. After stopping,
256+
this device disappears from the network and can neither be discovered by other exchanges, nor
257+
discover them.
258+
259+
@sa UserExchangeManager::active, UserExchangeManager::startExchange
260+
*/
261+
262+
/*!
263+
@fn QtDataSync::UserExchangeManager::userDataReceived
264+
265+
@param userInfo The user that sent his identity to this device
266+
@param trusted `true` if the received data is a trusted export, `false` if it is untrusted
267+
268+
When a user exports his identity to this device via exportTo() or exportTrustedTo(), this signal
269+
is emitted. Connect to it to react an proposed identity data. The data is <b>not</b> imported
270+
immediatly. You can use the importFrom() and importTrustedFrom() methods to perform the actual
271+
import of the data, if you want to accept it. Choose the correct import method based on the
272+
`trusted` parameter.
273+
274+
@sa UserExchangeManager::importFrom, UserExchangeManager::importTrustedFrom,
275+
UserExchangeManager::exportTo, UserExchangeManager::exportTrustedTo
276+
*/
277+
278+
/*!
279+
@fn QtDataSync::UserExchangeManager::exchangeError
280+
281+
@param errorString A localized error string describing what went wrong
282+
283+
Can be shown to the user to tell him something regarding the import or export (or the general
284+
exchange) failed.
285+
*/

‎src/datasync/exception.h‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -28,12 +28,12 @@ class Q_DATASYNC_EXPORT Exception : public QException
2828
//! Like what, but returns a QString instead of a character array
2929
virtual QString qWhat() const;
3030
//! @inherit{QException::what}
31-
const char *what() const noexcept final;
31+
const char *what() const noexcept final; //mark virtual again for doxygen
3232

3333
//! @inherit{QException::raise}
34-
void raise() const override;
34+
virtual void raise() const override; //mark virtual again for doxygen
3535
//! @inherit{QException::clone}
36-
QException *clone() const override;
36+
virtual QException *clone() const override; //mark virtual again for doxygen
3737

3838
protected:
3939
//! @private

‎src/datasync/userexchangemanager.h‎

Lines changed: 16 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -28,13 +28,11 @@ class Q_DATASYNC_EXPORT UserInfo
2828
Q_PROPERTY(quint16 port READ port CONSTANT)
2929

3030
public:
31-
//! Constructor
3231
UserInfo();
3332
//! Copy Constructor
3433
UserInfo(const UserInfo &other);
35-
//! Internal Constructor
34+
//! @private
3635
UserInfo(UserInfoPrivate *data);
37-
//! Destructor
3836
~UserInfo();
3937

4038
//! @readAcFn{UserInfo::name}
@@ -54,24 +52,29 @@ class Q_DATASYNC_EXPORT UserInfo
5452
};
5553

5654
class UserExchangeManagerPrivate;
55+
//! A helper class to exchange the account data between devices on the local network
5756
class Q_DATASYNC_EXPORT UserExchangeManager : public QObject
5857
{
5958
Q_OBJECT
6059

6160
//! Reports whether the instance is currently exchanging or not
6261
Q_PROPERTY(bool active READ isActive NOTIFY activeChanged)
63-
//! Holds all currently discovered users
62+
//! Holds all currently discovered devices
6463
Q_PROPERTY(QList<QtDataSync::UserInfo> devices READ devices NOTIFY devicesChanged)
6564

6665
public:
6766
//! The default port (13742) for the data exchange
6867
static const quint16 DataExchangePort;
6968

69+
//! @copydoc AccountManager::AccountManager(QObject *)
7070
explicit UserExchangeManager(QObject *parent = nullptr);
71+
//! @copydoc AccountManager::AccountManager(const QString &, QObject *)
7172
explicit UserExchangeManager(const QString &setupName, QObject *parent = nullptr);
73+
//! Constructor with an account manager to use for account import and export
7274
explicit UserExchangeManager(AccountManager *manager, QObject *parent = nullptr);
7375
~UserExchangeManager();
7476

77+
//! The internally used account manager used to export and import data
7578
AccountManager *accountManager() const;
7679

7780
//! Returns the currently used port
@@ -81,13 +84,15 @@ class Q_DATASYNC_EXPORT UserExchangeManager : public QObject
8184
//! @readAcFn{UserInfo::users}
8285
QList<UserInfo> devices() const;
8386

84-
//! Sends the user identity of the setup to the given user
87+
//! Sends the user identity to the given user as untrusted export
8588
Q_INVOKABLE void exportTo(const QtDataSync::UserInfo &userInfo, bool includeServer);
89+
//! Sends the user identity to the given user as trusted export
8690
Q_INVOKABLE void exportTrustedTo(const QtDataSync::UserInfo &userInfo, bool includeServer, const QString &password);
87-
//! Imports the user identity, previously received by the given user
91+
//! Imports the untrusted user data previously received by the given user
8892
void importFrom(const QtDataSync::UserInfo &userInfo,
8993
const std::function<void(bool,QString)> &completedFn,
9094
bool keepData = false);
95+
//! Imports the trusted user data previously received by the given user
9196
void importTrustedFrom(const QtDataSync::UserInfo &userInfo,
9297
const QString &password,
9398
const std::function<void(bool,QString)> &completedFn,
@@ -106,6 +111,7 @@ public Q_SLOTS:
106111
Q_SIGNALS:
107112
//! Is emitted, when a user identity was received from the given user
108113
void userDataReceived(const QtDataSync::UserInfo &userInfo, bool trusted, QPrivateSignal);
114+
//! Is emitted when an error occured trying to export or import
109115
void exchangeError(const QString &errorString, QPrivateSignal);
110116

111117
//! @notifyAcFn{UserInfo::active}
@@ -114,7 +120,9 @@ public Q_SLOTS:
114120
void devicesChanged(QList<QtDataSync::UserInfo> devices, QPrivateSignal);
115121

116122
protected:
123+
//! @private
117124
UserExchangeManager(QObject *parent, void*);
125+
//! @private
118126
void initManager(AccountManager *manager);
119127

120128
private Q_SLOTS:
@@ -125,9 +133,9 @@ private Q_SLOTS:
125133
QScopedPointer<UserExchangeManagerPrivate> d;
126134
};
127135

128-
//! qHash function overload for UserInfo, see qHash(int)
136+
//! Overload of qHash to use UserInfo with QHash
129137
Q_DATASYNC_EXPORT uint qHash(const QtDataSync::UserInfo &info, uint seed = 0);
130-
//! Stream operator for QDebug
138+
//! Stream operator to stream into a QDebug
131139
Q_DATASYNC_EXPORT QDebug operator<<(QDebug stream, const QtDataSync::UserInfo &userInfo);
132140

133141
}

0 commit comments

Comments
 (0)