Bankverbindung aus dem Chip der Bankkarte auslesen
Aus windata WIKI
Beschreibung
windata SmartCard API (girocard)
Diese COM-Library ermöglicht es jedem Softwarehersteller Bankkarten-Informationen, wie z. B. die Bankverbindung einer EC-Karte, aus deren Chip auszulesen. Sämtliche Kartenleser, welche die PC/SC-Schnittstelle unterstützen, können verwendet werden.
Voraussetzungen
- SmartCard-Lesegerät mit PC/SC-kompatiblen Treibern
- Windows Vista oder höher
- Microsoft Visual C++ 2015 Update 3 x86 Redistributable
- Version 1.2 bis 1.9: Microsoft Visual C++ 2013 x86 Redistributable
- Bis Version 1.1.1: Microsoft Visual C++ 2010 SP1 x86 Redistributable
- JET 4.0 x86 Datenbanktreiber (in neueren Windows-Versionen muss dieser Treiber evtl. manuell nachinstalliert werden)
- Administratorrechte für das Setup
- Administratorrechte für das Aktualisieren der Bankleitzahlen-Datenbank bei fehlenden Schreib- / Änderungsrechten für das entsprechende Verzeichnis
- COM-kompatible Programmiersprache
Funktionen / Datentypen
Abfrage
Interface ISmartCardInfoImpl (IID_ISmartCardInfoImpl)
- HRESULT GetCardReaders([out, retval] ISmartCardReaderCol** ppiCardReaders)
- Zusammenfassung: Listet alle angeschlossenen SmartCard-Leser auf.
- Eingabeparameter: N/A
- Rückgabewert [ISmartCardReaderCol**]: Enthält ein Collection-Interface (s.u.), welches die Namen sämtlicher angeschlossener SmartCard-Leser auflistet. Hierbei sind die Leser in jener Reihenfolge aufgelistet, wie sie vom System verwaltet werden.
Implementierung
CoClass CLSID_SmartCardInfoImpl ("SmartCardInfo.SmartCardInfoImpl")
Interface IBankCard (IID_IBankCard)
- HRESULT GetAccountData([in] BSTR bsReaderName, [out, retval] IBankCardData** ppiBankCardData)
- Zusammenfassung: Liest einen Record aus einer Bankkarte aus.
- Eingabeparameter:
- bsReaderName [BSTR]: Der Name des SmartCard-Lesers, welcher zuvor durch die o.g. Funktion GetCardReaders() ermittelt wurde.
- Rückgabewert [IBankCardData**]: Enthält die PAN, Bankleitzahl, BIC, Kontonummer, IBAN, Aktivierungsdatum, sowie Ablaufdatum der Bankkarte (siehe IBankCardData-Interface).
Implementierung
CoClass CLSID_BankCard ("SmartCardInfo.BankCard")
Ergebnis
Interface ISmartCardReaderCol (IID_ISmartCardReaderCol)
- [propget] HRESULT Count([out, retval] LONG* pVal)
- [LONG]: Gibt die Anzahl der ermittelten SmartCard-Leser zurück.
- [propget] HRESULT CardReader([in, defaultvalue(0)] LONG lIndex, [out, retval] BSTR* pVal)
- Eingabeparameter [LONG]: Der Index des gewünschten SmartCard-Lesers. Der erste SmartCard-Leser wird durch den Index 0 referenziert, der zweite durch 1, usw. Dieser Parameter ist bei kompatiblen Programmiersprachen optional. Hierbei wird automatisch der erste SmartCard-Leser für die Datenauswertung verwendet.
- Rückgabewert [BSTR*]: Der Name des SmartCard-Lesers.
Dieses Interface unterstützt einen COM-Enumerator, welcher in entsprechenden Programmiersprachen durch eine For...Each Syntax verwendet werden kann.
Implementierung
CoClass CLSID_SmartCardReaderCol ("SmartCardInfo.SmartCardReaderCol")
Interface IBankCardData (IID_IBankCardData)
- [propget] HRESULT m_lPAN([out, retval] LONG* pVal)
- [LONG]: PAN (Kurz-Bankleitzahl)
- [propget] HRESULT m_lBankCode([out, retval] LONG* pVal)
- [LONG]: Bankleitzahl
- [propget] HRESULT m_bsBIC([out, retval] BSTR* pVal)
- [BSTR]: BIC
- [propget] HRESULT m_cyAccountNo([out, retval] CY* pVal)
- [CY]: Kontonummer
- [propget] HRESULT m_bsIBAN([out, retval] BSTR* pVal)
- [BSTR]: IBAN
- [propget] HRESULT m_dtActivationDate([out, retval] DATE* pVal)
- [DATE]: Aktivierungsdatum
- [propget] HRESULT m_dtExpiryDate([out, retval] DATE* pVal)
- [DATE]: Ablaufdatum
Implementierung
CoClass CLSID_BankCardData ("SmartCardInfo.BankCardData")
Aktualisierung
Interface IBankCardUpdate (IID_IBankCardUpdate)
- HRESULT CheckForBankMasterUpdate([out, retval] VARIANT_BOOL* pvbNewBankMasterAvailable)
- Zusammenfassung: Vergleicht den Versionsstand der lokalen Bankleitzahlen-Datenbank mit der Server-Version.
- Eingabeparameter: N/A
- Rückgabewert [VARIANT_BOOL*]: Falls eine neuere Version der BLZ-Datenbank verfügbar ist, gibt die Funktion 'VARIANT_TRUE' zurück. Andernfalls wird 'VARIANT_FALSE' zurückgegeben.
- HRESULT UpdateBankMaster()
- Zusammenfassung: Lädt die aktuelle Bankleitzahlen-Datenbank vom windata-Server herunter und aktualisiert die lokale Version. Es wird empfohlen diese Funktion aufzurufen, falls der Aufruf der o.g. Funktion "CheckForBankMasterUpdate()" zu einem postiven Ergebnis führt. Diese Funktion benötigt evtl. Administratorrechte.
- Eingabeparameter: N/A
- Rückgabewert: N/A
Implementierung
CoClass CLSID_BankCardUpdate ("SmartCardInfo.BankCardUpdate")
Class Factory
Interface ISmartCardInfoFct (IID_ISmartCardInfoFct)
- HRESULT CreateInstance([in] BSTR bsProgID, [out, retval] IDispatch** ppiDisp)
- Zusammenfassung: Erzeugt eine neue Instanz. Instanzen der Library können ausschließlich mittels dieses Interfaces angefordert werden. Eine Instanziierung mittels Standardfunktionen (CoCreateInstance(), new(), etc.) ist nicht vorgesehen.
- Eingabeparameter:
- bsProgID [BSTR]: ProgID der angeforderten Instanz.
- Rückgabewert [IDispatch**]: Neue Instanz.
Implementierung
CoClass CLSID_SmartCardInfoFct ("SmartCardInfo.SmartCardInfoFct")
Events
Interface _IBankCardUpdateEvents (IID__IBankCardUpdateEvents)
- HRESULT DownloadProgress([in] LONG lProgress)
- Zusammenfassung: Zeigt den Fortschritt des Downloads beim Aktualiseren der Bankleitzahlen-Datenbank an.
- Eingabeparameter:
- lProgress [LONG]: Fortschritt des Downloads in Prozent.
- Rückgabewert: N/A
Implementierung
CoClass CLSID_BankCardUpdate
Library
Library LIBID_SmartCardInfoLib
Einbindung
Hinweise zur Implementierung sind im Download-Paket vorhanden. Hier finden Sie beispielhafte Lösungen für C++, C#, VB6 und VBA.
Skriptsprachen können mittels IDispatch ebenfalls auf die Library zugreifen. Hierzu ist im Demo-Verzeichnis ein VBS-, sowie JScript-Beispiel hinterlegt.
Der Einsatz weiterer Programmiersprachen ist problemlos möglich, sofern diese die COM-Umgebung unterstützen (z.B. Java, Python, Delphi).
Anwendung
Nach dem Auslesen einer Girocard kann als visuelles Ergebnis beispielsweise Folgendes angezeigt werden:
Fehlerrückmeldung
Die Fehlerrückmeldungen lassen sich in folgende Kategorien unterteilen:
- Fehler, welche vom SmartCard-Leser bzw. der unterliegenden PC/SC-Schnittstelle generiert werden. Eine Liste möglicher Fehlercodes finden sich hier.
- Fehler, welche durch die Bankkarte ausgelöst werden (E_APDU_RESPONSE = 0xE0040300). Zur Unterstützung und Behebung dieser Fehlerklasse wenden Sie sich bitte an den Support der windata GmbH & Co.KG unter support@windata.de.
- Alle sonstigen Fehler, welche durch einen bekannten HRESULT gemeldet werden.
Versionshistorie
Version 2.1 (20170322)
- Windows XP & Windows Server 2003 werden nicht mehr unterstützt.
- Aktualisierte CoFIS Library
- .NET Framework 4.0 als Installationsvoraussetzung entfernt.
- Die Visual C++ Runtime ist nicht mehr Teil des Setup. Falls nicht vorhanden, muss diese manuell installiert werden.
- Setup-Routine verbessert.
Version 2.0 (20170104)
- Komplette Überarbeitung der Library: Portierung der Funktionen in natives COM-Interface.
- Zusammenführung bisheriger Produktversionen.
- Aufnahme zusätzlicher Properties aus der Bankkarte.
- Compiler-Update: MSVC 2015.
Version 1.3.1 (20150113)
- Bugfix bei der IBAN-Berechnung (betrifft nur die SmartCardInfo Extended Library).
Version 1.3 (20141211)
- Bugfix bei der Erkennung der neuen IBAN-Bankkarten.
- Optimierungen.
- Namensänderung: "SmartCardInfo", statt "SmartCard Info".
- Die Entwicklung der Library erfolgt zukünftig in zwei unterschiedlichen Versionen:
- SmartCardInfo.dll (PAN): Diese Version wandelt die ermittelte PAN nicht um. Sie repräsentiert somit den Versionsstand der Library vor der Version 1.2.
- SmartCardInfoEx.dll (PAN zu BLZ Umwandlung): Diese Library verwendet die windata CoFIS Library, um die PAN in ihre zugehörige BLZ umzuwandeln. Dies stellt den Versionsstand der Library 1.2 und später dar.
Version 1.2.1 (20141201)
- Diverse Optimierungen.
Version 1.2 (20141111)
- Die PAN wird nun direkt mittels der zugehörigen windata CoFIS Library in ihre zugehörige Bankleitzahl umgewandelt. Dieser Prozess erfolgt transparent im Hintergrund. Dadurch ist der Rückgabewert der "GetAccountData()"-Funktion nun wie folgt definiert: <Bankleitzahl>;<KontoNr.>;<Ablaufdatum>
- Zwei neue Funktionen sind verfügbar:
-
- CheckForBankMasterUpdate(): Vergleicht den Versionsstand der lokalen Bankleitzahlen-Datenbank mit der Server-Version.
- DownloadCurrentBankMaster(): Lädt die aktuelle Bankleitzahlen-Datenbank vom windata-Server herunter.
- Compiler-Update: MSVC 2013. Die zugehörige Runtime ist erforderlich, um die Library verwenden zu können.
- Weitere Stabilitäts- und Performanceverbesserungen.
Version 1.1.1 (20140612)
- Diverse Optimierungen.
Version 1.1 (20140408)
- Bereitstellung einer Header- und Lib-Datei, um die DLL einfacher einbinden zu können.
- Kompatibilität des zurückgegebenen BSTR verbessert.
- Die MSVC 2010-Runtime ist nun zwingend erforderlich, um die DLL verwenden zu können.
- Unicode-Unterstützung.
- Diverse Optimierungen.
Version 1.0 (20130423)
Ursprüngliche Version.
Download (Trial-Version)
Eine Trial-Version der Library steht zu Evaluierungszwecken zur Verfügung. Führen Sie hierzu die Datei "SmartCardInfoSetup.msi" aus, um die Library auf Ihrem System zu installieren.
Lizenzierung
Zur Lizenzierung dieser Library wenden Sie sich bitte an den Vertrieb der windata GmbH & Co.KG unter info@windata.de.