fix: handle CardTerminalException in PcscReaderAdapter error handling

CMakeLists.txt

@@ -13,11 +13,11 @@
 
 CMAKE_MINIMUM_REQUIRED(VERSION 3.25)
 PROJECT(KeyplePluginPcscCppLib
-        VERSION 2.4.2
+        VERSION 2.5.2
         LANGUAGES C CXX)
 
 SET(CMAKE_PROJECT_VERSION_MAJOR "2")
-SET(CMAKE_PROJECT_VERSION_MINOR "4")
+SET(CMAKE_PROJECT_VERSION_MINOR "5")
 SET(CMAKE_PROJECT_VERSION_PATCH "2")
 
 SET(CMAKE_PROJECT_VERSION "${CMAKE_PROJECT_VERSION_MAJOR}.

include/keyple/plugin/pcsc/PcscCardCommunicationProtocol.hpp

@@ -0,0 +1,170 @@
+/******************************************************************************
+ * Copyright (c) 2025 Calypso Networks Association https://calypsonet.org/    *
+ *                                                                            *
+ * See the NOTICE file(s) distributed with this work for additional           *
+ * information regarding copyright ownership.                                 *
+ *                                                                            *
+ * This program and the accompanying materials are made available under the   *
+ * terms of the Eclipse Public License 2.0 which is available at              *
+ * http://www.eclipse.org/legal/epl-2.0                                       *
+ *                                                                            *
+ * SPDX-License-Identifier: EPL-2.0                                           *
+ ******************************************************************************/
+
+#pragma once
+
+#include <cstdint>
+#include <string>
+
+namespace keyple {
+namespace plugin {
+namespace pcsc {
+
+/**
+ * List of contactless protocols and technologies identifiable through PC/SC
+ * readers.
+ *
+ * <p>Each enum value associates a protocol or technology with a specific ATR
+ * pattern. These patterns follow the PC/SC standard Part 3 for contactless card
+ * identification.
+ *
+ * <p>The ATR patterns can identify both physical cards and virtual cards
+ * emulated by NFC devices.
+ *
+ * <p>See <a href="https://pcscworkgroup.com/">PC/SC Workgroup</a> for more
+ * details.
+ *
+ * @since 2.5.0
+ */
+class PcscCardCommunicationProtocol {
+public:
+    /**
+     * Any ISO 14443-4 compliant card or device (both Type A and Type B).
+     *
+     * <p>According to PC/SC specifications, ISO 14443-4 contactless cards have
+     * a specific ATR structure:
+     *
+     * <ul>
+     *   <li>TS (Initial character): 0x3B - Direct convention
+     *   <li>T0 (Format character): 0x8X - Where X varies based on the number of
+     *       historical bytes
+     *   <li>TD1: 0x80 - Indicates protocol T=0 at first level and presence of
+     *       TD2
+     *   <li>TD2: 0x01 - Indicates final protocol T=1
+     * </ul>
+     *
+     * <p>This structure allows for recognition of both Type A and Type B ISO
+     * 14443-4 cards, regardless of the number of historical bytes they contain.
+     *
+     * <p>Excludes Innovatron B Prime cards which have their own specific
+     * category.
+     *
+     * <p>Default rule =
+     * <b>{@code 3B8[0-9A-F]8001(?!.*5A0A)(?!804F0CA000000306).*}</b>
+     *
+     * @since 2.5.0
+     */
+    static const PcscCardCommunicationProtocol ISO_14443_4;
+
+    /**
+     * Calypso cards using Innovatron B Prime protocol.
+     *
+     * <p>According to PC/SC Part 3, B Prime cards use a specific ATR format:
+     *
+     * <ul>
+     *   <li>Starting with 3B8 followed by any hex digit - Indicating direct
+     *       convention with a variable number of historical bytes
+     *   <li>Followed by 8001 - Indicating TD1=0x80 and TD2=0x01 (protocol T=1)
+     *   <li>Followed immediately by the specific B Prime signature 5A0A in the
+     *       first historical bytes
+     * </ul>
+     *
+     * <p>Default rule = <b>{@code 3B8.8001(80)?5A0A.*}</b>
+     *
+     * @since 2.5.0
+     */
+    static const PcscCardCommunicationProtocol INNOVATRON_B_PRIME;
+
+    /**
+     * NXP MIFARE Ultralight technologies.
+     *
+     * <p>According to PC/SC Part 3 Supplemental Document:
+     *
+     * <ul>
+     *   <li>Initial bytes: 3B8F8001804F0CA0000003
+     *   <li>Card protocol: 0603 (ISO 14443 A part 3)
+     *   <li>Card type: 0003 (for Mifare UL)
+     * </ul>
+     *
+     * <p>Default rule = <b>{@code 3B8F8001804F0CA0000003060300030.*}</b>
+     *
+     * @since 2.5.0
+     */
+    static const PcscCardCommunicationProtocol MIFARE_ULTRALIGHT;
+
+    /**
+     * STMicroelectronics ST25/SRT512 memory tags.
+     *
+     * <p>According to PC/SC Part 3 Supplemental Document:
+     *
+     * <ul>
+     *   <li>Initial bytes: 3B8F8001804F0CA0000003
+     *   <li>Card protocol: 0605, 0606, 0607 (ISO 14443 B part 1/2/3)
+     *   <li>Card type: 0007 (ST25 tag)
+     * </ul>
+     *
+     * <p>Default rule = <b>{@code 3B8F8001804F0CA0000003060(5|6|7)0007.*}</b>
+     *
+     * @since 2.5.0
+     */
+    static const PcscCardCommunicationProtocol ST25_SRT512;
+
+    /**
+     * ISO 7816-3 Card (contact communication protocol)
+     *
+     * <p>Default rule = <b>{@code 3.*}</b>
+     *
+     * @since 2.5.0
+     */
+    static const PcscCardCommunicationProtocol ISO_7816_3;
+
+    /**
+     *
+     */
+    const std::string&
+    getName() const;
+
+    /**
+     * (private-package)<br>
+     * Gets the default rule associated to the protocol.
+     *
+     * @return The regular expression pattern as a String
+     * @since 2.0.0
+     */
+    const std::string&
+    getDefaultRule() const;
+
+private:
+    /**
+     *
+     */
+    const std::string mName;
+
+    /**
+     *
+     */
+    const std::string mDefaultRule;
+
+    /**
+     * Constructor
+     *
+     * @param name The protocol name.
+     * @param defaultRule The default rule as a regular expression pattern.
+     */
+    PcscCardCommunicationProtocol(
+        const std::string& name, const std::string& defaultRule);
+};
+
+} /* namespace pcsc */
+} /* namespace plugin */
+} /* namespace keyple */

include/keyple/plugin/pcsc/PcscPlugin.hpp

@@ -34,6 +34,6 @@ class PcscPlugin : public KeyplePluginExtension {
     virtual ~PcscPlugin() = default;
 };
 
-}
-}
-}
+} /* namespace pcsc */
+} /* namespace plugin */
+} /* namespace keyple */

