Zum Hauptinhalt springen

3. Message Format (Nachrichtenformat)

CoAP basiert auf dem Austausch kompakter Nachrichten, die standardmäßig über UDP transportiert werden (d.h. jede CoAP-Nachricht belegt den Datenbereich eines UDP-Datagramms). CoAP kann auch über Datagram Transport Layer Security (DTLS) verwendet werden (siehe Abschnitt 9.1). Es kann auch über andere Transporte wie SMS, TCP oder SCTP verwendet werden, deren Spezifikation außerhalb des Geltungsbereichs dieses Dokuments liegt. (CoAP unterstützt weder UDP-lite [RFC3828] noch UDP zero checksum [RFC6936].)

CoAP-Nachrichten werden in einem einfachen binären Format codiert. Das Nachrichtenformat beginnt mit einem festen 4-Byte-Header. Diesem folgt ein Token-Wert variabler Länge, der zwischen 0 und 8 Bytes lang sein kann.

Nach dem Token-Wert folgt eine Sequenz von null oder mehr CoAP-Optionen im Type-Length-Value (TLV) Format, optional gefolgt von einer Nutzlast, die den Rest des Datagramms einnimmt.

 0                   1                   2                   3
 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|Ver| T |  TKL  |      Code     |          Message ID           |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|   Token (if any, TKL bytes) ...
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|   Options (if any) ...
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|1 1 1 1 1 1 1 1|    Payload (if any) ...
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

                     Abbildung 7: Nachrichtenformat

Die Felder im Header sind wie folgt definiert:

Version (Ver): 2-Bit vorzeichenlose Ganzzahl. Gibt die CoAP-Versionsnummer an. Implementierungen dieser Spezifikation MÜSSEN dieses Feld auf 1 (binär 01) setzen. Andere Werte sind für zukünftige Versionen reserviert. Nachrichten mit unbekannten Versionsnummern MÜSSEN stillschweigend ignoriert werden.

Type (T, Typ): 2-Bit vorzeichenlose Ganzzahl. Gibt an, ob diese Nachricht vom Typ Confirmable (0), Non-confirmable (1), Acknowledgement (2) oder Reset (3) ist. Die Semantik dieser Nachrichtentypen ist in Abschnitt 4 definiert.

Token Length (TKL, Token-Länge): 4-Bit vorzeichenlose Ganzzahl. Gibt die Länge des Token-Feldes variabler Länge an (0-8 Bytes). Die Längen 9-15 sind reserviert, DÜRFEN NICHT gesendet werden und MÜSSEN als Nachrichtenformatfehler verarbeitet werden.

Code (Code): 8-Bit vorzeichenlose Ganzzahl, aufgeteilt in eine 3-Bit-Klasse (höchstwertige Bits) und ein 5-Bit-Detail (niederwertigste Bits), dokumentiert als "c.dd", wobei "c" eine Ziffer von 0 bis 7 für das 3-Bit-Teilfeld und "dd" zwei Ziffern von 00 bis 31 für das 5-Bit-Teilfeld sind. Die Klasse kann eine Anfrage (0), eine Erfolgsantwort (2), eine Client-Fehlerantwort (4) oder eine Server-Fehlerantwort (5) anzeigen. (Alle anderen Klassenwerte sind reserviert.) Als Spezialfall zeigt Code 0.00 eine leere Nachricht an. Für Anfragen gibt das Code-Feld die Anfragemethode an; für Antworten einen Antwortcode. Mögliche Werte werden in den CoAP Code Registries (Abschnitt 12.1) verwaltet. Die Semantik von Anfragen und Antworten ist in Abschnitt 5 definiert.

Message ID (Nachrichten-ID): 16-Bit vorzeichenlose Ganzzahl in Netzwerk-Byte-Reihenfolge. Wird verwendet, um Nachrichtenduplizierung zu erkennen und um Nachrichten vom Typ Acknowledgement/Reset mit Nachrichten vom Typ Confirmable/Non-confirmable abzugleichen. Die Regeln für die Generierung einer Message ID und das Abgleichen von Nachrichten sind in Abschnitt 4 definiert.

