Passa al contenuto principale

3. Message Format (Formato del Messaggio)

CoAP si basa sullo scambio di messaggi compatti che, per impostazione predefinita, vengono trasportati su UDP (cioè, ogni messaggio CoAP occupa la sezione dati di un datagramma UDP). CoAP può anche essere utilizzato su Datagram Transport Layer Security (DTLS) (vedere Sezione 9.1). Può anche essere utilizzato su altri trasporti come SMS, TCP o SCTP, la cui specifica esula dall'ambito di questo documento. (CoAP non supporta UDP-lite [RFC3828] e UDP zero checksum [RFC6936].)

I messaggi CoAP sono codificati in un semplice formato binario. Il formato del messaggio inizia con un'intestazione di dimensione fissa di 4 byte. Questa è seguita da un valore Token di lunghezza variabile, che può essere lungo tra 0 e 8 byte.

Dopo il valore Token segue una sequenza di zero o più opzioni CoAP in formato Type-Length-Value (TLV), opzionalmente seguita da un payload che occupa il resto del datagramma.

 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) ...
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

                     Figura 7: Formato del Messaggio

I campi nell'intestazione sono definiti come segue:

Version (Ver, Versione): Intero senza segno a 2 bit. Indica il numero di versione CoAP. Le implementazioni di questa specifica DEVONO impostare questo campo a 1 (binario 01). Altri valori sono riservati per versioni future. I messaggi con numeri di versione sconosciuti DEVONO essere silenziosamente ignorati.

Type (T, Tipo): Intero senza segno a 2 bit. Indica se questo messaggio è di tipo Confirmable (0), Non-confirmable (1), Acknowledgement (2), o Reset (3). La semantica di questi tipi di messaggio è definita nella Sezione 4.

Token Length (TKL, Lunghezza Token): Intero senza segno a 4 bit. Indica la lunghezza del campo Token di lunghezza variabile (0-8 byte). Le lunghezze 9-15 sono riservate, NON DEVONO essere inviate e DEVONO essere elaborate come errore di formato del messaggio.

Code (Codice): Intero senza segno a 8 bit, diviso in una classe a 3 bit (bit più significativi) e un dettaglio a 5 bit (bit meno significativi), documentato come "c.dd" dove "c" è una cifra da 0 a 7 per il sottocampo a 3 bit e "dd" sono due cifre da 00 a 31 per il sottocampo a 5 bit. La classe può indicare una richiesta (0), una risposta di successo (2), una risposta di errore client (4), o una risposta di errore server (5). (Tutti gli altri valori di classe sono riservati.) Come caso speciale, il Code 0.00 indica un messaggio vuoto. Per le richieste, il campo Code indica il metodo di richiesta; per le risposte, un codice di risposta. I valori possibili sono mantenuti nei registri dei codici CoAP (Sezione 12.1). La semantica delle richieste e delle risposte è definita nella Sezione 5.

Message ID (ID del Messaggio): Intero senza segno a 16 bit in ordine di byte di rete. Utilizzato per rilevare la duplicazione dei messaggi e per abbinare i messaggi di tipo Acknowledgement/Reset ai messaggi di tipo Confirmable/Non-confirmable. Le regole per generare un Message ID e abbinare i messaggi sono definite nella Sezione 4.

L'intestazione è seguita dal valore Token, che può essere da 0 a 8 byte, come indicato dal campo Token Length. Il valore Token è utilizzato per correlare richieste e risposte. Le regole per generare un Token e correlare richieste e risposte sono definite nella Sezione 5.3.1.

L'intestazione e il Token sono seguiti da zero o più opzioni (Sezione 3.1). Un'opzione può essere seguita dalla fine del messaggio, da un'altra opzione, o dal marcatore di payload e dal payload.

Dopo l'intestazione, il token e le opzioni (se presenti), può esserci un payload. Se presente e di lunghezza diversa da zero, è preceduto da un marcatore di payload fisso di un singolo byte (0xFF), che indica la fine delle opzioni e l'inizio del payload. I dati del payload si estendono dopo il marcatore fino alla fine del datagramma UDP, cioè, la lunghezza del payload è calcolata dalla dimensione del datagramma. La presenza di un marcatore di payload seguito da un payload di lunghezza zero DEVE essere elaborata come errore di formato del messaggio.

Nota di implementazione: Il valore di byte 0xFF può anche verificarsi all'interno di una lunghezza o valore di opzione, quindi una semplice scansione byte per byte per 0xFF non è una tecnica praticabile per trovare il marcatore di payload. Il byte 0xFF ha la semantica di marcatore di payload solo dove potrebbe verificarsi l'inizio di un'altra opzione.

3.1. Option Format (Formato delle Opzioni)​

CoAP definisce un numero di opzioni che possono essere incluse in un messaggio. Ogni istanza di un'opzione in un messaggio specifica il numero di opzione dell'opzione CoAP definita, la lunghezza del valore dell'opzione e il valore dell'opzione stesso.

