lib/csapi/third_party_lookup.h


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

/******************************************************************************
 * THIS FILE IS GENERATED - ANY EDITS WILL BE OVERWRITTEN
 */

#pragma once

#include "csapi/../application-service/definitions/location.h"
#include "csapi/../application-service/definitions/protocol.h"
#include "csapi/../application-service/definitions/user.h"

#include "jobs/basejob.h"

namespace Quotient {

/*! \brief Retrieve metadata about all protocols that a homeserver supports.
 *
 * Fetches the overall metadata about protocols supported by the
 * homeserver. Includes both the available protocols and all fields
 * required for queries against each protocol.
 */
class GetProtocolsJob : public BaseJob {
public:
    /// Retrieve metadata about all protocols that a homeserver supports.
    explicit GetProtocolsJob();

    /*! \brief Construct a URL without creating a full-fledged job object
     *
     * This function can be used when a URL for GetProtocolsJob
     * is necessary but the job itself isn't.
     */
    static QUrl makeRequestUrl(QUrl baseUrl);

    // Result properties

    /// The protocols supported by the homeserver.
    QHash<QString, ThirdPartyProtocol> protocols() const
    {
        return fromJson<QHash<QString, ThirdPartyProtocol>>(jsonData());
    }
};

/*! \brief Retrieve metadata about a specific protocol that the homeserver
 * supports.
 *
 * Fetches the metadata from the homeserver about a particular third party
 * protocol.
 */
class GetProtocolMetadataJob : public BaseJob {
public:
    /*! \brief Retrieve metadata about a specific protocol that the homeserver
     * supports.
     *
     * \param protocol
     *   The name of the protocol.
     */
    explicit GetProtocolMetadataJob(const QString& protocol);

    /*! \brief Construct a URL without creating a full-fledged job object
     *
     * This function can be used when a URL for GetProtocolMetadataJob
     * is necessary but the job itself isn't.
     */
    static QUrl makeRequestUrl(QUrl baseUrl, const QString& protocol);

    // Result properties

    /// The protocol was found and metadata returned.
    ThirdPartyProtocol data() const
    {
        return fromJson<ThirdPartyProtocol>(jsonData());
    }
};

/*! \brief Retrieve Matrix-side portals rooms leading to a third party location.
 *
 * Requesting this endpoint with a valid protocol name results in a list
 * of successful mapping results in a JSON array. Each result contains
 * objects to represent the Matrix room or rooms that represent a portal
 * to this third party network. Each has the Matrix room alias string,
 * an identifier for the particular third party network protocol, and an
 * object containing the network-specific fields that comprise this
 * identifier. It should attempt to canonicalise the identifier as much
 * as reasonably possible given the network type.
 */
class QueryLocationByProtocolJob : public BaseJob {
public:
    /*! \brief Retrieve Matrix-side portals rooms leading to a third party
     * location.
     *
     * \param protocol
     *   The protocol used to communicate to the third party network.
     *
     * \param searchFields
     *   One or more custom fields to help identify the third party
     *   location.
     */
    explicit QueryLocationByProtocolJob(const QString& protocol,
                                        const QString& searchFields = {});

    /*! \brief Construct a URL without creating a full-fledged job object
     *
     * This function can be used when a URL for QueryLocationByProtocolJob
     * is necessary but the job itself isn't.
     */
    static QUrl makeRequestUrl(QUrl baseUrl, const QString& protocol,
                               const QString& searchFields = {});

    // Result properties

    /// At least one portal room was found.
    QVector<ThirdPartyLocation> data() const
    {
        return fromJson<QVector<ThirdPartyLocation>>(jsonData());
    }
};

/*! \brief Retrieve the Matrix User ID of a corresponding third party user.
 *
 * Retrieve a Matrix User ID linked to a user on the third party service, given
 * a set of user parameters.
 */
class QueryUserByProtocolJob : public BaseJob {
public:
    /*! \brief Retrieve the Matrix User ID of a corresponding third party user.
     *
     * \param protocol
     *   The name of the protocol.
     *
     * \param fields
     *   One or more custom fields that are passed to the AS to help identify
     * the user.
     */
    explicit QueryUserByProtocolJob(const QString& protocol,
                                    const QString& fields = {});

    /*! \brief Construct a URL without creating a full-fledged job object
     *
     * This function can be used when a URL for QueryUserByProtocolJob
     * is necessary but the job itself isn't.
     */
    static QUrl makeRequestUrl(QUrl baseUrl, const QString& protocol,
                               const QString& fields = {});

    // Result properties

    /// The Matrix User IDs found with the given parameters.
    QVector<ThirdPartyUser> data() const
    {
        return fromJson<QVector<ThirdPartyUser>>(jsonData());
    }
};

/*! \brief Reverse-lookup third party locations given a Matrix room alias.
 *
 * Retrieve an array of third party network locations from a Matrix room
 * alias.
 */
class QueryLocationByAliasJob : public BaseJob {
public:
    /*! \brief Reverse-lookup third party locations given a Matrix room alias.
     *
     * \param alias
     *   The Matrix room alias to look up.
     */
    explicit QueryLocationByAliasJob(const QString& alias);

    /*! \brief Construct a URL without creating a full-fledged job object
     *
     * This function can be used when a URL for QueryLocationByAliasJob
     * is necessary but the job itself isn't.
     */
    static QUrl makeRequestUrl(QUrl baseUrl, const QString& alias);

    // Result properties

    /// All found third party locations.
    QVector<ThirdPartyLocation> data() const
    {
        return fromJson<QVector<ThirdPartyLocation>>(jsonData());
    }
};

/*! \brief Reverse-lookup third party users given a Matrix User ID.
 *
 * Retrieve an array of third party users from a Matrix User ID.
 */
class QueryUserByIDJob : public BaseJob {
public:
    /*! \brief Reverse-lookup third party users given a Matrix User ID.
     *
     * \param userid
     *   The Matrix User ID to look up.
     */
    explicit QueryUserByIDJob(const QString& userid);

    /*! \brief Construct a URL without creating a full-fledged job object
     *
     * This function can be used when a URL for QueryUserByIDJob
     * is necessary but the job itself isn't.
     */
    static QUrl makeRequestUrl(QUrl baseUrl, const QString& userid);

    // Result properties

    /// An array of third party users.
    QVector<ThirdPartyUser> data() const
    {
        return fromJson<QVector<ThirdPartyUser>>(jsonData());
    }
};

} // namespace Quotient