add request_directory() for file transfer

Author: f0rw4rd

c104/__init__.pyi

@@ -933,6 +933,30 @@ class Connection:
         >>> if not my_connection.test(common_address=47):
         >>>     raise ValueError("Cannot send test command")
         """
+    def request_directory(self, common_address: int, ioa: int = 0, wait_for_response: bool = True) -> bool:
+        """
+        send a file directory request to the remote terminal unit (server)
+        sends F_SC_NA_1 (Type 122) with SCQ=0
+
+        Parameters
+        ----------
+        common_address: int
+            station common address
+        ioa: int
+            information object address (default 0)
+        wait_for_response: bool
+            block call until response received?
+
+        Returns
+        -------
+        bool
+            True, if request sent successfully
+
+        Example
+        -------
+        >>> if my_connection.request_directory(common_address=1):
+        >>>     print("Directory request sent")
+        """
     def unmute(self) -> bool:
         """
         tell the remote terminal unit (server) that this connection is not muted, allow monitoring messages

src/python.cpp

@@ -2393,6 +2393,34 @@ Example
 )def",
           "common_address"_a, "with_time"_a = true,
           "wait_for_response"_a = true, py::return_value_policy::copy)
+      .def(
+          "request_directory", &Remote::Connection::requestDirectory,
+          R"def(request_directory(self: c104.Connection, common_address: int, ioa: int = 0, wait_for_response: bool = True) -> bool
+
+send a file directory request to the remote terminal unit (server)
+sends F_SC_NA_1 (Type 122) with SCQ=0
+
+Parameters
+----------
+common_address: int
+    station common address
+ioa: int
+    information object address (default 0)
+wait_for_response: bool
+    block call until response received?
+
+Returns
+-------
+bool
+    True, if request sent successfully
+
+Example
+-------
+>>> if my_connection.request_directory(common_address=1):
+>>>     print("Directory request sent")
+)def",
+          "common_address"_a, "ioa"_a = 0, "wait_for_response"_a = true,
+          py::return_value_policy::copy)
       .def(
           "add_station", &Remote::Connection::addStation,
           R"def(add_station(self: c104.Connection, common_address: int) -> c104.Station | None

src/remote/Connection.cpp

@@ -932,6 +932,51 @@ bool Connection::test(std::uint_fast16_t commonAddress, bool with_time,
   return result;
 }
 
+bool Connection::requestDirectory(std::uint_fast16_t commonAddress,
+                                  std::uint_fast32_t ioa,
+                                  const bool wait_for_response) {
+  Module::ScopedGilRelease const scoped("Connection.requestDirectory");
+
+  if (!isOpen())
+    return false;
+
+  std::string const cmdId =
+      std::to_string(commonAddress) + "-F_SC_NA_1-" + std::to_string(ioa);
+  if (wait_for_response) {
+    prepareCommandSuccess(cmdId, COMMAND_AWAIT_CON_TERM);
+  }
+
+  // Create ASDU for directory request (F_SC_NA_1, Type 122)
+  std::unique_lock<Module::GilAwareMutex> lock(connection_mutex);
+  CS101_AppLayerParameters alParams =
+      CS104_Connection_getAppLayerParameters(connection);
+
+  CS101_ASDU asdu =
+      CS101_ASDU_create(alParams, false, CS101_COT_FILE_TRANSFER, 0,
+                        static_cast<int>(commonAddress), false, false);
+
+  // Create FileCallOrSelect information object
+  // SCQ = 0 means "select directory"
+  FileCallOrSelect io =
+      FileCallOrSelect_create(NULL, static_cast<int>(ioa), 0, 0, 0);
+
+  CS101_ASDU_addInformationObject(asdu, (InformationObject)io);
+  InformationObject_destroy((InformationObject)io);
+
+  bool const result = CS104_Connection_sendASDU(connection, asdu);
+  lock.unlock();
+
+  CS101_ASDU_destroy(asdu);
+
+  if (wait_for_response) {
+    if (result) {
+      return awaitCommandSuccess(cmdId);
+    }
+    cancelCommandSuccess(cmdId);
+  }
+  return result;
+}
+
 bool Connection::transmit(std::shared_ptr<Object::DataPoint> point,
                           const CS101_CauseOfTransmission cause) {
   auto type = point->getType();

src/remote/Connection.h

@@ -393,6 +393,17 @@ class Connection : public std::enable_shared_from_this<Connection> {
   bool test(std::uint_fast16_t commonAddress, bool with_time = true,
             bool wait_for_response = true);
 
+  /**
+   * @brief request file directory listing from server
+   * @param commonAddress station address
+   * @param ioa information object address (default 0)
+   * @param wait_for_response blocking or non-blocking
+   * @return success information
+   */
+  bool requestDirectory(std::uint_fast16_t commonAddress,
+                        std::uint_fast32_t ioa = 0,
+                        bool wait_for_response = true);
+
   /**
    * @brief transmit a command to a remote server
    * @param point control point