1/******************************************************************************
2 * THIS FILE IS GENERATED - ANY EDITS WILL BE OVERWRITTEN
3 */
4
5#pragma once
6
7#include <Quotient/jobs/basejob.h>
8
9namespace Quotient {
10
11/*! \brief Invite a user to participate in a particular room.
12 *
13 * *Note that there are two forms of this API, which are documented separately.
14 * This version of the API does not require that the inviter know the Matrix
15 * identifier of the invitee, and instead relies on third-party identifiers.
16 * The homeserver uses an identity server to perform the mapping from
17 * third-party identifier to a Matrix identifier. The other is documented in
18 * the* [joining rooms
19 * section](/client-server-api/#post_matrixclientv3roomsroomidinvite).
20 *
21 * This API invites a user to participate in a particular room.
22 * They do not start participating in the room until they actually join the
23 * room.
24 *
25 * Only users currently in a particular room can invite other users to
26 * join that room.
27 *
28 * If the identity server did know the Matrix user identifier for the
29 * third-party identifier, the homeserver will append a `m.room.member`
30 * event to the room.
31 *
32 * If the identity server does not know a Matrix user identifier for the
33 * passed third-party identifier, the homeserver will issue an invitation
34 * which can be accepted upon providing proof of ownership of the third-
35 * party identifier. This is achieved by the identity server generating a
36 * token, which it gives to the inviting homeserver. The homeserver will
37 * add an `m.room.third_party_invite` event into the graph for the room,
38 * containing that token.
39 *
40 * When the invitee binds the invited third-party identifier to a Matrix
41 * user ID, the identity server will give the user a list of pending
42 * invitations, each containing:
43 *
44 * - The room ID to which they were invited
45 *
46 * - The token given to the homeserver
47 *
48 * - A signature of the token, signed with the identity server's private key
49 *
50 * - The matrix user ID who invited them to the room
51 *
52 * If a token is requested from the identity server, the homeserver will
53 * append a `m.room.third_party_invite` event to the room.
54 */
55class QUOTIENT_API InviteBy3PIDJob : public BaseJob {
56public:
57 /*! \brief Invite a user to participate in a particular room.
58 *
59 * \param roomId
60 * The room identifier (not alias) to which to invite the user.
61 *
62 * \param idServer
63 * The hostname+port of the identity server which should be used for
64 * third-party identifier lookups.
65 *
66 * \param idAccessToken
67 * An access token previously registered with the identity server. Servers
68 * can treat this as optional to distinguish between r0.5-compatible
69 * clients and this specification version.
70 *
71 * \param medium
72 * The kind of address being passed in the address field, for example
73 * `email` (see [the list of recognised values](/appendices/#3pid-types)).
74 *
75 * \param address
76 * The invitee's third-party identifier.
77 */
78 explicit InviteBy3PIDJob(const QString& roomId, const QString& idServer,
79 const QString& idAccessToken,
80 const QString& medium, const QString& address);
81};
82
83} // namespace Quotient
84