Invece di specificare direttamente il numero di opzione, le istanze DEVONO apparire nell'ordine dei loro numeri di opzione e viene utilizzata una codifica delta tra di esse: il numero di opzione per ogni istanza è calcolato come la somma del suo delta e del numero di opzione dell'istanza precedente nel messaggio. Per la prima istanza in un messaggio, si presume un'istanza di opzione precedente con numero di opzione zero. Più istanze della stessa opzione possono essere incluse utilizzando un delta di zero.

I numeri di opzione sono mantenuti nel registro "CoAP Option Numbers" (Sezione 12.2). Vedere la Sezione 5.4 per la semantica delle opzioni definite in questo documento.

  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
\                               \
/                               /
\                               \
+-------------------------------+

                      Figura 8: Formato delle Opzioni

I campi in un'opzione sono definiti come segue:

Option Delta (Delta dell'Opzione): Intero senza segno a 4 bit. Un valore tra 0 e 12 indica il delta dell'opzione. Tre valori sono riservati per costruzioni speciali:

  • 13: Un intero senza segno a 8 bit segue il byte iniziale e indica il delta dell'opzione meno 13.

  • 14: Un intero senza segno a 16 bit in ordine di byte di rete segue il byte iniziale e indica il delta dell'opzione meno 269.

  • 15: Riservato per il marcatore di payload. Se il campo è impostato su questo valore ma l'intero byte non è il marcatore di payload, questo DEVE essere elaborato come errore di formato del messaggio.

Il delta dell'opzione risultante è utilizzato come differenza tra il numero di opzione di questa opzione e quello dell'opzione precedente (o zero per la prima opzione). In altre parole, il numero di opzione è calcolato sommando semplicemente i valori di delta dell'opzione di questa e di tutte le opzioni precedenti prima di essa.

Option Length (Lunghezza dell'Opzione): Intero senza segno a 4 bit. Un valore tra 0 e 12 indica la lunghezza del valore dell'opzione, in byte. Tre valori sono riservati per costruzioni speciali:

  • 13: Un intero senza segno a 8 bit precede il valore dell'opzione e indica la lunghezza dell'opzione meno 13.

  • 14: Un intero senza segno a 16 bit in ordine di byte di rete precede il valore dell'opzione e indica la lunghezza dell'opzione meno 269.

  • 15: Riservato per uso futuro. Se il campo è impostato su questo valore, DEVE essere elaborato come errore di formato del messaggio.

Value (Valore): Una sequenza di esattamente Option Length byte. La lunghezza e il formato del valore dell'opzione dipendono dalla rispettiva opzione, che PUÒ definire valori di lunghezza variabile. Vedere la Sezione 3.2 per i formati utilizzati in questo documento; le opzioni definite in altri documenti POSSONO utilizzare altri formati di valore dell'opzione.

3.2. Option Value Formats (Formati dei Valori delle Opzioni)​

Le opzioni definite in questo documento utilizzano i seguenti formati di valore dell'opzione.

empty (vuoto): Una sequenza di byte di lunghezza zero.

opaque (opaco): Una sequenza di byte opaca.

uint (intero senza segno): Un intero non negativo che è rappresentato in ordine di byte di rete utilizzando il numero di byte dato dal campo Option Length.

Una definizione di opzione può specificare l'intervallo di numeri di byte consentiti; se ha una scelta, un mittente DOVREBBE rappresentare l'intero con il minor numero possibile di byte, cioè senza byte zero iniziali. Ad esempio, il numero 0 è rappresentato con un valore di opzione vuoto (una sequenza di byte di lunghezza zero) e il numero 1 da un singolo byte con il valore numerico di 1 (combinazione di bit 00000001 in notazione bit più significativo prima). Un destinatario DEVE essere preparato a elaborare valori con byte zero iniziali.

Nota di implementazione: Il comportamento eccezionale consentito per il mittente è destinato a implementazioni altamente vincolate e basate su template (ad es. implementazioni hardware) che utilizzano opzioni di dimensione fissa nel template.

string (stringa): Una stringa Unicode che è codificata utilizzando UTF-8 [RFC3629] in forma Net-Unicode [RFC5198].

Si noti che qui, e in tutti gli altri luoghi in cui viene utilizzata la codifica UTF-8 nel protocollo CoAP, l'intenzione è che la stringa codificata possa essere utilizzata direttamente come stringa di byte opaca da un'implementazione CoAP e confrontata per l'uguaglianza. Non c'è aspettativa né necessità di eseguire la normalizzazione all'interno di un'implementazione CoAP (tranne dove le stringhe Unicode vengono importate da fonti esterne al protocollo CoAP che sono note per fornire stringhe Unicode non normalizzate). Si noti anche che le stringhe ASCII (che non utilizzano caratteri di controllo speciali) sono sempre stringhe UTF-8 Net-Unicode valide.

Ultimo aggiornamento il