Add source code location to exceptions, minor refactoring

Author: mrts

CMakeLists.txt

@@ -10,6 +10,7 @@ project(pcsc-cpp)
 add_library(${PROJECT_NAME}
   STATIC
   include/${PROJECT_NAME}/${PROJECT_NAME}.hpp
+  include/${PROJECT_NAME}/${PROJECT_NAME}-utils.hpp
   include/${PROJECT_NAME}/comp_winscard.hpp
   include/flag-set-cpp/flag_set.hpp
   include/magic_enum/magic_enum.hpp

include/pcsc-cpp/pcsc-cpp-utils.hpp

@@ -0,0 +1,59 @@
+/*
+ * Copyright (c) 2020 The Web eID Project
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+
+#pragma once
+
+#include <string>
+#include <sstream>
+#include <iomanip>
+
+namespace pcsc_cpp
+{
+
+/** Convert the given integer to a hex string. */
+template <typename T>
+inline std::string int2hexstr(const T value)
+{
+    std::ostringstream hexStringBuilder;
+
+    hexStringBuilder << "0x" << std::setfill('0') << std::setw(sizeof(long) * 2) << std::hex
+                     << value;
+
+    return hexStringBuilder.str();
+}
+
+/** Remove absolute path prefix until "src" from the given path, '/path/to/src/main.cpp' becomes
+ * 'src/main.cpp'. */
+inline std::string removeAbsolutePathPrefix(const std::string& filePath)
+{
+    const auto lastSrc = filePath.rfind("src");
+    return lastSrc == std::string::npos ? filePath : filePath.substr(lastSrc);
+}
+
+} // namespace pcsc_cpp
+
+#define THROW_WITH_CALLER_INFO(ExceptionType, message, file, line, func)                           \
+    throw ExceptionType(std::string(message) + " in " + pcsc_cpp::removeAbsolutePathPrefix(file)   \
+                        + ':' + std::to_string(line) + ':' + func)
+
+#define THROW(ExceptionType, message)                                                              \
+    THROW_WITH_CALLER_INFO(ExceptionType, message, __FILE__, __LINE__, __func__)

include/pcsc-cpp/pcsc-cpp.hpp

@@ -331,18 +331,39 @@ class ScardError : public Error
     using Error::Error;
 };
 
-/** Raised when the PC/SC service is not running. */
-class ScardServiceNotRunning : public ScardError
+/** Thrown when the PC/SC service is not running. */
+class ScardServiceNotRunningError : public ScardError
 {
 public:
     using ScardError::ScardError;
 };
 
-/** Raised when no card readers are connected to the system. */
+/** Thrown when no card readers are connected to the system. */
 class ScardNoReadersError : public ScardError
 {
 public:
     using ScardError::ScardError;
 };
 
+/** Thrown when no card is connected to the selected reader. */
+class ScardNoCardError : public ScardError
+{
+public:
+    using ScardError::ScardError;
+};
+
+/** Thrown when the card is removed from the selected reader. */
+class ScardCardRemovedError : public ScardError
+{
+public:
+    using ScardError::ScardError;
+};
+
+/** Thrown when the card transaction fails. */
+class ScardTransactionFailedError : public ScardError
+{
+public:
+    using ScardError::ScardError;
+};
+
 } // namespace pcsc_cpp

src/Context.hpp

@@ -23,6 +23,7 @@
 #pragma once
 
 #include "pcsc-cpp/pcsc-cpp.hpp"
+#include "pcsc-cpp/pcsc-cpp-utils.hpp"
 
 #include "SCardCall.hpp"
 
@@ -38,8 +39,9 @@ class Context
     {
         SCard(EstablishContext, SCARD_SCOPE_USER, nullptr, nullptr, &contextHandle);
         if (!contextHandle) {
-            throw ScardError("Context:SCardEstablishContext: service unavailable "
-                             "(null context handle)");
+            THROW(ScardError,
+                  "Context:SCardEstablishContext: service unavailable "
+                  "(null context handle)");
         }
     }
 

src/SCardCall.hpp

@@ -22,29 +22,27 @@
 
 #pragma once
 
+#include "pcsc-cpp/pcsc-cpp.hpp"
 #include "pcsc-cpp/comp_winscard.hpp"
