· 8 years ago · Jul 20, 2018, 07:20 PM
1/*
2 * Copyright sablintolya@gmail.com
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 * http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16
17package io.github.ma1uta.matrix.android.api;
18
19import io.github.ma1uta.matrix.android.model.common.EmptyResponse;
20import io.github.ma1uta.matrix.android.model.room.CreateRoomRequest;
21import io.github.ma1uta.matrix.android.model.room.InviteRequest;
22import io.github.ma1uta.matrix.android.model.room.JoinRequest;
23import io.github.ma1uta.matrix.android.model.room.JoinedRoomsResponse;
24import io.github.ma1uta.matrix.android.model.room.KickRequest;
25import io.github.ma1uta.matrix.android.model.room.PublicRoomsRequest;
26import io.github.ma1uta.matrix.android.model.room.PublicRoomsResponse;
27import io.github.ma1uta.matrix.android.model.room.RoomId;
28import io.github.ma1uta.matrix.android.model.room.RoomVisibility;
29import retrofit2.http.Body;
30import retrofit2.http.DELETE;
31import retrofit2.http.GET;
32import retrofit2.http.Headers;
33import retrofit2.http.POST;
34import retrofit2.http.PUT;
35import retrofit2.http.Path;
36import retrofit2.http.Query;
37
38import java.util.List;
39
40/**
41 * Rooms apis.
42 */
43public interface RoomApi {
44 /**
45 * Visibility.
46 */
47 class Visibility {
48
49 protected Visibility() {
50 }
51
52 /**
53 * Public.
54 */
55 public static final String PUBLIC = "public";
56
57 /**
58 * Private.
59 */
60 public static final String PRIVATE = "private";
61 }
62
63 /**
64 * Presets.
65 */
66 class Preset {
67
68 protected Preset() {
69 }
70
71 /**
72 * Private.
73 */
74 public static final String PRIVATE_CHAT = "private_chat";
75
76 /**
77 * Public.
78 */
79 public static final String PUBLIC_CHAT = "public_chat";
80
81 /**
82 * Trusted.
83 */
84 public static final String TRUSTED_PRIVATE_CHAT = "trusted_private_chat";
85 }
86
87 /**
88 * Create a new room with various configuration options.
89 * <p/>
90 * The server MUST apply the normal state resolution rules when creating the new room, including checking power levels for each event.
91 * It MUST apply the events implied by the request in the following order:
92 * <ol>
93 * <li>A default m.room.power_levels event, giving the room creator (and not other members) permission to send state events.</li>
94 * <li>Events set by the presets.</li>
95 * <li>Events listed in initial_state, in the order that they are listed.</li>
96 * <li>Events implied by name and topic.</li>
97 * <li>Invite events implied by invite and invite_3pid.</li>
98 * </ol>
99 * <p/>
100 * The available presets do the following with respect to room state:
101 * <table>
102 * <tr>
103 * <th>Preset</th>
104 * <th>join_rules</th>
105 * <th>history_visibility</th>
106 * <th>guest_access</th>
107 * <th>Other</th>
108 * </tr>
109 * <tr>
110 * <td>private_chat</td>
111 * <td>invite</td>
112 * <td>shared</td>
113 * <td>can_join</td>
114 * </tr>
115 * <tr>
116 * <td>trusted_private_chat</td>
117 * <td>invite</td>
118 * <td>shared</td>
119 * <td>can_join</td>
120 * <td>All invitees are given the same power level as the room creator.</td>
121 * </tr>
122 * <tr>
123 * <td>public_chat</td>
124 * <td>public</td>
125 * <td>shared</td>
126 * <td>forbidden</td>
127 * </tr>
128 * </table>
129 * <b>Requires auth</b>: Yes.
130 *
131 * @param createRoomRequest JSON body parameters.
132 * @return Status code 200: Information about the newly created room.
133 * Status code 400: The request is invalid. A meaningful errcode and description error text will be returned.
134 * Example reasons for rejection include:
135 * <ul>
136 * <li>The request body is malformed (errcode set to M_BAD_JSON or M_NOT_JSON).</li>
137 * <li>The room alias specified is already taken (errcode set to M_ROOM_IN_USE).</li>
138 * <li>The initial state implied by the parameters to the request is invalid: for example, the user's power_level is set
139 * below that necessary to set the room name (errcode set to M_INVALID_ROOM_STATE).</li>
140 * </ul>
141 */
142 @POST("/_matrix/client/r0/createRoom")
143 @Headers("Content-type: application/json")
144 RoomId create(@Body CreateRoomRequest createRoomRequest);
145
146 /**
147 * Create a new mapping from room alias to room ID.
148 * <p/>
149 * <b>Requires auth</b>: Yes.
150 *
151 * @param roomAlias Required. The room alias to set.
152 * @param roomId json body request.
153 * @return Status code 200: The mapping was created.
154 * Status code 409: A room alias with that name already exists.
155 */
156 @PUT("/_matrix/client/r0/directory/room/{roomAlias}")
157 @Headers("Content-type: application/json")
158 EmptyResponse newAlias(@Path("roomAlias") String roomAlias, @Body RoomId roomId);
159
160 /**
161 * Requests that the server resolve a room alias to a room ID.
162 * <p/>
163 * The server will use the federation API to resolve the alias if the domain part of the alias does not correspond to the server's
164 * own domain.
165 *
166 * @param roomAlias Required. The room alias.
167 * @return Status code 200: The room ID and other information for this alias.
168 * Status code 404: There is no mapped room ID for this room alias.
169 */
170 @GET("/_matrix/client/r0/directory/room/{roomAlias}")
171 @Headers("Content-type: application/json")
172 RoomId resolve(@Path("roomAlias") String roomAlias);
173
174 /**
175 * Remove a mapping of room alias to room ID.
176 * <p/>
177 * Servers may choose to implement additional access control checks here, for instance that room aliases can only be deleted
178 * by their creator or a server administrator.
179 * <p/>
180 * <b>Requires auth</b>: Yes.
181 *
182 * @param roomAlias Required. The room alias to remove.
183 * @return Status code 200: The mapping was deleted.
184 */
185 @DELETE("/_matrix/client/r0/directory/room/{roomAlias}")
186 @Headers("Content-type: application/json")
187 EmptyResponse delete(@Path("roomAlias") String roomAlias);
188
189 /**
190 * This API returns a list of the user's current rooms.
191 * <p/>
192 * <b>Requires auth</b>: Yes.
193 *
194 * @return Status code 200: A list of the rooms the user is in.
195 */
196 @GET("/_matrix/client/r0/joined_rooms")
197 @Headers("Content-type: application/json")
198 JoinedRoomsResponse joinedRooms();
199
200 /**
201 * Note that there are two forms of this API, which are documented separately. This version of the API requires that the inviter
202 * knows the Matrix identifier of the invitee. The other is documented in the third party invites section.
203 * <p/>
204 * This API invites a user to participate in a particular room. They do not start participating in the room until they actually
205 * join the room.
206 * <p/>
207 * Only users currently in a particular room can invite other users to join that room.
208 * <p/>
209 * If the user was invited to the room, the homeserver will append a m.room.member event to the room.
210 * <p/>
211 * <b>Rate-limited</b>: Yes.
212 * <p/>
213 * <b>Requires auth</b>: Yes.
214 *
215 * @param roomId Required. The room identifier (not alias) to which to invite the user.
216 * @param inviteRequest JSON body request.
217 * @return Status code 200: The user has been invited to join the room.
218 * Status code 403: You do not have permission to invite the user to the room. A meaningful errcode and description error text
219 * will be returned. Example reasons for rejections are:
220 * <ul>
221 * <li>The invitee has been banned from the room.</li>
222 * <li>The invitee is already a member of the room.</li>
223 * <li>The inviter is not currently in the room.</li>
224 * <li>The inviter's power level is insufficient to invite users to the room.</li>
225 * </ul>
226 * Status code 429: This request was rate-limited.
227 */
228 @POST("/_matrix/client/r0/rooms/{roomId}/invite")
229 @Headers("Content-type: application/json")
230 EmptyResponse invite(@Path("roomId") String roomId, @Body InviteRequest inviteRequest);
231
232 /**
233 * Note that this API requires a room ID, not alias. /join/{roomIdOrAlias} exists if you have a room alias.
234 * <p/>
235 * This API starts a user participating in a particular room, if that user is allowed to participate in that room.
236 * After this call, the client is allowed to see all current state events in the room, and all subsequent events associated
237 * with the room until the user leaves the room.
238 * <p/>
239 * After a user has joined a room, the room will appear as an entry in the response of the /initialSync and /sync APIs.
240 * <p/>
241 * If a third_party_signed was supplied, the homeserver must verify that it matches a pending m.room.third_party_invite
242 * event in the room, and perform key validity checking if required by the event.
243 * <p/>
244 * <b>Rate-limited</b>: Yes.
245 * <p/>
246 * <b>Requires auth</b>: Yes.
247 *
248 * @param roomId Required. The room identifier (not alias) to join.
249 * @param joinRequest JSON body request.
250 * @return Status code 200: The room has been joined. The joined room ID must be returned in the room_id field.
251 * Status code 403: You do not have permission to join the room. A meaningful errcode and description error text will be returned.
252 * Example reasons for rejection are:
253 * <ul>
254 * <li>The room is invite-only and the user was not invited.</li>
255 * <li>The user has been banned from the room.</li>
256 * </ul>
257 * Status code 429:This request was rate-limited.
258 */
259 @POST("/_matrix/client/r0/rooms/{roomId}/join")
260 @Headers("Content-type: application/json")
261 RoomId join(@Path("roomId") String roomId, @Body JoinRequest joinRequest);
262
263 /**
264 * Note that this API takes either a room ID or alias, unlike /room/{roomId}/join.
265 * <p/>
266 * This API starts a user participating in a particular room, if that user is allowed to participate in that room.
267 * After this call, the client is allowed to see all current state events in the room, and all subsequent events associated
268 * with the room until the user leaves the room.
269 * <p/>
270 * After a user has joined a room, the room will appear as an entry in the response of the /initialSync and /sync APIs.
271 * <p/>
272 * If a third_party_signed was supplied, the homeserver must verify that it matches a pending m.room.third_party_invite
273 * event in the room, and perform key validity checking if required by the event.
274 * <p/>
275 * <b>Rate-limited</b>: Yes.
276 * <p/>
277 * <b>Requires auth</b>: Yes.
278 *
279 * @param roomIdOrAlias Required. The room identifier or alias to join.
280 * @param joinRequest JSON body request.
281 * @param serverName The servers to attempt to join the room through. One of the servers must be participating in the room.
282 * @return Status code 200: The room has been joined. The joined room ID must be returned in the room_id field.
283 * Status code 403:
284 * You do not have permission to join the room. A meaningful errcode and description error text will be returned.
285 * Example reasons for rejection are:
286 * <ul>
287 * <li>The room is invite-only and the user was not invited.</li>
288 * <li>The user has been banned from the room.</li>
289 * </ul>
290 * Status code 429: This request was rate-limited.
291 */
292 @POST("/_matrix/client/r0/join/{roomIdOrAlias}")
293 @Headers("Content-type: application/json")
294 RoomId joinByIdOrAlias(@Path("roomIdOrAlias") String roomIdOrAlias, @Query("server_name") List<String> serverName,
295 @Body JoinRequest joinRequest);
296
297 /**
298 * This API stops a user participating in a particular room.
299 * <p/>
300 * If the user was already in the room, they will no longer be able to see new events in the room.
301 * If the room requires an invite to join, they will need to be re-invited before they can re-join.
302 * <p/>
303 * If the user was invited to the room, but had not joined, this call serves to reject the invite.
304 * <p/>
305 * The user will still be allowed to retrieve history from the room which they were previously allowed to see.
306 * <p/>
307 * Rate-limited: Yes.
308 * <p/>
309 * Requires auth: Yes.
310 *
311 * @param roomId Required. The room identifier to leave.
312 * @return Status code 200: The room has been left.
313 * Status code 429: This request was rate-limited.
314 */
315 @POST("/_matrix/client/r0/rooms/{roomId}/leave")
316 @Headers("Content-type: application/json")
317 EmptyResponse leave(@Path("roomId") String roomId);
318
319 /**
320 * This API stops a user remembering about a particular room.
321 * <p/>
322 * In general, history is a first class citizen in Matrix. After this API is called, however, a user will no longer be
323 * able to retrieve history for this room. If all users on a homeserver forget a room, the room is eligible for deletion
324 * from that homeserver.
325 * <p/>
326 * If the user is currently joined to the room, they must leave the room before calling this API.
327 * <p/>
328 * <b>Rate-limited</b>: Yes.
329 * <p/>
330 * <b>Requires auth</b>: Yes.
331 *
332 * @param roomId Required. The room identifier to forget.
333 * @return Status code 200: The room has been forgotten.
334 * Status code 400: The user has not left the room.
335 * Status code 429: This request was rate-limited.
336 */
337 @POST("/_matrix/client/r0/rooms/{roomId}/forget")
338 @Headers("Content-type: application/json")
339 EmptyResponse forget(@Path("roomId") String roomId);
340
341 /**
342 * Kick a user from the room.
343 * <p/>
344 * The caller must have the required power level in order to perform this operation.
345 * <p/>
346 * Kicking a user adjusts the target member's membership state to be ``leave`` with an
347 * optional ``reason``. Like with other membership changes, a user can directly adjust
348 * the target member's state by making a request to ``/rooms/<room id>/state/m.room.member/<user id>``.
349 * <p/>
350 * <b>Requires auth</b>: Yes.
351 *
352 * @param roomId Required. The room identifier (not alias) from which the user should be kicked.
353 * @param kickRequest JSON body request.
354 * @return Status code 200: The user has been kicked from the room.
355 * Status code 403: You do not have permission to kick the user from the room. A meaningful errcode and description error
356 * text will be returned. Example reasons for rejections are:
357 * <ul>
358 * <li>The kicker is not currently in the room.</li>
359 * <li>The kickee is not currently in the room.</li>
360 * <li>The kicker's power level is insufficient to kick users from the room.</li>
361 * </ul>
362 */
363 @POST("/_matrix/client/r0/rooms/{roomId}/kick")
364 @Headers("Content-type: application/json")
365 EmptyResponse kick(@Path("roomId") String roomId, @Body KickRequest kickRequest);
366
367 /**
368 * Ban a user in the room. If the user is currently in the room, also kick them.
369 * <p/>
370 * When a user is banned from a room, they may not join it or be invited to it until they are unbanned.
371 * <p/>
372 * The caller must have the required power level in order to perform this operation.
373 * <p/>
374 * <b>Requires auth</b>: Yes.
375 *
376 * @param roomId Required. The room identifier (not alias) from which the user should be banned.
377 * @param banRequest JSON body request.
378 * @return Status code 200: The user has been kicked and banned from the room.
379 * Status code 403: You do not have permission to ban the user from the room. A meaningful errcode and description error
380 * text will be returned. Example reasons for rejections are:
381 * <ul>
382 * <li>The banner is not currently in the room.</li>
383 * <li>The banner's power level is insufficient to ban users from the room.</li>
384 * </ul>
385 */
386 @POST("/_matrix/client/r0/rooms/{roomId}/ban")
387 @Headers("Content-type: application/json")
388 EmptyResponse ban(@Path("roomId") String roomId, @Body KickRequest banRequest);
389
390 /**
391 * Unban a user from the room. This allows them to be invited to the room, and join if they would otherwise be allowed to join
392 * according to its join rules.
393 * <p/>
394 * The caller must have the required power level in order to perform this operation.
395 * <p/>
396 * <b>Requires auth</b>: Yes.
397 *
398 * @param roomId Required. The room identifier (not alias) from which the user should be unbanned.
399 * @param unbanRequest JSON body request.
400 * @return Status code 200: The user has been unbanned from the room.
401 * Status code 403: You do not have permission to unban the user from the room. A meaningful errcode and description error
402 * text will be returned. Example reasons for rejections are:
403 * <ul>
404 * <li>The unbanner's power level is insufficient to unban users from the room.</li>
405 * </ul>
406 */
407 @POST("/_matrix/client/r0/rooms/{roomId}/unban")
408 @Headers("Content-type: application/json")
409 EmptyResponse unban(@Path("roomId") String roomId, @Body KickRequest unbanRequest);
410
411 /**
412 * Gets the visibility of a given room on the server's public room directory.
413 *
414 * @param roomId Required. The room ID.
415 * @return Status code 200: The visibility of the room in the directory
416 * Status code 404: The room is not known to the server
417 */
418 @GET("/_matrix/client/r0/directory/list/room/{roomId}")
419 @Headers("Content-type: application/json")
420 RoomVisibility getVisibility(@Path("roomId") String roomId);
421
422 /**
423 * Sets the visibility of a given room in the server's public room directory.
424 * <p/>
425 * Servers may choose to implement additional access control checks here, for instance that room visibility can only be
426 * changed by the room creator or a server administrator.
427 * <p/>
428 * <b>Requires auth</b>: Yes.
429 *
430 * @param roomId Required. The room ID.
431 * @param visibility json body request.
432 * @return Status code 200: The visibility was updated, or no change was needed.
433 * Status code 404: The room is not known to the server.
434 */
435 @PUT("/_matrix/client/r0/directory/list/room/{roomId}")
436 @Headers("Content-type: application/json")
437 EmptyResponse setVisibility(@Path("roomId") String roomId, @Body RoomVisibility visibility);
438
439 /**
440 * Lists the public rooms on the server.
441 * <p/>
442 * This API returns paginated responses. The rooms are ordered by the number of joined members, with the largest rooms first.
443 *
444 * @param limit Limit the number of results returned.
445 * @param since A pagination token from a previous request, allowing clients to get the next (or previous) batch of rooms.
446 * The direction of pagination is specified solely by which token is supplied, rather than via an explicit flag.
447 * @param server The server to fetch the public room lists from. Defaults to the local server.
448 * @return Status code 200: A list of the rooms on the server.
449 */
450 @GET("/_matrix/client/r0/publicRooms")
451 @Headers("Content-type: application/json")
452 PublicRoomsResponse showPublicRooms(@Query("limit") Long limit, @Query("since") String since, @Query("server") String server);
453
454 /**
455 * Lists the public rooms on the server, with optional filter.
456 * <p/>
457 * This API returns paginated responses. The rooms are ordered by the number of joined members, with the largest rooms first.
458 * <p/>
459 * <b>Requires auth</b>: Yes.
460 *
461 * @param server The server to fetch the public room lists from. Defaults to the local server.
462 * @param publicRoomsRequest JSON body request.
463 * @return Status code 200: A list of the rooms on the server.
464 */
465 @POST("/_matrix/client/r0/publicRooms")
466 @Headers("Content-type: application/json")
467 PublicRoomsResponse searchPublicRooms(@Query("server") String server, @Body PublicRoomsRequest publicRoomsRequest);
468}