Dem Header folgt der Token-Wert, der 0 bis 8 Bytes lang sein kann, wie vom Token Length-Feld angegeben. Der Token-Wert wird verwendet, um Anfragen und Antworten zu korrelieren. Die Regeln für die Generierung eines Tokens und die Korrelation von Anfragen und Antworten sind in Abschnitt 5.3.1 definiert.

Dem Header und Token folgen null oder mehr Optionen (Abschnitt 3.1). Einer Option kann das Ende der Nachricht, eine andere Option oder der Nutzlast-Marker und die Nutzlast folgen.

Nach dem Header, Token und Optionen (falls vorhanden) kann eine Nutzlast vorhanden sein. Wenn vorhanden und nicht null lang, wird ihr ein fester Ein-Byte-Nutzlast-Marker (0xFF) vorangestellt, der das Ende der Optionen und den Beginn der Nutzlast anzeigt. Die Nutzlastdaten erstrecken sich vom Marker bis zum Ende des UDP-Datagramms, d.h. die Nutzlastlänge wird aus der Datagrammgröße berechnet. Das Vorhandensein eines Nutzlast-Markers gefolgt von einer Nutzlast mit null Länge MUSS als Nachrichtenformatfehler verarbeitet werden.

Implementierungshinweis: Der Bytewert 0xFF kann auch innerhalb einer Optionslänge oder eines Werts auftreten, daher ist ein einfacher byteweiser Scan nach 0xFF keine praktikable Technik zum Finden des Nutzlast-Markers. Das Byte 0xFF hat nur dort die Semantik eines Nutzlast-Markers, wo der Beginn einer anderen Option auftreten könnte.

3.1. Option Format (Optionsformat)​

CoAP definiert eine Reihe von Optionen, die in einer Nachricht enthalten sein können. Jede Instanz einer Option in einer Nachricht gibt die Optionsnummer der definierten CoAP-Option, die Länge des Optionswerts und den Optionswert selbst an.

Anstatt die Optionsnummer direkt anzugeben, MÜSSEN die Instanzen in der Reihenfolge ihrer Optionsnummern erscheinen, und zwischen ihnen wird eine Delta-Codierung verwendet: Die Optionsnummer für jede Instanz wird als Summe ihres Deltas und der Optionsnummer der vorhergehenden Instanz in der Nachricht berechnet. Für die erste Instanz in einer Nachricht wird eine vorhergehende Optionsinstanz mit Optionsnummer null angenommen. Mehrere Instanzen derselben Option können eingeschlossen werden, indem ein Delta von null verwendet wird.

Optionsnummern werden im "CoAP Option Numbers" Register (Abschnitt 12.2) verwaltet. Siehe Abschnitt 5.4 für die Semantik der in diesem Dokument definierten Optionen.

  0   1   2   3   4   5   6   7
+---------------+---------------+
|               |               |
|  Option Delta | Option Length |   1 byte
|               |               |
+---------------+---------------+
\                               \
/         Option Delta          /   0-2 bytes
\          (extended)           \
+-------------------------------+
\                               \
/         Option Length         /   0-2 bytes
\          (extended)           \
+-------------------------------+
\                               \
/                               /
\                               \
/         Option Value          /   0 or more bytes
\                               \
/                               /
\                               \
+-------------------------------+

                      Abbildung 8: Optionsformat

Die Felder in einer Option sind wie folgt definiert:

Option Delta (Options-Delta): 4-Bit vorzeichenlose Ganzzahl. Ein Wert zwischen 0 und 12 gibt das Options-Delta an. Drei Werte sind für spezielle Konstruktionen reserviert:

  • 13: Eine 8-Bit vorzeichenlose Ganzzahl folgt dem Anfangsbyte und gibt das Options-Delta minus 13 an.

  • 14: Eine 16-Bit vorzeichenlose Ganzzahl in Netzwerk-Byte-Reihenfolge folgt dem Anfangsbyte und gibt das Options-Delta minus 269 an.

  • 15: Reserviert für den Nutzlast-Marker. Wenn das Feld auf diesen Wert gesetzt ist, aber das gesamte Byte nicht der Nutzlast-Marker ist, MUSS dies als Nachrichtenformatfehler verarbeitet werden.

