add file_select() for IEC 104 file transfer

Author: f0rw4rd

c104/__init__.pyi

@@ -933,6 +933,31 @@ class Connection:
         >>> if not my_connection.test(common_address=47):
         >>>     raise ValueError("Cannot send test command")
         """
+    def file_select(self, common_address: int, ioa: int, wait_for_response: bool = True) -> bool:
+        """
+        select a file on the remote terminal unit (server) for transfer
+        sends F_SC_NA_1 (Type 122) with SCQ=1 (SELECT_FILE)
+        server responds with F_FR_NA_1 (Type 120 - FILE_READY)
+
+        Parameters
+        ----------
+        common_address: int
+            station common address
+        ioa: int
+            information object address of the file
+        wait_for_response: bool
+            block call until response received?
+
+        Returns
+        -------
+        bool
+            True, if file selection successful
+
+        Example
+        -------
+        >>> if my_connection.file_select(common_address=1, ioa=30000):
+        >>>     print("File selected successfully")
+        """
     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,35 @@ Example
 )def",
           "common_address"_a, "with_time"_a = true,
           "wait_for_response"_a = true, py::return_value_policy::copy)
+      .def(
+          "file_select", &Remote::Connection::fileSelect,
+          R"def(file_select(self: c104.Connection, common_address: int, ioa: int, wait_for_response: bool = True) -> bool
+
+select a file on the remote terminal unit (server) for transfer
+sends F_SC_NA_1 (Type 122) with SCQ=1 (SELECT_FILE)
+server responds with F_FR_NA_1 (Type 120 - FILE_READY)
+
+Parameters
+----------
+common_address: int
+    station common address
+ioa: int
+    information object address of the file
+wait_for_response: bool
+    block call until response received?
+
+Returns
+-------
+bool
+    True, if file selection successful
+
+Example
+-------
+>>> if my_connection.file_select(common_address=1, ioa=30000):
+>>>     print("File selected successfully")
+)def",
+          "common_address"_a, "ioa"_a, "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::fileSelect(std::uint_fast16_t commonAddress,
+                            std::uint_fast32_t ioa,
+                            const bool wait_for_response) {
+  Module::ScopedGilRelease const scoped("Connection.fileSelect");
+
+  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 = 1 means "select file" (CS101_SCQ_SELECT_FILE)
+  FileCallOrSelect io =
+      FileCallOrSelect_create(NULL, static_cast<int>(ioa), CS101_NOF_TRANSPARENT_FILE, 0, 1);
+
+  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 select a file on remote server for transfer
+   * @param commonAddress station address
+   * @param ioa information object address of the file
+   * @param wait_for_response blocking or non-blocking
+   * @return success information
+   */
+  bool fileSelect(std::uint_fast16_t commonAddress,
+                  std::uint_fast32_t ioa,
+                  bool wait_for_response = true);
+
   /**
    * @brief transmit a command to a remote server
    * @param point control point