@@ -196,6 +196,7 @@ export abstract class WidgetDriver {
196
196
* the client will return all the events.
197
197
* @param eventType The event type to be read.
198
198
* @param msgtype The msgtype of the events to be read, if applicable/defined.
199
+ * @param stateKey The state key of the events to be read, if applicable/defined.
199
200
* @param limit The maximum number of events to retrieve per room. Will be zero to denote "as many
200
201
* as possible".
201
202
* @param roomIds When null, the user's currently viewed room. Otherwise, the list of room IDs
@@ -204,6 +205,7 @@ export abstract class WidgetDriver {
204
205
* Otherwise, the event ID at which only subsequent events will be returned, as many as specified
205
206
* in "limit".
206
207
* @returns {Promise<IRoomEvent[]> } Resolves to the room events, or an empty array.
208
+ * @deprecated Clients are advised to implement {@link WidgetDriver.readRoomTimeline} instead.
207
209
*/
208
210
public readRoomEvents (
209
211
eventType : string ,
@@ -229,6 +231,7 @@ export abstract class WidgetDriver {
229
231
* @param roomIds When null, the user's currently viewed room. Otherwise, the list of room IDs
230
232
* to look within, possibly containing Symbols.AnyRoom to denote all known rooms.
231
233
* @returns {Promise<IRoomEvent[]> } Resolves to the state events, or an empty array.
234
+ * @deprecated Clients are advised to implement {@link WidgetDriver.readRoomTimeline} instead.
232
235
*/
233
236
public readStateEvents (
234
237
eventType : string ,
@@ -239,6 +242,53 @@ export abstract class WidgetDriver {
239
242
return Promise . resolve ( [ ] ) ;
240
243
}
241
244
245
+ /**
246
+ * Reads all events of the given type, and optionally `msgtype` (if applicable/defined),
247
+ * the user has access to. The widget API will have already verified that the widget is
248
+ * capable of receiving the events. Less events than the limit are allowed to be returned,
249
+ * but not more.
250
+ * @param roomId The ID of the room to look within.
251
+ * @param eventType The event type to be read.
252
+ * @param msgtype The msgtype of the events to be read, if applicable/defined.
253
+ * @param stateKey The state key of the events to be read, if applicable/defined.
254
+ * @param limit The maximum number of events to retrieve. Will be zero to denote "as many as
255
+ * possible".
256
+ * @param since When null, retrieves the number of events specified by the "limit" parameter.
257
+ * Otherwise, the event ID at which only subsequent events will be returned, as many as specified
258
+ * in "limit".
259
+ * @returns {Promise<IRoomEvent[]> } Resolves to the room events, or an empty array.
260
+ */
261
+ public readRoomTimeline (
262
+ roomId : string ,
263
+ eventType : string ,
264
+ msgtype : string | undefined ,
265
+ stateKey : string | undefined ,
266
+ limit : number ,
267
+ since : string | undefined ,
268
+ ) : Promise < IRoomEvent [ ] > {
269
+ // For backward compatibility we try the deprecated methods, in case
270
+ // they're implemented
271
+ if ( stateKey === undefined ) return this . readRoomEvents ( eventType , msgtype , limit , [ roomId ] , since ) ;
272
+ else return this . readStateEvents ( eventType , stateKey , limit , [ roomId ] ) ;
273
+ }
274
+
275
+ /**
276
+ * Reads the current values of all matching room state entries.
277
+ * @param roomId The ID of the room.
278
+ * @param eventType The event type of the entries to be read.
279
+ * @param stateKey The state key of the entry to be read. If undefined,
280
+ * all room state entries with a matching event type should be returned.
281
+ * @returns {Promise<IRoomEvent[]> } Resolves to the events representing the
282
+ * current values of the room state entries.
283
+ */
284
+ public readRoomState (
285
+ roomId : string ,
286
+ eventType : string ,
287
+ stateKey : string | undefined ,
288
+ ) : Promise < IRoomEvent [ ] > {
289
+ return Promise . resolve ( [ ] ) ;
290
+ }
291
+
242
292
/**
243
293
* Reads all events that are related to a given event. The widget API will
244
294
* have already verified that the widget is capable of receiving the event,
@@ -360,6 +410,15 @@ export abstract class WidgetDriver {
360
410
throw new Error ( "Download file is not implemented" ) ;
361
411
}
362
412
413
+ /**
414
+ * Gets the IDs of all joined or invited rooms currently known to the
415
+ * client.
416
+ * @returns The room IDs.
417
+ */
418
+ public getKnownRooms ( ) : string [ ] {
419
+ throw new Error ( "Querying known rooms is not implemented" ) ;
420
+ }
421
+
363
422
/**
364
423
* Expresses an error thrown by this driver in a format compatible with the Widget API.
365
424
* @param error The error to handle.
0 commit comments