 |
Datafox DFCom - API 04.03.22
Dokumentation zur Datafox Kommunikationsbibliothek (DFComDLL.dll / DFCom_x64.dll)
|
|
Datafox DFCom - API 04.03.22
Dokumentation zur Datafox Kommunikationsbibliothek (DFComDLL.dll / DFCom_x64.dll)
|
Die Abbildung 1 zeigt einen möglichen Hardwareaufbau mit Datafox - Geräten. Dieses Beispiel soll der Verdeutlichung der Begriffe Verbindung und Geräteadresse dienen. Die Verbindungs-Id (connectionId) ist vergleichbar mit einem Straßennamen. Die Geräteadresse (deviceAddress) ist vergleichbar mit der Hausnummer eines Gebäudes (wird in RS485-Netzwerken oder bei Mehrfachdockingstationen benötigt). Im abgebildeten Beispiel gibt es insgesamt vier Verbindungen (connectionIds).
Ein Gerät der Abbildung 1 kann über folgende Wertangaben eindeutig identifiziert werden:
Um Informationen an die Geräte zu schicken ist es notwendig, dass die jeweilige Verbindung zuvor geöffnet wurde. In Analogie zum Strassenbeispiel würde dies geöffneten Bahnschranken entsprechen.
Es ist nicht notwendig jedes Mal die verwendete Verbindung zu schließen, wenn die Kommunikation mit einem Gerät beendet wurde (eine Bahnschranke wird ebenfalls nicht nach jedem durchgefahrenen Auto geschlossen). Die Kommunikationsverbindungen können beim Start des Programms geöffnet werden (siehe Programmbeispiele). Ein Schließen der Verbindungen ist normalerweise erst bei Programmbeendigung notwendig oder wenn es gewisse Situationen erfordern.
Die Verbindungs-Id (connectionId) ist demnach die Identifikationsnummer eines Verbindungsobjektes. Um mit einem Gerät kommunizieren zu können muss eine Kommunikationsverbindung zu diesem hergestellt worden sein. Über die Verbindungs-Id wird diese Verbindung funktionsübergreifend identifiziert, sie muss bei fast nahezu jeder Funktion als erstes Argument angegeben werden.
Jedes Gerät gehört genau zu einer Kommunikationsverbindung. Die Anzahl der möglichen Verbindungen ist auf maximal 250 (+140 im Active-Mode) festgelegt (erlaubter Wertebereich: 1 - 250; Active-Mode: 251 - 391).
Die Geräteadresse (deviceAddress) wird zur Adressierung eines bestimmten Gerätes benötigt. In RS485 Netzwerken (Bussystemen) benötigt jedes Endgerät eine eindeutige Nummer. Die Geräteadresse wird an jedem Gerät in dessen BIOS eingestellt.
Pro Verbindung ist eine Geräteanzahl von 1..n Einzelgeräten (Endgeräten) möglich. Die maximale Anzahl n (max. sind 250 Geräte pro Verbindung möglich) wird von dem gewählten Verbindungsschema (siehe Abbildung 1) bestimmt.
| Verbindungsschema | Verbindungsart | von - auf | max. Anzahl Geräte | zu verwendende Geräteadresse bei Funktionsaufrufen |
|---|---|---|---|---|
| direkt | RS232 - RS232 | 1 | immer mit 254 |
| über Umsetzer | RS232 - RS485 | 250 | von 1 bis 250 |
|
| direkt | TCP/IP - TCP/IP | 1 | immer mit 254 |
| über COM-Server | TCP/IP - RS485 | 250 | von 1 bis 250 |
|
| über COM-Server | TCP/IP - RS232 | 1 | immer mit 254 |
Im nachfolgenden wird kurz erläutert, wie das Konzept des "Passive-Mode" funktioniert und eingesetzt werden kann.
Die Abbildung 2 zeigt eine mögliche Grundstruktur für ein Programm, für den in Abbildung 1 gezeigten Hardwareaufbau. Prinzipiell sollte ein Verbindungsschema wie im nebenstehenden Programmschema aufgebaut sein.
Nach dem Start des Programms wird die benötigte Verbindung (connectionId) initalisiert, hierzu dienen Initalisierungsroutinen wie DFCComOpenIV(). Während dieser Phase können natürlich auch mehrere Verbindungen hintereinander initalisiert werden. Nach der Initialisierung der Verbindungen können die Endgeräte beliebig oft angesprochen werden. Im Normalfall ist es völlig ausreichend wenn bei Beendigung des Programms alle geöffneten Verbindungen geschlossen werden.
Eine erneute Initialisierung wäre nur im Falle einer Kommunikationsunterbrechung notwendig. Hierzu ist die betroffene Verbindung erst einmal explizit mit der Funktion DFCComClose() zu schließen. Erst nach dem Schließen der Verbindung ist es zulässig mit einer Initialisierungsfunktion diese wieder zu öffnen.
Mit der Funktion DFCIsChannelOpen() hat man zum Beispiel die Möglichkeit zu überprüfen ob eine bestimmte Verbindungs-Id bereits geöffnet wurde (bzw. noch geöffnet ist).
C++ Beispiel: Überprüfen ob die Verbindungs-Id 2 geöffnet ist
Wenn die Verbindung zwischen der Bibliothek und dem Gerät unterbrochen wurde, dann sollte dieses durch die Fehlerbehandlung auf folgende Weise abgefangen werden (siehe auch Grober Überblick).
Im nachfolgenden wird kurz erläutert, wie das Konzept des "Active-Mode" funktioniert und eingesetzt werden kann. Es bezieht sich auf die Version 4.1.5.
Bei dem "Active-Mode" bauen die Geräte eine Verbindung zur Bibliothek auf. Diese Verbindung bleibt über die gesamte Laufzeit bestehen und wird durch Alive-Pings sichergestellt. Das bedeutet, dass bei einem Verbindungsabriss oder einer Verbindungsunterbrechung die Geräte selbstständig eine Neuverbindung unternehmen.
Jede bestehende Verbindung im Active-Mode hat eine eindeutige Verbindungs-Id die über die entsprechenden Funktionen abgerufen werden können. Unter Verwendung dieser Verbindungs-Id kann jede Funktion wie gewohnt ausgeführt werden. Die Geräteadresse ist in diesem Fall immer 254.
Zusätzlich zur Verbindung im Active-Mode kann eine "Datensatzmeldung" konfiguriert werden. Dabei melden die Geräte der Bibliothek ob Datensätze vorliegen und diese speichert die Information bis zum Abruf zwischen, dieses vermindert die Netzwerkbelastung, da nicht ständig auf die Geräte mit einer Datensatzanfrage gepollt werden muss.
Bibliothek ohne Active-Mode (Wird Passive-Mode genannt.)
Bibliothek mit Active-Mode
Über die Funktion DFCStartActiveConnection() starten Sie das Modul für den Active-Mode. Dabei wird von der Bibliothek ein Listen-Socket erstellt, an den die Geräte dann eine Verbindungsanfrage stellen können. Mit DFCStopActiveConnection() beenden Sie das Modul für den Active-Mode, dabei werden alle bestehenden Verbindungen getrennt.
Im Gerät geschieht die Aktivierung / Deaktivierung durch die Systemvariable COM.ACTIVE.
Die im Gerät zu hinterlegenden Verbindungsdaten können über Systemvariablen eingestellt werden. Eine Liste aller benötigten Systemvariablen für den Präfix COM finden Sie im Systemvariablen .
Systemvariablen können mit den Funktionen DFCSetGlobVar(), DFCGetGlobVar() gesetzt bzw. gelesen werden.
Die Systemvariablen für Präfix COM, können über das DatafoxStudioIV eingestellt werden. Bitte beachten Sie den hierfür zuständigen Dialog unter "Konfiguration -> Systemvariablen für die Gerätekommunikation".
Standardmäßig ist das Melden von Datensätzen nach dem Start des Active-Mode durch DFCStartActiveConnection() aktiviert und die Bibliothek verarbeitet somit die Meldungen der Geräte. Durch Aufruf der Funktion DFCSetRecordAvailable() kann diese Meldungsverarbeitung der Bibliothek aktiviert / deaktiviert werden.
Im Gerät geschieht die Aktivierung / Deaktivierung durch die Systemvariable COM.NOTIFY. Wenn im Gerät mindestens ein Datensatz abrufbereit ist, wird dieses durch das Gerät der Bibliothek automatisch gemeldet. Die Meldung wird in einer Prioritätswarteschlange der Bibliothek eingereiht und kann über die Funktion DFCRecordAvailable() abgerufen werden. Über diesen Funktionsaufruf wird unter anderem die Verbindungsnummer geliefert und kann zum Abrufen der Datensätze im folgenden Aufruf von DFCReadRecord() verwendet werden.
Die Verbindung im Active-Mode sowie Melden von Datensätzen kann über das DatafoxStudioIV geprüft und in Betrieb genommen werden. Hierzu steht ein eigener Kommunikationspunkt unter "Kommunikation -> Einstellungen" zur Verfügung. Bitte beachten Sie, dass Sie bevor eine Kommunikation mit einem Gerät durchgeführt werden kann, eine Aktive-Verbindungs-Id gewählt werden muss.
Um Datensätze aus den Geräten zu lesen muss zuerst die jeweilige Kommunikationsschnittstelle mit der Funktion DFCComOpenIV() erfolgreich initialisiert werden. Oder es muss im Active-Mode eine entsprechende Verbindung zustande gekommen sein.
Danach wird mit der Methode DFCReadRecord() das Gerät angesprochen und der erste Datensatz aus dem Gerät gelesen. Nach erfolgreicher Verarbeitung des Datensatzes durch Ihre Anwendung muss mit der Funktion DFCQuitRecord() der zuvor gelesenen Datensatz quittiert werden. Erst nach erfolgreicher Ausführung der quittierung wird durch die Firmware auf den nächsten Datensatz gewechselt. Durch erneuten Aufruf der Funktion DFCReadRecord() wird der nächste Datensatz aus dem Gerät gelesen.
Nach Ausführung aller benötigten Kommunikationsbefehle, muss mit der Funktion DFCComClose() die Kommunikationsschnittstelle wieder geschlossen werden.
Es kann während der Kommunikation kein Datensatz verloren gehen, bei einer Störung während der Kommunikation kann es jedoch vorkommen das ein Datensatz zweimal ausgelesen wird (Aussage gilt für Firmwareversion > 2.0).
Sie haben im Gerätesetup die Möglichkeit einen Server-Timeout anzugeben. Wird ein Datensatz am Terminal über die Bedienung erzeugt und innerhalb dieses eingestellten Timeouts abgerufen wird er als ein Online-Datensatz ausgezeichnet. Die Datensatzfunktionen zum Abruf der Daten geben einen entsprechenden Rückgabewert zurück um ihn als Online-Datensatz zu melden.
Datensätze die als Online gemeldet werden, müssen durch Aufruf der Funktion DFCComSendMessage() beantwortet werden. Sie können durch Angabe einer Einblendezeit von 0 auch eine "dummy" Meldung zum Gerät senden. Erst nachdem das Gerät diese Meldung erhalten hat, wird die Bedienung wieder für weitere Eingaben freigeschaltet. Erfolgt keine Rückmeldung per DFCComSendMessage() wird die Bedienung erst nach Ablauf des Server-Timeouts freigeschaltet.
Es können gleichzeitig mehrere Verbindungen unter Verwendung verschiedener Schnittstellen aufgebaut werden. Für jede Verbindungs-Id wird ein eigener interner Speicherbereich verwendet, der jedoch die Datensatzbeschreibungen und Listenbeschreibungen des zuletzt mit DFCLoadDatensatzbeschreibung() (und DFCLoadListenbeschreibung()) ausgelesenen Gerätes vorhält. D. h., wenn Sie verschiedene Setupkonfigurationen in den Geräten verwenden, ist eine Aktualisierung der Datensatz- und Listenbeschreibungen immer dann erforderlich, wenn sich im angesprochenen Gerät eine geänderte Datensatz- oder Listenbeschreibung befindet.
Auch bei mehreren angesprochenen Geräten in einem RS485 Netzwerk oder einer Mehrfachdockingstation ist wichtig, immer beim Wechsel auf ein nächstes Gerät ggf. die Datensatz- und Listenbeschreibungen zu aktualisieren.
Jede Verbindungs-Id verwaltet ihren eigenen Speicher für die 20 möglichen Listen. Für jede zu importierende Liste wird entsprechend ihrer Größe ein dynamischer Speicher reserviert. Mit der Funktion DFCClrListenBuffer() werden alle reservierten Speicher freigegeben.
Die Verarbeitung erfolgt in drei Schritten. Zuerst werden die internen Listenspeicher durch Aufruf der Funktion DFCClrListenBuffer() gelöscht. Danach wird durch Aufruf der Funktion DFCMakeListe() für jede Liste der entsprechende Listenspeicher mit Daten gefüllt. Hiernach werden die Listendaten durch Aufruf der Funktion DFCLoadListen() in das Gerät übertragen.
Die Funktion DFCLoadListen() überträgt immer alle zuvor importierten Listen, egal ob eine oder mehrere. Im Gerät werden nach Übertragung von Listen mittels DFCLoadListen() nur die übertragenen Listen ersetzt, alle anderen bleiben erhalten.
Um eine einzelne Liste zu übertragen, löschen Sie die Listenspeicher mittels DFCClrListenBuffer() und importieren die Listendaten mit DFCMakeListe(). Danach übertragen Sie sie dann mit DFCLoadListen().
Um Listendaten mittels DFCMakeListe() zu importieren, müssen diese in einem Bytearray aufbereitet werden.
Die Listendaten im Bytearray müssen exakt mit der Listenbeschreibung im Setup übereinstimmen. Die Feldinhalte sind links ausgerichtet und werden bei Feldern mit Zeichenketten bis zum Auffinden der ersten Nullterminierung ausgegeben.
Zeichenketten sind mit NULL (Hexadezimalwert 0x00, nicht zu verwechseln mit ASCII Zeichen "0", Hexadezimalwert 0x30) auf die im Setup vorgegebene Feldlänge zu füllen. Zusätzlich ist die abschließende NULL zu beachten.
Wenn im Setup eine Zeichenkette mit 16 Zeichen angelegt wurde, ist die Feldlänge exakt 17 Byte. Trennzeichen zwischen den Feldern und den Zeilen werden nicht verwendet.
Beispiel: Liste mit 2 Feldern
Feld 1: Personalnummer (nur Ziffern) 4 Byte;
Feld 2: Name Zeichenkette (ASCII - Zeichen) 16 Zeichen.
Eine Zeile besteht dann aus genau 4 + 1 + 16 + 1 = 22 Byte. Wenn 3 Zeilen angelegt werden sind exakt 3*22 = 66 Byte anzulegen.
Es ist nicht möglich einzelne Listen komplett zu entfernen. Dies geschieht lediglich nach Übertragung einer Setupdatei. Durch Aufruf der Funktion DFCMakeListe() mit der Datensatzanzahl 0 wird die Liste als leere Liste importiert und durch Aufruf der Funktion DFCLoadListen() diese dann zum Gerät übertragen.
Beschreibung wie die Listenübernahme der Firmware arbeitet. Die Listenübernahme ist je nach gewähltem Betriebsmodus "Normal, MDE" oder "PZE Modus 1, 2" leicht verschieden.
Listen für Betriebsmodus "Normal, MDE": Nach dem Übertragen einer oder mehrerer Listen, werden diese in folgenden Situationen übernommen:
Listen für den Betriebsmodus "PZE Modus 1, 2": Zusätzlich zu den Situationen des Betriebsmodus "Normal, MDE", die hier auch gelten, kommt noch der einstellbare Tastentimeout dazu. Erfolgt keine Bedienung des Geräts für den eingestellten Tastentimeout, durchläuft das Gerät zwangsläufig das Hauptmenü und die Listendaten werden dadurch übernommen.
Listen für die Zutrittskontrolle: Nach dem Übertragen einer oder mehrerer Zutrittslisten wird die Zutrittskontrolle gestoppt und die Listendaten in das System übernommen. Danach nimmt die Zutrittskontrolle ihren Betrieb wieder auf.
Listen für Timeboys: Nach dem Übertragen einer oder mehrerer Listen für Timeboys, werden diese sofort übernommen, sofern nicht gerade eine Übertragung der bereits vorliegenden Listen in einen Timeboy aktiv ist. Dann wird die aktuelle Übertragung zuerst abgeschlossen bevor die neuen Listendaten übernommen werden.
Der interne Puffer wird für jede Verbindungs-Id getrennt geführt. Die Listendaten müssen daher auch für jede verwendete Verbindungs-Id getrennt importiert werden.
Wenn über eine Verbindungs-Id mehrere Geräte erreichbar sind, die unterschiedliche Listen benötigen, müssen die Listendaten vor der Übertragung für das entsprechende Gerät, neu importiert werden.
Ablauf des Listenladen:
Die Bibliothek setzt nur C-Datentyen ein.
Die Uhr in den Terminals sollte regelmäßig gestellt werden, um Abweichungen zu vermeiden. Insbesondere, wenn mehrere Terminals verwendet werden. Wir empfehlen die Uhr mindestens einmal pro Tag zu stellen. Der ideale Zeitpunkt dafür ist 4:00 Uhr, da hier dann bei Sommer-/Winterzeit gleich die Uhr richtig gestellt wird.
Es ist ggf. die automatische Sommer-/Winterzeitumstellung des Betriebssystems zu aktivieren.
Zum Stellen der Uhr verwenden Sie die Funktion DFCComSetTime().
Ist eine im Timeboy hinterlegte Nummer. Standardmäßig ist diese 0 und kann über das TbSetup/DatafoxStudioIV gesetzt werden. Timeboys können über diese Nummer in Gruppen eingeteilt werden und über die Funktionen mit separaten Listen versorgt werden.
Beispiel zur Erklärung:
Problem: Sie haben drei Timeboys mit dem gleichen Setup im Einsatz, möchten aber auf jedem Timeboy eine eigene Auftragsliste aufspielen.
Lösung: Sie Vergeben jedem Timeboy eine eigene GroupID und übertragen die Listen, die für alle Geräte gültig sind mit der GroupID 0 und die jeweilige Auftragsliste mit derren GroupID.
Firmwareupdates enthalten neben dem eigentlichen Kontrollerprogramm noch Resourcendaten wie Zeichensätze, Texte, Bilder und weitere Daten. Mit der Funktion DFCUpload() ist ein unkompliziertes Update des Gerätes möglich, da die Funktion selbstständig die benötigten Daten ermittelt und entsprechend überträgt.
Folgende Optionen können mittlerweile zusätzlich durch den Anwender eingestellt werden:
Diese Informationen werden (so weit vorhanden) von der Updateroutine herangezogen um die gewünschte Gerätedatei aus dem Gerätedateiarchiv (*.dfz) auszuwählen.
Von folgenden Einstellungen geht die Bibliothek aus, wenn die Optionen im Gerät undefiniert sind.
Beim Update über das DatafoxStudioIV werden Sie automatisch zur Einstellung der Optionen aufgefordert, wenn diese undefiniert sind. Beim Update über die Bibliothek werden die oben aufgeführten Standardvorgaben verwendet. Die Umschaltung der Optionen ist über das DatafoxStudioIV möglich.
Das Wechseln in den Bootloadermodus ist im jeweiligen Handbuch beschrieben.
Im Bootloadermodus verwendet das Gerät fest die Kommunikationsart USB.
Nach Aufspielen einer Firmwareversion über den Bootloadermodus startet das Gerät neu. Das Gerät nutzt dann wieder die vor dem Update eingesetzte Kommunikationsart.
A downgrade must generally be carried out via the bootloader mode.
After uploading a firmware version via GSM/GPRS, the unit performs a new dial-in with the previously used dial-in parameters. This data is not lost when a new firmware version is installed.
| Observation | Action |
|---|---|
| After transferring a firmware version, no fonts and graphics are displayed on devices with display. | Please transfer the same firmware version again. |
Specification of an IP address in dot notation:
| IP-Address | Description |
|---|---|
| "4.3.2.16" | Decimal specification |
| "004.003.002.020" | Octal specification |
| "0x4.0x3.0x2.0x10" | Hexadecimal specification |
| "4.003.002.0x10" | Mixed specification |
Please note that "leading zeros" lead to the octal specification!!! The specification of host names, e.g.: www.datafox.de
Über die Systemvariable COM.KEY
Über die Funktion DFCSetCommunicationPassword() kann das zu verwendente Passwort an das Kommunikationsmodul übergeben werden. Wenn durch ein Gerät die verschlüsselte Kommunikation gefordert wird, wird dieses dann dazu verwendet die Kommunikation zwischen Gerät und Kommunikationsmodul durchzuführen.
Nachdem durch das Gerät eine verschlüsselte Kommunikation gefordert wurde, wird das hinterterlegte Passwort dazu verwendet. Es wird ein Session-Key ausgetauscht, welcher je nach Angabe, dann zyklisch erneuert wird. Die gültige Zeitspanne des Session-Keys geben Sie beim Aufruf der Funktion DFCSetCommunicationPassword() an.
Wenn Sie Listen DFCLoadListen() oder Zutrittslisten DFCLoadEntrance2List() zum Gerät übertragen haben, können Sie diese mit den Funktionen aus dem Kapitel "Funktionen für Listen, sowie Zutrittslisten" bearbeiten.
Anhand der folgenden Grafik soll gezeigt werden wie Sie auf die Listendaten zugreifen können um unterschiedliche Abfragen tätigen können.
Es gibt einige Befehle deren Ausführung je nach zu übertragender Datenmenge entsprechend lange benötigen. Hierzu zählen unter anderem auch DFCLoadListen() zum übertragen von Setuplisten oder DFCLoadEntrance2List() zum übertragen von Zutrittslisten.
Wenn bei Ihnen die Notwendigkeit besteht während der länger andauernden Übertragung z. B. Datensätze abrufen zu können oder Sie möchten auf mehrere Geräte der selben Verbindung die Listendaten ziemlich zeitgleich auf den aktuellen Stand bringen, dann können Sie dieses mit den DFCBlockTransfer() Funktionen tun.
Anhand der folgenden Grafik soll gezeigt werden wie Sie die DFCBlockTransfer() Funktionen anwenden können, um zwischen dem Übertragen von Setuplisten Datensätze abrufen zu können.
Im folgenden sollen verschiedene eingesetzte Begriffe oder auch Angaben bei den Funktionsparametern erläutert werden.
Bei den Funktionen für die Initalisierung der Schnittstellen, wie DFCComOpenIV() oder anderen, kommen Angaben zu einem Schnittstellentimeout vor. Dieser Schnittstellentimeout wirkt sich auf die zugrundeliegenden Leseroutinen aus. Wird ein Datenpacket zu einem Gerät gesendet, wird diese eingestellte Zeit gewartet bis ein Abbruch des Lesens erfolgt und eine erneute Anfrage gesendet wird (bis zu 3 mal). Kommt die Antwort auf die Anfrage schneller als der eingestellte Timeout wird mit der Verarbeitung entsprechend sofort weitergemacht.
Bei einem hoch gewählten Timeout, dauert es entsprechend lange, bis erkannt wird, dass ein Gerät überhaupt nicht antwortet. Bei einem klein gewählten Timeout können lange Packetlaufzeiten zu unnötig wiederholten Anfragen führen, ggf. sogar zu einem Abbruch der Kommunikationsanfragen.
Der Timeout steht in Zusammenhang mit der gewählten Kommunikationsart, somit ist Beipielsweise bei RS232 ein Timeout von 1000ms Standard, bei TCP/IP 3000ms Standard und bei TCP/IP über Mobilfunk (GPRS) sogar 9000ms Standard (da hier die Packetlaufzeiten entsprechen hoch sind).
Es wird auf jeden Fall empfohlen den Wert durch Ihre Anwendung konfigurierbar zu halten, da es abhängig von den Kundeninstallationen notwendig werden kann diesen Wert anzupassen.
Bei den meisten kommunizierenden Funktionen wird ein Fehlerparameter angegeben. Die Bedeutung des Fehlercodes siehe Fehlernummern.
Alle in der Bibliothek als Zeichenfolgen bezeichnete Werte sind als nullterminierte Zeichenfolgen mit einer ISO 8859-1 Zeichenkodierung zu verstehen. Bei Zeichenarrays handelt es sich um reservierte Puffer für aufzunehmende Zeichenfolgen.
Die verwendeten Datenstrukturen werden nachfolgend erklärt.
Es wird in jedem Datensatz die zugehörige Datensatzbeschreibungsnummer aus dem Setup mitgeführt. Ein an die Anwendung überlieferter Datensatz sieht immer wie folgt aus:
| Byte - Nummer: | 0 | 1 ... (length - 1) |
|---|---|---|
| Byte - Inhalt: | Beschreibungsnummer | Daten des Datensatzes. |
Es werden immer alle Felder eines Datensatzes aufeinanderfolgend und in der im Setup definierten Feldbreite (ggf. plus eines Terminierungszeichens) geliefert.
Bitte beachten Sie, dass alle als ASCII - Feld definierten Felder ein zusätzliches Terminierungszeichen erhalten, wodurch ein im Setup mit einem Byte definiertes Feld in den "Daten des Datensatzes" zwei Byte umfasst!
Mit Hilfe der Auswertefunktionen für die Datensatzbeschreibungen und Listenbeschreibungen können Sie die "Daten des Datensatzes" interpretieren. Das Terminierungszeichen ist in der Angabe zur Feldbreite des jeweiligen Datensatzfeldes enthalten.
Das Datum - Uhrzeit Feld in einem Datensatz sieht wie folgt aus:
| Byte - Nummer | Bedeutung | Beispiel: 06.04.2012 04:12:00 |
|---|---|---|
| 0 | Jahreszahl Hunderter (0..255) | 20 |
| 1 | Jahreszahl Einer (0..99) | 12 |
| 2 | Monat (1..12) | 4 |
| 3 | Tag (1..31) | 6 |
| 4 | Stunde (0..23) | 4 |
| 5 | Minute (0..59) | 12 |
| 6 | Sekunde (0..59) | 0 |
Der Feldtyp steht für Eingaben größerer Datenmengen (> 40 Zeichen) mittels Feldfunktion "Normal" mit Barcode/Transponder zur Verfügung. Es können bis zu 240 Byte in einem solchen Datenfeld gespeichert werden. Um die Menge der gespeicherten Daten ermitteln zu können wird diese Information im ersten Byte des Feldinhaltes abgelegt.
Aufbau des Feldinhaltes:
| Byte - Nummer | Bedeutung |
|---|---|
| 0 | Anzahl der Datenbytes |
| 1 ... length | Datenbytes |
Um diesen Datensatzfeldtyp verwenden zu können benötigen Sie mindestens Firmware Version 04.03.13.
Bei einem Fingertemplate handelt es sich um eine Datenstruktur zur Identifikation einer Person. Es verknüpft eine Personalnummer mit den Daten eines Fingers und enthält folgende grundlegende Informationen.
Im Folgenden soll Ihnen aufgezeigt werden, welche Möglichkeiten Ihnen für die Verarbeitung und Verteilung dieser Daten in Ihrem System zur Verfügung stehen.
Für die Verarbeitung von Fingertemplates stehen Ihnen mehrere Funktionen zur Verfügung. Mit Hilfe der Funktion DFCFingerprintList() können Sie sich eine zweispaltige Liste der auf dem enthaltenen Modul vorhandenen Fingertemplates erstellen lassen. Es wird die Personalnummer und Fingernummer pro Template in eine automatisch generierte Liste geschrieben. Zum Abrufen der Daten siehe Bearbeitung vorhandener Listendaten..
Mit Hilfe der Funktion DFCFingerprintGetRecord() können Sie die einzelnen Templates abrufen und mittels DFCFingerprintAppendRecord() an die Templatedatenbank eines anderen Gerätes anfügen. Mit DFCFingerprintDeleteRecord() können Sie einzelne Templates oder alle Templates einer Person oder auch alle enthaltenen Templates von dem Modul löschen lassen.
Mit Hilfe dieser nun vorgestellten Funktionen können Sie ein Verteilen von Fingertemplates über mehrere Geräte hinweg realisieren. Hierzu können Sie in dem von Ihnen verwendeten Setup entsprechende Datensätze für das Einlernen und Löschen von Fingertemplates erzeugen und daraufhin entsprechend reagieren. Sie haben die volle Kontrolle über die im System vorhandenen Fingertemplates.
Eine andere Variante Fingertemplates im System zu verteilen ist die über ein Einlerngerät. Hierbei müssen Sie mit dem Kunden ein Gerät (meist in der Personalabteilung) wählen, wo neue Mitarbeiter eingelernt oder ggf. auch Mitarbeiter gelöscht werden. Im Setup erzeugen Sie auch hierbei entsprechende Informationsdatensätze auf die Sie dann wie folgt reagieren können: Mit Hilfe der Funktion DFCFingerprintBackup() erstellen Sie von den Daten des besagten Gerätes eine Backupdatei. Diese Backupdatei können Sie dann mit DFCFingerprintRestore() auf die anderen im System befindlichen Geräte übertragen.
Die mittels von DFCFingerprintBackup() erstellte Backup-Datei enthält einen 9-Byte-Header gefolgt von einer Aneinanderreihung der Fingerprint-Templatedaten, so wie diese durch den Sensor verarbeitet werden. Der Aufbau der Template-Daten, soweit bekannt, ist in den folgenden Unterkapiteln beschrieben.
Bitte beachten Sie, dass ein Mischen verschiedener Template-Datenformate im Sensor nicht möglich ist.
| Byte - Nummer: | Inhalt |
|---|---|
| 1 .. 2 | Magic (0xdfdf) |
| 3 .. 4 | Offset zum Datenbeginn |
| 5 .. 6 | Anzahl enthaltener Fingertemplates |
| 7 | Template-Typ (0 = DIN V66400, 1 = Idencom-Compact, 2 = Idencom-Standard, 3 = Saturn01) |
| 8 .. 9 | CRC der Header-Daten (ohne den CRC selbst) |
| 10 .. 10+sz-1 | Daten des ersten Fingerprint-Templates |
| 10+sz .. 10+2*sz-1 | Daten des zweiten Fingerprint-Templates |
| 10+2*sz .. | Weitere Template-Daten gemäß spezifizierter Anzahl |
Das gesamte Template hat eine maximale Größe von 161 Byte.
| Byte - Nummer: | Inhalt |
|---|---|
| 1 .. 8 | PID (Personal-Id. Es werden ausschließlich Byte 1 - 4 als 32bit Wert verwendet. |
| 9 | FID (Finger-Id) |
| 10 | Quality |
| 11 | Anzahl Minutiae |
| 12 | X1 |
| 13 | Y1 |
| 14 | W1 |
| 15 | X2 |
| 16 | Y2 |
| 17 | W2 |
| .. | .. |
| .. | .. |
| 159 | X50 |
| 160 | Y50 |
| 161 | W50 |
Das gesamte Template hat eine maximale Größe von 216 Byte.
| Byte - Nummer: | Inhalt |
|---|---|
| 1 .. 8 | PID (Personal-Id. Es werden ausschließlich Byte 1 - 4 als 32bit Wert verwendet. |
| 9 | FID (Finger-Id) |
| 10 | Quality |
| 11 | Anzahl Minutiae |
| 12 | X1 |
| 13 | Y1 |
| 14 | W1 |
| 15 | XN1 |
| 16 | YN1 |
| .. | .. |
| .. | .. |
| 214 | W41 |
| 215 | XN41 |
| 216 | YN41 |
Das gesamte Template hat eine maximale Größe von 561 Byte.
| Byte - Nummer: | Inhalt |
|---|---|
| 1 .. 8 | PID (Personal-Id. Es werden ausschließlich Byte 1 - 4 als 32bit Wert verwendet. |
| 9 | FID (Finger-Id) |
| 10 | Quality |
| 11 | Anzahl Minutiae |
| 12, 13 | X1 |
| 14, 15 | Y1 |
| 16, 17 | W1 |
| 18 | V1 |
| 19, 20 | XN1 |
| 21, 22 | YN1 |
| .. | .. |
| .. | .. |
| 555, 556 | W50 |
| 557 | V50 |
| 558, 559 | XN50 |
| 560, 561 | YN50 |
Das gesamte Template hat eine maximale Größe von 635 Byte.
| Byte - Nummer: | Inhalt |
|---|---|
| 1 .. 8 | PID (Personal-Id. Es werden ausschließlich Byte 1 - 4 als 32bit Wert verwendet. |
| 9 | FID (Finger-Id) |
| 10, 11 | Reserviert |
| 12 .. 635 | Templatedaten |
In der Bibliothek ist ein Logmechanismus für ein Hintergrundloggen eingebracht, welches alle Funktionsaufrufe in Dateien (Standard: YYYY_MM_DD_DFComDLL_connectionId.log) die in einem angelegten Ordner (Standard: DFComLog) liegen schreibt. Dieses Hintergrundloggen ist standardmäßig aktiviert und kann über die Initialisierungsdatei "DFCom.ini" gesteuert werden. Es werden die letzten zehn aufeinanderfolgenden Anwendungstage mitgeschnitten und die so gesammelten Daten umfassen im Mittel ein Datenvolumen von ca. 300MB.
Der Dateinamen enthält das Datum und die Verbindungs-Id. Die Zeit des Funktionsaufrufes ist die erste Logangabe. Danach folgt durch Tabstopp getrennt die Prozess-Id, Thread-Id, der Funktionsname mit den jeweils übergebenen Parameterwerten. Als Abschluss wird der Rückgabewert (wenn vorhanden) in Klammern angegeben. Bei Parametern die über Zeiger bekannt gegeben werden, wie Fehlerobjekt oder Datenbuffer, werden immer die Übergebenen Werte nicht die Adresse mitgeschrieben. Wenn keine Werte vorliegen (Null-Pointer) werden trotzdem immer alle Tabstopp ausgegeben und es ist somit möglich die Datei für eine weitere Verarbeitung zu verwenden. In einer eckigen Klammer wird nach setzen des Elapse - Schlüssels die Ausführungsdauer der Funktion angegeben, diese gibt an wie lange die Funktion für die Abarbeitung des Befehls benötigte (Stark abhängig von den verwendeten Schnittstellentimeouts).
Beispiel: 2018_11_06_DFComDLL_1.log
Die einzelnen Werte sind mit Tabulator getrennt.
16:43:37 16320 2956 DFCComOpenIV 1 0 4 \\.\COM4 38400 1200 (1, 0) [0.0]
| Uhrzeit | Process-Id | Thread-Id | Funktionsname | Parameterwerte | (Rückgabewert, Fehlernummer) | Ausführungszeit |
|---|---|---|---|---|---|---|
| 16:43:37 | 16320 | 2956 | DFCComOpenIV | 1 0 4 \\.\COM4 38400 1200 | (1, 0) | [0.0] |
Der zu verwendende Dateiname lautet: DFCom.ini
[Log] Enable=1 Path=C:/Users/MMustermann/AppData/Local/datafox Folder=DFComLog Trace=0 Erase=1 Keep=10 Elapse=1 List=1
Kurzbeschreibung der enthaltenen Parameter:
[Docking] Prefer=2
Sektion [Docking] ist global gültig. Für eine Verbindungsspezifische Einstellung verwenden Sie bitte einen Sektionsnamen [Docking_connectionId] z. B. [Docking_5] für die Verbindungs-Id 5.
[Channels] CheckOpenCloseBySameThread=1
Sektion [Channels] ist global gueltig für das Verhalten der Verbindungsklassen.
[XML] createHelpFile=0 docPath=
Sektion [XML] beinhaltet Einstellungen im Bezug auf die Verarbeitung von XML-Konfigurationdateien.
Im folgenden Diagram ist die Suchreihenfolge der DFCom.ini augeführt.
| Bezeichnung | Bedeutung |
|---|---|
| APP_PATH | Pfad der Anwendung (*.exe), welche die DFComDLL einbindet. |
| DFCOM_INI_PATH | Umgebungsvariable mit einem Pfad zur DFCom.ini - Datei. |
| LOCALAPPDATA, HOME | Umgebungsvariablen aus dem Betriebssystem. |
APP_PATH erwartet und wenn sie dort nicht aufgefunden wurde, dann wurde versucht dort eine entsprechende Standarddatei zu erzeugt. 
Es besteht die Möglichkeit über Feldfunktionen des Setups Datendateien zu erstellen. Beispielsweise können Sie per Feldfunktion eine Bildaufnahme der Kamera auslösen. Hierbei wird zum einen eine Bilddatei im Gerätespeicher abgelegt und der Dateiname durch die Feldfunktion zurückgeliefert. Den Dateinamen übernehmen Sie am besten in den zu erzeugenden Datensatz. Wenn Sie den Datensatz dann abrufen, erhalten Sie mit diesem dann den Dateinamen der zu lesenden Bilddatei.
Die Datendatei lesen Sie mit der Funktion DFCFileDownload(), hierbei übergeben Sie als Type-Argument 4 und den entsprechenden Dateinamen. Wenn Sie dem Dateinamen einen Pfad voranstellen, wird die ausgelesene Datei dorthin abgespeichert, ansonsten wird das aktuelle Arbeitsverzeichnis verwendet.
Es existiert eine zweite Möglichkeit auf die Datendateien zuzugreifen. Hierbei übergeben Sie der Funktion DFCFileDownload() als Dateiname IMG_*.png und erhalten die nächste zu lesende Datendatei. Lassen Sie Sich nicht von der hier angewendeten Zeichenfolge täuschen, es handelt sich nicht wie im ersten Augenblick zu erwarten um einen regulären Ausdruck. Wie auch bei dem direkten Lesen einer Datendatei können Sie dem Dateinamen einen Pfad voranstellen, ansonsten wird die Datei im aktuellen Arbeitsverzeichnis abgelegt. Die Datei wird unter ihrem eigentlichen Namen abgespeichert, um diesen nach dem Auslesen zu ermitteln können Sie mit der Funktion DFCGetGlobVar() die Systemvariable SYSTEM.FILETRANSFER auslesen, welche den Dateinamen der zuletzt gelesenen Datei enthält.
Über vorkonfigurierte Konfigurationsdateien können Sie das Geräteverhalten Ihren Bedürfnissen anpassen. Um zum Beispiel die (W)LAN funktionalität DHCP zu aktivieren und deaktivieren, können Sie unterschiedliche Konfigurationsdateien, die Sie über das DatafoxStudioIV verwalten können, übertragen. Ebenfalls lassen sich einzelne Bilder Situationsabhängig ausgetauscht werden, ohne das gesamte Display-Design übertragen zu müssen. Hierzu können Sie die Exportfunktionalität des Display-Designers nutzen, um die Bilder im benötigten Format zu erhalten.