+#include "pcsc-cpp/pcsc-cpp-utils.hpp"
 
 #include <string>
 
 namespace pcsc_cpp
 {
 
 inline std::string buildErrorMessage(const char* callerFunctionName, const char* scardFunctionName,
-                                     const LONG result)
+                                     const LONG result, const char* file, int line)
 {
-    return std::string(callerFunctionName) + ':' + scardFunctionName + ": "
-        + std::to_string(result);
+    return std::string(scardFunctionName) + " returned " + int2hexstr(result) + " in "
+        + removeAbsolutePathPrefix(file) + ':' + std::to_string(line) + ':' + callerFunctionName;
 }
 
 template <typename Func, typename... Args>
 void SCardCall(const char* callerFunctionName, const char* file, int line,
                const char* scardFunctionName, Func scardFunction, Args... args)
 {
-    // TODO: Add logging, for example:
-    // DEBUG(callerFunctionName, file, line, "%s: %s (0x%08x)", scardFunctionName,
-    //       pcsc_stringify_error(result), result);
-    (void)file;
-    (void)line;
+    // TODO: Add logging - or is exception error message enough?
     const uint32_t result = scardFunction(args...);
 
     // TODO: Add more cases when needed.
@@ -53,12 +51,23 @@ void SCardCall(const char* callerFunctionName, const char* file, int line,
         return;
     case SCARD_E_NO_SERVICE:
     case SCARD_E_SERVICE_STOPPED:
-        throw ScardServiceNotRunning(
-            buildErrorMessage(callerFunctionName, scardFunctionName, result));
+        throw ScardServiceNotRunningError(
+            buildErrorMessage(callerFunctionName, scardFunctionName, result, file, line));
     case SCARD_E_NO_READERS_AVAILABLE:
-        throw ScardNoReadersError(buildErrorMessage(callerFunctionName, scardFunctionName, result));
+        throw ScardNoReadersError(
+            buildErrorMessage(callerFunctionName, scardFunctionName, result, file, line));
+    case SCARD_E_NO_SMARTCARD:
+        throw ScardNoCardError(
+            buildErrorMessage(callerFunctionName, scardFunctionName, result, file, line));
+    case SCARD_W_REMOVED_CARD:
+        throw ScardCardRemovedError(
+            buildErrorMessage(callerFunctionName, scardFunctionName, result, file, line));
+    case SCARD_E_NOT_TRANSACTED:
+        throw ScardTransactionFailedError(
+            buildErrorMessage(callerFunctionName, scardFunctionName, result, file, line));
     default:
-        throw ScardError(buildErrorMessage(callerFunctionName, scardFunctionName, result));
+        throw ScardError(
+            buildErrorMessage(callerFunctionName, scardFunctionName, result, file, line));
     }
 }
 

src/SmartCard.cpp

@@ -50,7 +50,7 @@ inline SmartCard::Protocol convertToSmartCardProtocol(const DWORD protocol)
     case SCARD_PROTOCOL_T1:
         return SmartCard::Protocol::T1;
     default:
-        throw Error("Invalid card protocol: " + std::to_string(protocol));
+        THROW(Error, "Invalid card protocol: " + std::to_string(protocol));
     }
 }
 
@@ -63,9 +63,6 @@ std::pair<SCARDHANDLE, DWORD> connectToCard(const SCARDCONTEXT ctx, const string
 
     SCard(Connect, ctx, readerName.c_str(), SCARD_SHARE_SHARED, requestedProtocol, &cardHandle,
           &protocolOut);
-    // TODO: Handle SCARD_E_PROTO_MISMATCH?
-    // TODO: if (requestedProtocol != protocolOut) throw Error? What about Protocol::AUTO?
-    // TODO: reconnect needed under certain circumstances.
 
     return std::pair<SCARDHANDLE, DWORD> {cardHandle, protocolOut};
 }
@@ -188,7 +185,7 @@ class CardImpl
     ResponseApdu toResponse(byte_vector& responseBytes, size_t responseLength) const
     {
         if (responseLength > responseBytes.size()) {
-            throw Error("SCardTransmit: received more bytes than buffer size");
+            THROW(Error, "SCardTransmit: received more bytes than buffer size");
         }
         responseBytes.resize(responseLength);
 
@@ -208,12 +205,13 @@ class CardImpl
         case ResponseApdu::WRONG_LE_LENGTH: // See next if block.
             break;
         default:
-            throw Error("Error response: '" + bytes2hexstr({response.sw1, response.sw2})
-                        + "', protocol " + std::to_string(protocol()));
+            THROW(Error,
+                  "Error response: '" + bytes2hexstr({response.sw1, response.sw2}) + "', protocol "
+                      + std::to_string(protocol()));
         }
 
         if (response.sw1 == ResponseApdu::WRONG_LE_LENGTH) {
-            throw Error("Wrong LE length (SW1=0x6C) in response, please set LE");
+            THROW(Error, "Wrong LE length (SW1=0x6C) in response, please set LE");
         }
 
         return response;
