feat: add support for query parameters to exploreDirectory method

example/directory_discovery.dart

@@ -0,0 +1,31 @@
+// Copyright 2024 Contributors to the Eclipse Foundation. All rights reserved.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+//
+// SPDX-License-Identifier: BSD-3-Clause
+
+// ignore_for_file: avoid_print
+
+import "package:dart_wot/binding_http.dart";
+import "package:dart_wot/core.dart";
+
+Future<void> main(List<String> args) async {
+  final servient = Servient(
+    clientFactories: [
+      HttpClientFactory(),
+    ],
+  );
+  final wot = await servient.start();
+  final url = Uri.parse("http://192.168.102.23:9001/.well-known/wot");
+
+  final thingDiscovery = await wot.exploreDirectory(
+    url,
+    limit: 1,
+    offset: 2,
+    format: DirectoryPayloadFormat.collection,
+  );
+
+  await for (final thingDescription in thingDiscovery) {
+    print(thingDescription);
+  }
+}

lib/src/core/implementation/wot.dart

@@ -111,9 +111,12 @@ class WoT implements scripting_api.WoT {
 
   @override
   Future<scripting_api.ThingDiscoveryProcess> exploreDirectory(
-    Uri url, [
+    Uri url, {
     scripting_api.ThingFilter? filter,
-  ]) async {
+    int? offset,
+    int? limit,
+    scripting_api.DirectoryPayloadFormat? format,
+  }) async {
     final thingDescription = await requestThingDescription(url);
 
     if (!thingDescription.isValidDirectoryThingDescription) {
@@ -124,8 +127,14 @@ class WoT implements scripting_api.WoT {
 
     final consumedDirectoryThing = await consume(thingDescription);
 
-    final interactionOutput =
-        await consumedDirectoryThing.readProperty("things");
+    final interactionOutput = await consumedDirectoryThing.readProperty(
+      "things",
+      uriVariables: {
+        if (offset != null) "offset": offset,
+        if (limit != null) "limit": limit,
+        if (format != null) "format": format.toString(),
+      },
+    );
     final rawThingDescriptions = await interactionOutput.value();
 
     if (rawThingDescriptions is! List<Object?>) {

lib/src/core/scripting_api/wot.dart

@@ -13,6 +13,35 @@ import "discovery/thing_filter.dart";
 import "exposed_thing.dart";
 import "types.dart";
 
+/// Enumeration for specifying the value of the `format` query parameter when
+/// using the `exploreDirectory` discovery method.
+///
+/// See [section 7.3.2.1.5] of the [WoT Discovery] specification for more
+/// information.
+///
+/// [WoT Discovery]: https://www.w3.org/TR/2023/REC-wot-discovery-20231205
+/// [section 7.3.2.1.5]: https://www.w3.org/TR/2023/REC-wot-discovery-20231205/#exploration-directory-api-things-listing
+enum DirectoryPayloadFormat {
+  /// Indicates that an array of Thing Descriptions should be returned.
+  ///
+  /// This is the default value.
+  array,
+
+  /// Indicates that an collection of Thing Descriptions should be returned.
+  collection,
+  ;
+
+  @override
+  String toString() {
+    switch (this) {
+      case array:
+        return "array";
+      case collection:
+        return "collection";
+    }
+  }
+}
+
 /// Interface for a [WoT] runtime.
 ///
 /// See WoT Scripting API specification,
@@ -39,9 +68,12 @@ abstract interface class WoT {
   /// [ThingDescription] objects for Thing Descriptions that match an optional
   /// [filter] argument of type [ThingFilter].
   Future<ThingDiscoveryProcess> exploreDirectory(
-    Uri url, [
+    Uri url, {
     ThingFilter? filter,
-  ]);
+    int? offset,
+    int? limit,
+    DirectoryPayloadFormat? format,
+  });
 
   /// Discovers [ThingDescription]s from a given [url] using the specified
   /// [method].