Das resultierende Options-Delta wird als Differenz zwischen der Optionsnummer dieser Option und der der vorherigen Option (oder null für die erste Option) verwendet. Mit anderen Worten, die Optionsnummer wird berechnet, indem einfach die Options-Delta-Werte dieser und aller vorherigen Optionen davor summiert werden.

Option Length (Optionslänge): 4-Bit vorzeichenlose Ganzzahl. Ein Wert zwischen 0 und 12 gibt die Länge des Optionswerts in Bytes an. Drei Werte sind für spezielle Konstruktionen reserviert:

  • 13: Eine 8-Bit vorzeichenlose Ganzzahl geht dem Optionswert voraus und gibt die Optionslänge minus 13 an.

  • 14: Eine 16-Bit vorzeichenlose Ganzzahl in Netzwerk-Byte-Reihenfolge geht dem Optionswert voraus und gibt die Optionslänge minus 269 an.

  • 15: Reserviert für zukünftige Verwendung. Wenn das Feld auf diesen Wert gesetzt ist, MUSS es als Nachrichtenformatfehler verarbeitet werden.

Value (Wert): Eine Sequenz von genau Option Length Bytes. Die Länge und das Format des Optionswerts hängen von der jeweiligen Option ab, die Werte variabler Länge definieren KANN. Siehe Abschnitt 3.2 für die in diesem Dokument verwendeten Formate; in anderen Dokumenten definierte Optionen KÖNNEN andere Optionswertformate verwenden.

3.2. Option Value Formats (Optionswertformate)​

Die in diesem Dokument definierten Optionen verwenden die folgenden Optionswertformate.

empty (leer): Eine Bytesequenz mit null Länge.

opaque (undurchsichtig): Eine undurchsichtige Bytesequenz.

uint (vorzeichenlose Ganzzahl): Eine nicht negative Ganzzahl, die in Netzwerk-Byte-Reihenfolge unter Verwendung der durch das Option Length-Feld angegebenen Anzahl von Bytes dargestellt wird.

Eine Optionsdefinition kann den Bereich zulässiger Bytezahlen angeben; wenn sie die Wahl hat, SOLLTE ein Sender die Ganzzahl mit so wenigen Bytes wie möglich darstellen, d.h. ohne führende Null-Bytes. Zum Beispiel wird die Zahl 0 mit einem leeren Optionswert (einer Bytesequenz mit null Länge) dargestellt und die Zahl 1 durch ein einzelnes Byte mit dem numerischen Wert 1 (Bitkombination 00000001 in höchstwertiges Bit zuerst Notation). Ein Empfänger MUSS darauf vorbereitet sein, Werte mit führenden Null-Bytes zu verarbeiten.

Implementierungshinweis: Das für den Sender zulässige außergewöhnliche Verhalten ist für stark eingeschränkte, vorlagenbasierte Implementierungen (z.B. Hardware-Implementierungen) gedacht, die Optionen fester Größe in der Vorlage verwenden.

string (Zeichenkette): Eine Unicode-Zeichenkette, die mit UTF-8 [RFC3629] in Net-Unicode-Form [RFC5198] codiert ist.

Beachten Sie, dass hier und an allen anderen Stellen, an denen UTF-8-Codierung im CoAP-Protokoll verwendet wird, die Absicht besteht, dass die codierte Zeichenkette direkt als undurchsichtige Bytezeichenkette von einer CoAP-Implementierung verwendet und auf Gleichheit verglichen werden kann. Es gibt keine Erwartung und keine Notwendigkeit, eine Normalisierung innerhalb einer CoAP-Implementierung durchzuführen (außer wo Unicode-Zeichenketten aus Quellen außerhalb des CoAP-Protokolls importiert werden, von denen bekannt ist, dass sie nicht normalisierte Unicode-Zeichenketten liefern). Beachten Sie auch, dass ASCII-Zeichenketten (die keine speziellen Steuerzeichen verwenden) immer gültige UTF-8 Net-Unicode-Zeichenketten sind.

Letztes Update am