include/keyple/plugin/pcsc/PcscPluginAdapter.hpp

@@ -26,6 +26,7 @@
 #include "keyple/plugin/pcsc/PcscPlugin.hpp"
 #include "keyple/plugin/pcsc/PcscReaderAdapter.hpp"
 #include "keyple/plugin/pcsc/cpp/CardTerminal.hpp"
+#include "keyple/plugin/pcsc/cpp/CardTerminals.hpp"
 
 namespace keyple {
 namespace plugin {
@@ -37,6 +38,7 @@ using keyple::core::util::cpp::Logger;
 using keyple::core::util::cpp::LoggerFactory;
 using keyple::core::util::cpp::Pattern;
 using keyple::plugin::pcsc::cpp::CardTerminal;
+using keyple::plugin::pcsc::cpp::CardTerminals;
 
 class PcscReaderAdapter;
 
@@ -215,6 +217,11 @@ class PcscPluginAdapter final
      */
     std::map<std::string, std::string> mProtocolRulesMap;
 
+    /**
+     *
+     */
+    std::shared_ptr<CardTerminals> mTerminals;
+
     /**
      *
      */

include/keyple/plugin/pcsc/PcscPluginFactoryBuilder.hpp

@@ -35,15 +35,14 @@ using keyple::core::util::cpp::Pattern;
  * method PcscReader#setContactless(bool). <br>
  * A set of default protocol identification rules is also proposed.
  *
- * @see PcscSupportedContactProtocol
- * @see PcscSupportedContactlessProtocol
+ * @see PcscCardCommunicationProtocol
  * @since 2.0.0
  */
 class KEYPLEPLUGINPCSC_API PcscPluginFactoryBuilder final {
 public:
 
     /**
-     * Builder to build a {@link PcscPluginFactory}.
+     * Builder to build a PcscPluginFactory.
      *
      * @since 2.0.0
      */

include/keyple/plugin/pcsc/PcscReader.hpp

@@ -140,18 +140,49 @@ class KEYPLEPLUGINPCSC_API PcscReader : public KeypleReaderExtension {
      */
     enum class DisconnectionMode {
         /**
-         * Resets the card
+         * Resets the card. This sends a reset signal to the card while keeping
+         * the connection alive.
          *
+         * <p>Corresponds to PC/SC `SCARD_RESET_CARD`.
          * @since 2.0.0
          */
         RESET,
 
         /**
-         * Keeps the status of the card unchanged
+         * Leaves the card in its current state without performing any reset or
+         * power down.
+         *
+         * <p>Corresponds to PC/SC `SCARD_LEAVE_CARD`.
          *
          * @since 2.0.0
          */
-        LEAVE
+        LEAVE,
+
+        /**
+         * Completely powers off the card.
+         *
+         * <p>Corresponds to PC/SC `SCARD_UNPOWER_CARD`.
+         *
+         * <p>This mode is only available with the default security provider.
+         * Depending on the provider used, a runtime error may occur during
+         * eader enumeration.
+         *
+         * @since 2.5.0
+         */
+        UNPOWER,
+
+        /**
+         * Ejects the card (if supported by the reader).
+         *
+         * <p>Corresponds to PC/SC `SCARD_EJECT_CARD`.
+         *
+         * <p>This mode is only available with the default security provider.
+         * Depending on the provider used, a runtime error may occur during
+         * reader enumeration.
+         *
+         * @since 2.5.0
+         */
+        EJECT
     };
 
     /**
@@ -274,6 +305,25 @@ class KEYPLEPLUGINPCSC_API PcscReader : public KeypleReaderExtension {
     friend std::ostream& operator<<(std::ostream& os, const DisconnectionMode dm);
 };
 
+/**
+ *
+ */
+inline std::string operator+(std::string str, const PcscReader::DisconnectionMode dm)
+{
+    switch (dm) {
+    case PcscReader::DisconnectionMode::RESET:
+        return str + "RESET";
+    case PcscReader::DisconnectionMode::LEAVE:
+        return str + "LEAVE";
+    case PcscReader::DisconnectionMode::UNPOWER:
+        return str + "UNPOWER";
+    case PcscReader::DisconnectionMode::EJECT:
+        return str + "EJECT";
+    default:
+        return str + "UNKNOWN";
+    }
+}
+
 } /* namespace pcsc */
 } /* namespace plugin */
 } /* namespace keyple */