pub struct OptNumber(pub u32);Expand description
Option Numbers
generated from RFC7252 section 5.4.6
An Option is identified by an option number, which also provides some additional semantics information, e.g., odd numbers indicate a critical option, while even numbers indicate an elective option. Note that this is not just a convention, it is a feature of the protocol: Whether an option is elective or critical is entirely determined by whether its option number is even or odd.
More generally speaking, an Option number is constructed with a bit mask to indicate if an option is Critical or Elective, Unsafe or Safe-to-Forward, and, in the case of Safe-to-Forward, to provide a Cache-Key indication as shown by the following figure. In the following text, the bit mask is expressed as a single byte that is applied to the least significant byte of the option number in unsigned integer representation. When bit 7 (the least significant bit) is 1, an option is Critical (and likewise Elective when 0). When bit 6 is 1, an option is Unsafe (and likewise Safe-to-Forward when 0). When bit 6 is 0, i.e., the option is not Unsafe, it is not a Cache-Key (NoCacheKey) if and only if bits 3-5 are all set to 1; all other bit combinations mean that it indeed is a Cache-Key. These classes of options are explained in the next sections.
0 1 2 3 4 5 6 7
+---+---+---+---+---+---+---+---+
| | NoCacheKey| U | C |
+---+---+---+---+---+---+---+---+
Figure 10: Option Number Mask (Least Significant Byte)An endpoint may use an equivalent of the C code in Figure 11 to derive the characteristics of an option number “onum”.
Critical = (onum & 1);
UnSafe = (onum & 2);
NoCacheKey = ((onum & 0x1e) == 0x1c);
Figure 11: Determining Characteristics from an Option NumberThe option numbers for the options defined in this document are listed in the “CoAP Option Numbers” registry (Section 12.2).
RFC7252 Section 12.2 Core CoAP Option Numbers
## CoAP Option Numbers Registry [_generated from RFC7252 section 12.2_](https://datatracker.ietf.org/doc/html/rfc7252#section-12.2)This document defines a sub-registry for the Option Numbers used in CoAP options within the “CoRE Parameters” registry. The name of the sub-registry is “CoAP Option Numbers”.
Each entry in the sub-registry must include the Option Number, the name of the option, and a reference to the option’s documentation.
Initial entries in this sub-registry are as follows:
+--------+------------------+-----------+
| Number | Name | Reference |
+--------+------------------+-----------+
| 0 | (Reserved) | [RFC7252] |
| 1 | If-Match | [RFC7252] |
| 3 | Uri-Host | [RFC7252] |
| 4 | ETag | [RFC7252] |
| 5 | If-None-Match | [RFC7252] |
| 7 | Uri-Port | [RFC7252] |
| 8 | Location-Path | [RFC7252] |
| 11 | Uri-Path | [RFC7252] |
| 12 | Content-Format | [RFC7252] |
| 14 | Max-Age | [RFC7252] |
| 15 | Uri-Query | [RFC7252] |
| 17 | Accept | [RFC7252] |
| 20 | Location-Query | [RFC7252] |
| 35 | Proxy-Uri | [RFC7252] |
| 39 | Proxy-Scheme | [RFC7252] |
| 60 | Size1 | [RFC7252] |
| 128 | (Reserved) | [RFC7252] |
| 132 | (Reserved) | [RFC7252] |
| 136 | (Reserved) | [RFC7252] |
| 140 | (Reserved) | [RFC7252] |
+--------+------------------+-----------+
Table 7: CoAP Option NumbersThe IANA policy for future additions to this sub-registry is split into three tiers as follows. The range of 0..255 is reserved for options defined by the IETF (IETF Review or IESG Approval). The range of 256..2047 is reserved for commonly used options with public specifications (Specification Required). The range of 2048..64999 is for all other options including private or vendor-specific ones, which undergo a Designated Expert review to help ensure that the option semantics are defined correctly. The option numbers between 65000 and 65535 inclusive are reserved for experiments. They are not meant for vendor-specific use of any kind and MUST NOT be used in operational deployments.
+-------------+---------------------------------------+
| Range | Registration Procedures |
+-------------+---------------------------------------+
| 0-255 | IETF Review or IESG Approval |
| 256-2047 | Specification Required |
| 2048-64999 | Expert Review |
| 65000-65535 | Experimental use (no operational use) |
+-------------+---------------------------------------+
Table 8: CoAP Option Numbers: Registration ProceduresThe documentation of an Option Number should specify the semantics of an option with that number, including the following properties:
o The meaning of the option in a request.
o The meaning of the option in a response.
o Whether the option is critical or elective, as determined by the Option Number.
o Whether the option is Safe-to-Forward, and, if yes, whether it is part of the Cache-Key, as determined by the Option Number (see Section 5.4.2).
o The format and length of the option’s value.
o Whether the option must occur at most once or whether it can occur multiple times.
o The default value, if any. For a critical option with a default value, a discussion on how the default value enables processing by implementations that do not support the critical option (Section 5.4.4).
OptNumber struct
Because Option Numbers are only able to be computed in the context of other options, in order to
get Option Numbers you must have a collection of Opts, and use the provided EnumerateOptNumbers.
Tuple Fields
0: u32Implementations
sourceimpl OptNumber
impl OptNumber
sourcepub fn must_be_processed(&self) -> OptionMustBeProcessed
pub fn must_be_processed(&self) -> OptionMustBeProcessed
Whether or not this option may be ignored by a server
sourcepub fn when_unsupported_by_proxy(&self) -> WhenOptionUnsupportedByProxy
pub fn when_unsupported_by_proxy(&self) -> WhenOptionUnsupportedByProxy
Whether or not this option may be forwarded blindly by a proxy that does not support processing it
sourcepub fn when_option_changes(&self) -> WhenOptionChanges
pub fn when_option_changes(&self) -> WhenOptionChanges
Whether or not different values for this option should yield proxies’ cached response
(when the proxy does not support processing it and the option is safe to forward)
Trait Implementations
sourceimpl PartialOrd<OptNumber> for OptNumber
impl PartialOrd<OptNumber> for OptNumber
sourcefn partial_cmp(&self, other: &OptNumber) -> Option<Ordering>
fn partial_cmp(&self, other: &OptNumber) -> Option<Ordering>
1.0.0 · sourcefn le(&self, other: &Rhs) -> bool
fn le(&self, other: &Rhs) -> bool
self and other) and is used by the <=
operator. Read more