getSpaceHierarchy method

Future<GetSpaceHierarchyResponse> getSpaceHierarchy(String roomId, { bool? suggestedOnly, int? limit, int? maxDepth, String? from, })

Paginates over the space tree in a depth-first manner to locate child rooms of a given space.

Where a child room is unknown to the local server, federation is used to fill in the details. The servers listed in the via array should be contacted to attempt to fill in missing rooms.

Only m.space.child state events of the room are considered. Invalid child rooms and parent events are not covered by this endpoint.

roomId The room ID of the space to get a hierarchy for.

suggestedOnly Optional (default false) flag to indicate whether or not the server should only consider suggested rooms. Suggested rooms are annotated in their m.space.child event contents.

limit Optional limit for the maximum number of rooms to include per response. Must be an integer greater than zero.

Servers should apply a default value, and impose a maximum value to avoid resource exhaustion.

maxDepth Optional limit for how far to go into the space. Must be a non-negative integer.

When reached, no further child rooms will be returned.

Servers should apply a default value, and impose a maximum value to avoid resource exhaustion.

from A pagination token from a previous result. If specified, max_depth and suggested_only cannot be changed from the first request.

Implementation

Future<GetSpaceHierarchyResponse> getSpaceHierarchy(
  String roomId, {
  bool? suggestedOnly,
  int? limit,
  int? maxDepth,
  String? from,
}) async {
  final requestUri = Uri(
    path: '_matrix/client/v1/rooms/${Uri.encodeComponent(roomId)}/hierarchy',
    queryParameters: {
      if (suggestedOnly != null) 'suggested_only': suggestedOnly.toString(),
      if (limit != null) 'limit': limit.toString(),
      if (maxDepth != null) 'max_depth': maxDepth.toString(),
      if (from != null) 'from': from,
    },
  );
  final request = Request('GET', baseUri!.resolveUri(requestUri));
  request.headers['authorization'] = 'Bearer ${bearerToken!}';
  final response = await httpClient.send(request);
  final responseBody = await response.stream.toBytes();
  if (response.statusCode != 200) unexpectedResponse(response, responseBody);
  final responseString = utf8.decode(responseBody);
  final json = jsonDecode(responseString);
  return GetSpaceHierarchyResponse.fromJson(json as Map<String, Object?>);
}