TLS_RECEIVE_2

Typ	Funktionsbaustein
Beschreibung	Der Funktionsbaustein wird zum Empfangen von Daten über TCP (Transmission Control Protocol) oder TLS (Transmission Layer Security) von einem TCP/TLS-fähigen Ethernet-Gerät verwendet. Dies erfolgt über einen TCP/TLS-Socket. Der Socket muss zuerst mit Hilfe des Funktionsbausteins TLS_SOCKET_2 geöffnet werden, bevor Daten empfangen werden können. Nachdem der Socket erfolgreich geöffnet und eine Verbindung aufgebaut wurde, empfängt der Funktionsbaustein die Daten vom Kommunikationspartner entweder über eine reine TCP-Verbindung oder über eine TLS-gesicherte Verbindung. Welcher Verbindungstyp verwendet wird, hängt davon ab, welcher Wert am Eingang START_TLS des Funktionsbausteins TLS_SOCKET_2 anliegt: Bei START_TLS = FALSE verwendet der Funktionsbaustein eine reine TCP-Verbindung, um Daten zu empfangen. Bei START_TLS = TRUE empfängt der FB die Daten über eine TLS-gesicherte Verbindung. Der Funktionsbaustein führt eine Sicherheitsprüfung durch um festzustellen, ob die IEC-Anwendung einen Datenaustausch über eine unsichere (TCP) oder über eine sichere (TLS-gesicherte) Verbindung erwartet. Für die Sicherheitsprüfung vergleicht der Baustein den Wert seines RECEIVE_SECURE-Eingangs mit dem Wert, der am Eingang START_TLS des Funktionsbausteins TLS_SOCKET_2 anliegt. Werden Inkonsistenzen zwischen den Eingangswerten festgestellt, zum Beispiel bei RECEIVE_SECURE = TRUE (IEC-Anwendung erfordert sicheren Datenempfang) und START_TLS = FALSE (TLS-Protokoll noch nicht initialisiert), wird der Ausgang ERROR auf TRUE gesetzt und am Ausgang STATUS der Fehlercode 16#C150 ausgegeben. Der Funktionsbaustein empfängt Daten, wenn der Eingang EN_R (EN_R = ENable_Receive) TRUE ist. Wenn Daten erfolgreich empfangen wurden, wird der Ausgang NDR (NDR = NewDataReceived) in jedem Zyklus auf TRUE gesetzt, in dem die spezifizierte Datenmenge in den DATA-Buffer kopiert wurden. Falls bei gesetztem Eingang EN_R im nächsten Zyklus erneut Daten empfangen werden, bleibt NDR = TRUE und die neuen Daten werden in die an Parameter DATA angeschlossene Variable kopiert. Wenn keine neuen Daten empfangen werden, wird NDR auf FALSE gesetzt. Die IP-Adresse und die Portnummer des Geräts (Absenders) werden an den Ausgängen SOURCE_IP (IP-Adresse des Absenders) und SOURCE_PORT (IP-Port des Absenders) angezeigt. WARNUNG Unbeabsichtigter Betriebszustand des Geräts Stellen Sie sicher, dass das Ändern der Ausgangsdaten nicht zu einem ungewollten oder gefährlichen Verhalten des Gesamtsystems führen kann.
Hinweise	Der mit dem Funktionsbaustein TLS_SOCKET_2 geöffnete Socket kann nur für den Aufruf des Funktionsbausteins TLS_RECEIVE_2 verwendet werden, solange der Ausgang ACTIVE von TLS_SOCKET_2 = TRUE ist. Der Aufruf des Funktionsbausteins TLS_RECEIVE_2 während ACTIVE = FALSE ist, führt zu einem Fehler an TLS_RECEIVE_2 (ERROR = TRUE und STATUS-Code = 0xC210). Das mit dem Funktionsbaustein TLS_SOCKET_2 erzeugte-Sockethandle ist nicht kompatibel mit dem Sockethandle, das mit TCP_SOCKET oder TLS_SOCKET erzeugt wird. Das-Sockethandle kann nur mit den FBs TLS_SEND_2/TLS_RECEIVE_2 verwendet werden. Stellen Sie bei Steuerungen mit integrierter Firewall sicher, dass die Firewall nicht die für die Kommunikation benötigten Ports blockiert. Andernfalls kann keine Verbindung hergestellt werden. Funktionsbausteine müssen instanziiert werden. Der FB-Instanzname muss in der 'Variablen'-Tabelle der POE deklariert werden, in welcher der FB verwendet werden soll. Der Instanzname muss innerhalb der POE eindeutig sein.
Parameter	Eingänge Hinweis Der für den Aufbau der TLS-Kommunikation auf Basis (d.h."on top") der TCP-Kommunikation relevante Parameter ist RECEIVE_SECURE. Die übrigen Eingänge spezifizieren TCP-Funktionalität. EN_R Datentyp: BOOL Beschreibung: Mit einer steigenden Flanke am Eingang EN_R (EN_R = ENable_Receive) wird der Datenempfang angestoßen. Solange EN_R = TRUE ist, können Daten empfangen werden. HANDLE Datentyp: DWORD Beschreibung: Sockethandle, das mit dem Funktionsbaustein TLS_SOCKET_2 geöffnet wurde (siehe auch oben stehende Hinweise). Hinweis Ein Handle, das mit einer Instanz der älteren Implementierung des Funktionsbausteins TCP_SOCKET oder TLS_SOCKET erzeugt wurde, darf nicht mit dem Funktionsbaustein TLS_RECEIVE_2 verwendet werden. Verwenden Sie Handles nur innerhalb derselben "FB-Generation". Der Parameter wird nur in dem Zyklus ausgewertet, in dem am Parameter EN_R eine steigende Flanke erkannt wird. EXP_DATA_CNT Datentyp: UDINT Beschreibung: Länge (in Bytes) der zu empfangenden Daten (EXP_DATA_CNT = EXPected_DATA_CouNT). Die Länge (Anzahl an Bytes) ist kleiner oder gleich der Länge der an DATA angeschlossenen Variable. Dabei gilt Folgendes: Wenn der Wert größer 0 ist, werden auch nur so viele Bytes in die an DATA angeschlossene Variable kopiert. Wenn weniger als die angegebene Anzahl an Bytes empfangen wurde, werden diese Bytes an die bereits empfangenen Bytes in der an DATA angeschlossenen Variable angehängt. Der Ausgang DATA_CNT wird entsprechend inkrementiert. Wurden die erwarteten Bytes (EXP_DATA_CNT) empfangen, wird der Ausgang NDR auf TRUE gesetzt. Andernfalls muss die FB-Instanz erneut aufgerufen werden, bis alle erwarteten Daten empfangen wurden. Wenn mehr als die angegebene Anzahl an Bytes empfangen wurde, wird nur die Anzahl der erwarteten Bytes (EXP_DATA_CNT) in die an DATA angeschlossene Variable kopiert. Ausgang DATA_CNT wird entsprechend inkrementiert und NDR auf TRUE gesetzt. Die restlichen empfangenen, aber noch nicht kopierten Bytes können mit dem nächsten Aufruf der FB-Instanz gelesen werden. Wenn der Wert gleich 0 ist, werden alle Daten in die an DATA angeschlossene Variable kopiert, wie zwischenzeitlich empfangen wurden (maximal jedoch so viele, wie die an DATA angeschlossene Variable lang ist). Der Ausgang DATA_CNT wird entsprechend inkrementiert. Wurden ein oder mehrere Bytes empfangen (DATA_CNT > 0), wird der Ausgang NDR auf TRUE gesetzt. Der Parameter wird nur in dem Zyklus ausgewertet, in dem am Parameter EN_R eine steigende Flanke erkannt wird. Tipp: Sie können mit der Funktion SIZEOF die Größe der Variable, d.h. die Anzahl der für die Variable im Speicher der Steuerung reservierten Bytes ermitteln. RECEIVE_SECURE Datentyp: BOOL Beschreibung: Legt fest, ob die IEC-Anwendung einen Datenaustausch über eine unsichere (TCP) oder über eine sichere (TLS-gesicherte) Verbindung erwartet. TRUE: Anwendung erwartet sicheren Datenempfang (über TLS-gesicherte Verbindung). FALSE: Anwendung erwartet unsicheren Datenempfang (über TCP-Verbindung). Der Wert am Eingang wird mit dem Eingangswert START_TLS des Bausteins TLS_SOCKET_2 verglichen. Werden Inkonsistenzen zwischen den Eingangswerten festgestellt, zum Beispiel bei RECEIVE_SECURE = TRUE (IEC-Anwendung erfordert sicheren Datenempfang) und START_TLS = FALSE (TLS-Protokoll noch nicht initialisiert), wird der Ausgang ERROR auf TRUE gesetzt und am Ausgang STATUS der Fehlercode 16#C150 ausgegeben. Ein-/Ausgang DATA Datentyp: ANY Beschreibung: Datenpuffer, der die empfangenen Daten enthält. Die Daten werden als Byte-Stream übertragen. Es erfolgt keine Little-/Big-Endian-Konvertierung. Ist die angeschlossene Variable ein STRUCT (oder ARRAY OF STRUCT), enthält die Variable im Speicher der Steuerung eventuell Padding Bytes, die im eingehenden Daten-Strom berücksichtigt werden müssen. Ausgänge NDR Datentyp: BOOL Beschreibung: Der Ausgang NDR (NewDataReceived) wird für einen Zyklus auf TRUE gesetzt, sobald die Daten erfolgreich empfangen wurden. Die erfolgreiche Übertragung kann nur in dem Zyklus ausgewertet werden, in dem NDR = TRUE ist. Wenn NDR = TRUE ist, wird mit dem nächsten Aufruf (falls Bytes empfangen wurden) DATA überschrieben (NDR kann wieder TRUE sein). Wenn NDR = FALSE ist, werden mit dem nächsten Aufruf (falls Bytes empfangen wurden) die empfangenen Bytes an DATA angehängt. Der Ausgang DATA_CNT wird entsprechend inkrementiert. NDR wird auf TRUE gesetzt, wenn die Anzahl an erwarteten Bytes empfangen wurden. ERROR Datentyp: BOOL Beschreibung: Bei einem Fehler wird der Ausgang ERROR auf TRUE gesetzt. Der zugehörige Fehlercode wird am Ausgang STATUS angezeigt. Siehe Fehlercodes / Statuscodes für TLS*-Funktionsbausteine . STATUS Datentyp: WORD Beschreibung: Liefert den Fehlercode im Fehlerfall (ERROR = TRUE) oder den aktuellen Status des Funktionsbausteins (ERROR = FALSE). Fehlercodes beginnen mit 16#Cxxx und Statuscodes mit 16#8xxx. Solange der Eingang EN_R auf TRUE gesetzt ist, versucht die FB-Instanz einen Socket zu öffnen. Tritt ein Fehler auf, steuert die FB-Instanz den Ausgang ERROR auf TRUE. Gleichzeitig liefert der STATUS-Ausgang Informationen zur Fehlerursache. Die Ausgänge ERROR und STATUS werden nur für einen Zyklus gesetzt. Beim nächsten Aufruf wird erneut versucht, diesen Socket zu öffnen. Die Versuche werden solange wiederholt, wie ACTIVATE TRUE bleibt. Siehe Fehlercodes / Statuscodes für TLS*-Funktionsbausteine . SOURCE_IP Datentyp: STRING Beschreibung: IP-Adresse des Geräts, von dem Daten empfangen wurden. Im Fehlerfall wird die zuletzt gültige IP-Adresse gehalten. Hinweis Die Zeichenfolge enthält eine IPv4-Adresse. Die IPv4-Adresse besteht aus 4 Zahlen (Werte von 0 bis 255), die durch Punkte voneinander getrennt sind. SOURCE_PORT Datentyp: UINT Beschreibung: Portnummer des Geräts, von dem Daten empfangen wurden. Im Fehlerfall wird die zuletzt gültige Portnummer gehalten. DATA_CNT Datentyp: UDINT Beschreibung: Anzahl der erfolgreich empfangenen Bytes. Die Länge (Anzahl an Bytes) ist kleiner oder gleich der Länge der an DATA angeschlossenen Variable. Der Parameter muss in dem Zyklus ausgewertet werden, in dem NDR = TRUE ist. Tipp: Sie können mit der Funktion SIZEOF die Größe der Variable, d.h. die Anzahl der für die Variable im Speicher der Steuerung reservierten Bytes ermitteln.