TLS_RECEIVE

Hinweis Für diesen Funktionsbaustein ist eine neue Implementierung verfügbar, der die Firmware-Version 2021.3 oder neuer erfordert. Der neue FB kombiniert die Handhabung von TCP- und TLS-Kommunikation. Außerdem ermöglicht er die Kommunikation eines TCP/TLS-Servers mit mehreren Clients. Weitere Informationen finden Sie im Thema "TLS_RECEIVE_2".

Typ	Funktionsbaustein
Beschreibung	Der Funktionsbaustein wird für den Datenempfang über TLS (Transport Layer Security) von einem TLS-fähigen Ethernet-Gerät verwendet. Dies erfolgt mit Hilfe eines TLS-Sockets. Der Socket muss zuerst mit Hilfe des Funktionsbausteins TLS_SOCKET 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 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 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 geöffnete TLS-Socket kann nur für den Aufruf des Funktionsbausteins TLS_RECEIVE verwendet werden, solange der Ausgang ACTIVE des Funktionsbausteins TLS_SOCKET gesetzt ist. Der Aufruf des Funktionsbausteins TLS_RECEIVE während ACTIVE = FALSE ist, führt zu einem Fehler am Funktionsbaustein TLS_RECEIVE (ERROR = TRUE und STATUS-Code = 0xC210 ausgegeben). Das mit dem Funktionsbaustein TLS_SOCKET erzeugte TLS-Sockethandle ist nicht kompatibel mit dem TCP-Sockethandle, das mit dem Baustein TCP_SOCKET erzeugt wird. Das TLS-Sockethandle kann nur mit den Funktionsbausteinen TLS_SEND und TLS_RECEIVE verwendet werden, das TCP-Sockethandle nur mit den FBs TCP_SEND und TCP_RECEIVE. 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 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 geöffnet wurde (siehe auch oben stehende Hinweise). 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 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. Siehe Fehlercodes / Statuscodes für TLS*-Funktionsbausteine . SOURCE_IP Datentyp: STRING Beschreibung: IP-Adresse des Geräts, von dem Daten empfangen wurden. 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. 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.