@@ -274,7 +272,7 @@ bool SmartCard::readerHasPinPad() const
 ResponseApdu SmartCard::transmit(const CommandApdu& command) const
 {
     if (!transactionInProgress) {
-        throw std::logic_error("Call SmartCard::transmit() inside a transaction");
+        THROW(std::logic_error, "Call SmartCard::transmit() inside a transaction");
     }
 
     return card->transmitBytes(command.toBytes());
@@ -283,7 +281,7 @@ ResponseApdu SmartCard::transmit(const CommandApdu& command) const
 ResponseApdu SmartCard::transmitCTL(const CommandApdu& command, uint16_t lang, uint8_t minlen) const
 {
     if (!transactionInProgress) {
-        throw std::logic_error("Call SmartCard::transmit() inside a transaction");
+        THROW(std::logic_error, "Call SmartCard::transmit() inside a transaction");
     }
 
     return card->transmitBytesCTL(command.toBytes(), lang, minlen);

src/utils.cpp

@@ -21,6 +21,7 @@
  */
 
 #include "pcsc-cpp/pcsc-cpp.hpp"
+#include "pcsc-cpp/pcsc-cpp-utils.hpp"
 
 #include <sstream>
 #include <iomanip>
@@ -55,11 +56,13 @@ class UnexpectedResponseError : public Error
 public:
     explicit UnexpectedResponseError(const CommandApdu& command,
                                      const byte_vector& expectedResponseBytes,
-                                     const ResponseApdu& response) :
+                                     const ResponseApdu& response, const char* file, const int line,
+                                     const char* callerFunctionName) :
         Error("transmitApduWithExpectedResponse(): Unexpected response to command '"s
               + bytes2hexstr(command.toBytes()) + "' - expected '"s
-              + bytes2hexstr(expectedResponseBytes) + "', got '"s
-              + bytes2hexstr(response.toBytes()))
+              + bytes2hexstr(expectedResponseBytes) + "', got '"s + bytes2hexstr(response.toBytes())
+              + " in " + removeAbsolutePathPrefix(file) + ':' + std::to_string(line) + ':'
+              + callerFunctionName)
     {
     }
 };
@@ -95,7 +98,8 @@ void transmitApduWithExpectedResponse(const SmartCard& card, const CommandApdu&
 {
     const auto response = card.transmit(command);
     if (response.toBytes() != expectedResponseBytes) {
-        throw UnexpectedResponseError(command, expectedResponseBytes, response);
+        throw UnexpectedResponseError(command, expectedResponseBytes, response, __FILE__, __LINE__,
+                                      __func__);
     }
 }
 
@@ -111,17 +115,19 @@ size_t readDataLengthFromAsn1(const SmartCard& card)
     // Verify expected DER header, first byte must be SEQUENCE.
     if (response.data[0] != DER_SEQUENCE_TYPE_TAG) {
         // TODO: more specific exception
-        throw Error("readDataLengthFromAsn1(): First byte must be SEQUENCE (0x30), but is 0x"s
-                    + bytes2hexstr({response.data[0]}));
+        THROW(Error,
+              "readDataLengthFromAsn1(): First byte must be SEQUENCE (0x30), but is 0x"s
+                  + bytes2hexstr({response.data[0]}));
     }
 
     // TODO: support other lenghts besides 2.
     // Assume 2-byte length, so second byte must be 0x82.
     if (response.data[1] != DER_TWO_BYTE_LENGTH) {
         // TODO: more specific exception
-        throw Error("readDataLengthFromAsn1(): Second byte must be two-byte length indicator "s
-                    "(0x82), but is 0x"s
-                    + bytes2hexstr({response.data[1]}));
+        THROW(Error,
+              "readDataLengthFromAsn1(): Second byte must be two-byte length indicator "s
+              "(0x82), but is 0x"s
+                  + bytes2hexstr({response.data[1]}));
     }
 
     // Read 2-byte length field at offset 2 and 3.
@@ -130,8 +136,9 @@ size_t readDataLengthFromAsn1(const SmartCard& card)
     const auto length = size_t((response.data[2] << 8) + response.data[3] + 4);
     if (length < 128 || length > 0x0f00) {
         // TODO: more specific exception
-        throw Error("readDataLengthFromAsn1(): Unexpected data length in DER header: "s
-                    + std::to_string(length));
+        THROW(Error,
+              "readDataLengthFromAsn1(): Unexpected data length in DER header: "s
+                  + std::to_string(length));
     }
 
     return length;
@@ -162,7 +169,7 @@ byte_vector readBinary(const SmartCard& card, const size_t length, const size_t
 
     if (resultBytes.size() != length) {
         // TODO: more specific exception
-        throw Error("readBinary(): Invalid length: "s + std::to_string(resultBytes.size()));
+        THROW(Error, "readBinary(): Invalid length: "s + std::to_string(resultBytes.size()));
     }
 
     return resultBytes;

tests/mock/test-select-card-reader-and-card.cpp

@@ -59,7 +59,7 @@ TEST(pcsc_cpp_test, listReadersNoService)
 
     PcscMock::addReturnValueForScardFunctionCall("SCardEstablishContext", SCARD_E_NO_SERVICE);
 
-    EXPECT_THROW({ listReaders(); }, ScardServiceNotRunning);
+    EXPECT_THROW({ listReaders(); }, ScardServiceNotRunningError);
 
     PcscMock::reset();
 }