Aller au contenu principal

3. Message Format (Format de Message)

CoAP est basé sur l'échange de messages compacts qui, par défaut, sont transportés sur UDP (c'est-à-dire que chaque message CoAP occupe la section de données d'un datagramme UDP). CoAP peut également être utilisé sur Datagram Transport Layer Security (DTLS) (voir Section 9.1). Il peut également être utilisé sur d'autres transports tels que SMS, TCP ou SCTP, dont la spécification est hors de la portée de ce document. (CoAP ne prend pas en charge UDP-lite [RFC3828] et UDP zero checksum [RFC6936].)

Les messages CoAP sont encodés dans un format binaire simple. Le format de message commence par un en-tête de taille fixe de 4 octets. Ceci est suivi d'une valeur de Token de longueur variable, qui peut avoir entre 0 et 8 octets de long.

Après la valeur Token vient une séquence de zéro ou plusieurs Options CoAP au format Type-Length-Value (TLV), éventuellement suivie d'une charge utile qui occupe le reste du datagramme.

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

                     Figure 7: Format de Message

Les champs dans l'en-tête sont définis comme suit:

Version (Ver): Entier non signé de 2 bits. Indique le numéro de version CoAP. Les implémentations de cette spécification DOIVENT définir ce champ à 1 (binaire 01). Les autres valeurs sont réservées pour les versions futures. Les messages avec des numéros de version inconnus DOIVENT être silencieusement ignorés.

Type (T): Entier non signé de 2 bits. Indique si ce message est de type Confirmable (0), Non-confirmable (1), Acknowledgement (2), ou Reset (3). La sémantique de ces types de messages est définie dans la Section 4.

Token Length (TKL, Longueur de Token): Entier non signé de 4 bits. Indique la longueur du champ Token de longueur variable (0-8 octets). Les longueurs 9-15 sont réservées, NE DOIVENT PAS être envoyées et DOIVENT être traitées comme une erreur de format de message.

Code: Entier non signé de 8 bits, divisé en une classe de 3 bits (bits les plus significatifs) et un détail de 5 bits (bits les moins significatifs), documenté comme "c.dd" où "c" est un chiffre de 0 à 7 pour le sous-champ de 3 bits et "dd" sont deux chiffres de 00 à 31 pour le sous-champ de 5 bits. La classe peut indiquer une requête (0), une réponse de succès (2), une réponse d'erreur client (4), ou une réponse d'erreur serveur (5). (Toutes les autres valeurs de classe sont réservées.) Comme cas spécial, le Code 0.00 indique un message vide. Pour les requêtes, le champ Code indique la méthode de requête; pour les réponses, un code de réponse. Les valeurs possibles sont maintenues dans les registres de codes CoAP (Section 12.1). La sémantique des requêtes et des réponses est définie dans la Section 5.

Message ID (ID de Message): Entier non signé de 16 bits en ordre d'octets réseau. Utilisé pour détecter la duplication de messages et pour faire correspondre les messages de type Acknowledgement/Reset aux messages de type Confirmable/Non-confirmable. Les règles pour générer un ID de message et faire correspondre les messages sont définies dans la Section 4.

L'en-tête est suivi de la valeur Token, qui peut avoir de 0 à 8 octets, comme indiqué par le champ Token Length. La valeur Token est utilisée pour corréler les requêtes et les réponses. Les règles pour générer un Token et corréler les requêtes et les réponses sont définies dans la Section 5.3.1.

L'en-tête et le Token sont suivis de zéro ou plusieurs Options (Section 3.1). Une Option peut être suivie de la fin du message, d'une autre Option, ou du marqueur de charge utile et de la charge utile.

Après l'en-tête, le token et les options (le cas échéant), il peut y avoir une charge utile. Si elle est présente et de longueur non nulle, elle est préfixée par un marqueur de charge utile fixe d'un seul octet (0xFF), qui indique la fin des options et le début de la charge utile. Les données de charge utile s'étendent après le marqueur jusqu'à la fin du datagramme UDP, c'est-à-dire que la longueur de la charge utile est calculée à partir de la taille du datagramme. La présence d'un marqueur de charge utile suivi d'une charge utile de longueur nulle DOIT être traitée comme une erreur de format de message.

Note d'implémentation: La valeur d'octet 0xFF peut également se produire dans une longueur ou une valeur d'option, donc un simple balayage octet par octet pour 0xFF n'est pas une technique viable pour trouver le marqueur de charge utile. L'octet 0xFF n'a la sémantique de marqueur de charge utile que là où le début d'une autre option pourrait se produire.

