FB_IotMqtt5ConnAckProperties

Der Funktionsbaustein ermöglicht den Empfang von Statusinformationen des Message Brokers direkt nach dem Connection Acknowledgement, welcher Teil des Verbindungsaufbaus ist. Hierüber kann der Message Broker dem Client Informationen über potenzielle Einschränkungen mitteilen, zum Beispiel eine maximale Paketgröße, die der Message Broker verarbeiten kann.

Es ist Aufgabe des Clients diese Werte abzufragen und ggf. darauf zu reagieren. Wenn der Client ConnAck Properties empfangen hat und diese am Ausgang bereitstellt, wird dies mittels bPropertiesAvailable=TRUE angezeigt.

Allgemeine Beschreibung der Connection Acknowledgement Properties:

Eigenschaft	Beschreibung
Retain available	Gibt an, ob der Message Broker Retain-Nachrichten unterstützt.
Server KeepAlive	Gibt die vom Server zugewiesene KeepAlive-Zeit an.
Shared subscriptions available	Gibt an, ob der Message Broker Shared Subscriptions unterstützt.
Wildcard subscriptions available	Gibt an, ob der Message Broker Wildcard Subscriptions unterstützt, z.B. Subscriptions auf ein # oder + Topic.
Authentication data	Beinhaltet die Authentifizierungsdaten, abhängig von der verwendeten Authentifizierungsmethode.
Maximum packet size	Gibt die maximale Paketgröße des Control Pakets an. Wenn dieser Wert nicht angegeben ist, dann ist keine Maximalgröße explizit gesetzt.
Maximum QoS	Gibt den maximalen QoS Level an, den der Message Broker unterstützt. Einige Message Broker Implementierungen unterstützen zum Beispiel kein QoS 2.
Reason code	Optionaler Reason Code, welchen der Message Broker im Rahmen des ConnAck-Verfahrens an den Client übermitteln kann. Im Zusammenspiel mit der Server Reference (s.u.) kann der Message Broker dem Client hierüber z.B. mitteilen, dass er temporär oder permanent nicht erreichbar und/oder unter einer neuen Adresse erreichbar ist.
Maximum receive	Der Server verwendet diese Eigenschaft, um die Anzahl an QoS1 und QoS2 Publishes zu limitieren, die er für den Client bereit ist gleichzeitig zu verarbeiten.
Session expiry interval	Der Server kann hierüber den Client informieren, dass er ein anderes Session Expiry Interval verwendet als ursprünglich vom Client angefordert.
Response info	Optionale Rückgabeinformationen vom Message Broker an den Client. Ein Anwendungsfall hierfür kann zum Beispiel sein, dass der Broker dem Client einen Topic-Bereich mitteilt der dem Client zugewiesen wurde und auf den er zugreifen kann.
Maximum topic alias	Gibt den maximalen Wert an, der für einen Topic Alias verwendet werden kann.
Assigned client ID	Gibt die vom Message Broker zugewiesene ClientID zurück, sofern der Client keine eigene ClientID angegeben hat.
Server reference	Optionale (Adress-) Referenz auf einen weiteren Message Broker, z.B. bei Reason Code 0x9C oder 0x9D (Server unavailable, Server has moved).
User Properties	User Properties sind Key/Value Paare, welche an die PublishProperties angehängt werden können. Dies erfolgt mittels des Bausteins FB_IotMqtt5UserProperties. Die Bedeutung der UserProperties ist nicht Bestandteil der MQTT5 Spezifikation und somit applikationsspezifisch.

Syntax

Definition:

FUNCTION_BLOCK FB_IotMqtt5ConnAckProperties EXTENDS FB_IotMqtt5UserProperties
VAR_OUTPUT
    bError           : BOOL;
    hrErrorCode      : HRESULT;
END_VAR

Ausgänge

Name	Typ	Beschreibung
bError	BOOL	Wird TRUE, sobald eine Fehlersituation eintritt.
hrErrorCode	HRESULT	Liefert bei einem gesetzten bError-Ausgang einen Fehlercode. Eine Erläuterung zu den möglichen Fehlercodes befindet sich im Anhang.

Eigenschaften

Name	Typ	Zugriff	Beschreibung
bPropertiesAvailable	BOOL	Get	Gibt an, ob Properties vorhanden sind.
bRetainAvailable	BOOL	Get	Gibt an, ob der Message Broker Retain-Nachrichten unterstützt.
bServerKeepAlive	BOOL	Get	Gibt an, ob vom Server ein anderer KeepAlive-Wert verwendet wird als ursprünglich vom Client angefragt wurde.
bSessionPresent	BOOL	Get	Gibt an, ob der Client schon eine Session mit dem Broker hat.
bSharedSubAvailable	BOOL	Get	Gibt an, ob der Message Broker Shared Subscriptions unterstützt.
bSubIdAvailable	BOOL	Get	Gibt an, ob der Message Broker die Verwendung von Subscription Identifiers unterstützt.
bWildcardSubAvailable	BOOL	Get	Gibt an, ob der Message Broker Wildcard Subscriptions unterstützt.
nAuthDataSize	UINT	Get	Gibt die Größe der Authentication Data an.
nMaxPackateSize	UDINT	Get	Gibt die maximale Paketgröße des Control-Pakets an.
nMaxQoS	BYTE	Get	Gibt den maximalen QoS Level an, den der Message Broker unterstützt.
nReasonCode	BYTE	Get	Gibt einen optionalen Reason Code an, welchen der Server im Rahmen des ConnAck-Verfahrens an den Client übermittelt.
nReceiveMax	UINT	Get	Maximale Anzahl an gleichzeitigen QoS 1 und 2 publishes, die der Server unterstützt.
nResponseInfoSize	UINT	Get	Gibt die Größe der Response-Information zurück.
nSessionExpiryInterval	UDINT	Get	Wert in Sekunden für das vom Server unterstützte Session Expiry Interval.
nTopicAliasMax	UINT	Get	Maximalwert für den Topic Alias, den der Server unterstützt.
sAssignedClientId	STRING	Get	Vom Message Broker zugewiesene Client-ID.
sAuthMethod	STRING	Get	Gibt den Namen der verwendeten Authentifizierungsmethode zurück.
sReasonString	STRING	Get	Leserliche Variante des Reason Code.
sServerReference	STRING	Get	Optionale Server Reference, das Format ist nicht durch die Spezifikation festgelegt.

Methoden

Name	Beschreibung
GetAuthData	Gibt die Authentication Data zurück, welche abhängig von der verwendeten Authentication Method ist.
GetResponseInfo	Ermöglicht das Auslesen der Response Information. Hiermit kann der Message Broker dem Client eine Basis für die Erzeugung des Response Topics beim Req/Res-Verfahren übermitteln. Das Format ist hierbei nicht durch die Spezifikation festgelegt.
SetConnAckProperties	Ermöglicht das Setzen der ConnAck Properties.

Voraussetzungen

Entwicklungsumgebung	Zielplattform	Einzubindende SPS-Bibliotheken
TwinCAT v3.1.4026.0	IPC oder CX (x86, x64, ARM)	Tc3_IotBase (>= v3.4.2.0)