3.1. Option Format (Format d'Option)​

CoAP définit un certain nombre d'options qui peuvent être incluses dans un message. Chaque instance d'une option dans un message spécifie le numéro d'option de l'option CoAP définie, la longueur de la valeur d'option et la valeur d'option elle-même.

Au lieu de spécifier directement le numéro d'option, les instances DOIVENT apparaître dans l'ordre de leurs numéros d'option et un encodage delta est utilisé entre elles: le numéro d'option pour chaque instance est calculé comme la somme de son delta et du numéro d'option de l'instance précédente dans le message. Pour la première instance dans un message, une instance d'option précédente avec le numéro d'option zéro est supposée. Plusieurs instances de la même option peuvent être incluses en utilisant un delta de zéro.

Les numéros d'option sont maintenus dans le registre "CoAP Option Numbers" (Section 12.2). Voir la Section 5.4 pour la sémantique des options définies dans ce document.

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

                      Figure 8: Format d'Option

Les champs dans une Option sont définis comme suit:

Option Delta (Delta d'Option): Entier non signé de 4 bits. Une valeur entre 0 et 12 indique le delta d'option. Trois valeurs sont réservées pour des constructions spéciales:

  • 13: Un entier non signé de 8 bits suit l'octet initial et indique le delta d'option moins 13.

  • 14: Un entier non signé de 16 bits en ordre d'octets réseau suit l'octet initial et indique le delta d'option moins 269.

  • 15: Réservé pour le marqueur de charge utile. Si le champ est défini sur cette valeur mais que l'octet entier n'est pas le marqueur de charge utile, cela DOIT être traité comme une erreur de format de message.

Le delta d'option résultant est utilisé comme la différence entre le numéro d'option de cette option et celui de l'option précédente (ou zéro pour la première option). En d'autres termes, le numéro d'option est calculé en additionnant simplement les valeurs de delta d'option de cette option et de toutes les options précédentes avant elle.

Option Length (Longueur d'Option): Entier non signé de 4 bits. Une valeur entre 0 et 12 indique la longueur de la valeur d'option, en octets. Trois valeurs sont réservées pour des constructions spéciales:

  • 13: Un entier non signé de 8 bits précède la valeur d'option et indique la longueur d'option moins 13.

  • 14: Un entier non signé de 16 bits en ordre d'octets réseau précède la valeur d'option et indique la longueur d'option moins 269.

  • 15: Réservé pour une utilisation future. Si le champ est défini sur cette valeur, il DOIT être traité comme une erreur de format de message.

Value (Valeur): Une séquence d'exactement Option Length octets. La longueur et le format de la valeur d'option dépendent de l'option respective, qui PEUT définir des valeurs de longueur variable. Voir la Section 3.2 pour les formats utilisés dans ce document; les options définies dans d'autres documents PEUVENT utiliser d'autres formats de valeur d'option.

3.2. Option Value Formats (Formats de Valeur d'Option)​

Les options définies dans ce document utilisent les formats de valeur d'option suivants.

empty (vide): Une séquence d'octets de longueur nulle.

opaque: Une séquence d'octets opaque.

uint (entier non signé): Un entier non négatif qui est représenté en ordre d'octets réseau en utilisant le nombre d'octets donné par le champ Option Length.

Une définition d'option peut spécifier la plage de nombres d'octets admissibles; si elle a le choix, un expéditeur DEVRAIT représenter l'entier avec aussi peu d'octets que possible, c'est-à-dire sans octets de zéro de tête. Par exemple, le nombre 0 est représenté par une valeur d'option vide (une séquence d'octets de longueur nulle) et le nombre 1 par un seul octet avec la valeur numérique de 1 (combinaison de bits 00000001 en notation bit le plus significatif en premier). Un destinataire DOIT être préparé à traiter des valeurs avec des octets de zéro de tête.

Note d'implémentation: Le comportement exceptionnel autorisé pour l'expéditeur est destiné aux implémentations hautement contraintes et basées sur des modèles (par exemple, les implémentations matérielles) qui utilisent des options de taille fixe dans le modèle.

string (chaîne): Une chaîne Unicode qui est encodée en utilisant UTF-8 [RFC3629] sous forme Net-Unicode [RFC5198].

Notez qu'ici, et dans tous les autres endroits où l'encodage UTF-8 est utilisé dans le protocole CoAP, l'intention est que la chaîne encodée puisse être directement utilisée comme une chaîne d'octets opaque par une implémentation CoAP et comparée pour l'égalité. Il n'y a pas d'attente ni de besoin d'effectuer une normalisation au sein d'une implémentation CoAP (sauf où les chaînes Unicode sont importées de sources extérieures au protocole CoAP qui sont connues pour fournir des chaînes Unicode non normalisées). Notez également que les chaînes ASCII (qui n'utilisent pas de caractères de contrôle spéciaux) sont toujours des chaînes UTF-8 Net-Unicode valides.

Dernière mise à jour le