ObservableResource
A resource clients can observe (RFC 7641). A GET or FETCH with Observe 0 that the handler answers with 2.xx adds the client to the observers; call notifyObservers whenever the state changes, and every observer gets a notification produced by calling the handler again with its registration request.
class Clock : ObservableResource("time") {
override suspend fun handleGet(context: RequestContext) =
CoapResponse.content(now()).withOptions { maxAge(1) }
}
// every second: clock.notifyObservers()The server takes care of the rest of RFC 7641 §4: sequence numbers (§4.4), at most NSTART outstanding notifications per client, sending only the latest state when changes outpace the network and superseding an unacknowledged notification (§4.5.2), a Confirmable notification at least every CoapServerConfig.confirmableNotificationInterval (§4.5), removing observers on RST, timeout or a non-2.xx notification (§3.2, §4.5), and 4.04 notifications when the resource is removed. Over a reliable transport (RFC 8323 §7) the notifications go on the registration's connection, in order, and a closed connection removes its observers.
Properties
Who may use this resource and, unless a child has a policy of its own, everything below it (ADR 0008). Null inherits the parent's, and the root's falls back to CoapServerConfig.defaultAccess; see AccessPolicy for when the server asks it.
Link attributes for /.well-known/core.
The child resources, in the order they were added.
Whether /.well-known/core lists this resource (RFC 6690 §4: which links to include is up to the server).
Whether GET or FETCH with Observe registers observers (RFC 7641 §4.1); see ObservableResource.
Whether notifications go Confirmable or Non-confirmable (RFC 7641 §4.5): a hint for datagram transports only, since a reliable transport has no message types and ignores it (RFC 8323 §7.2). Non-confirmable ones are cheaper for frequent changes; the server still sends a Confirmable one periodically, and to a client that neither message nor channel security authenticated at least every ninth notification, whose ACK shows the client still wants them (RFC 7641 §7). Only CoapMessageType.NON asks for Non-confirmable notifications; any other value asks for Confirmable ones.
How many clients observe this resource now.
The parent resource, or null for a root or a detached resource.
Critical options this resource processes itself, beyond those the server implements (RFC 7252 §5.4.1). A request with any other unrecognized critical option gets 4.02 Bad Option before a handler runs. For example, a resource that honours conditional requests adds If-Match and If-None-Match (see RequestContext.preconditionsHold).
Functions
Adds child under this resource and returns it.
The child called name, or null.
Dispatches to the handler for the request method (template method). Override it to handle methods generically, for example to proxy.
DELETE (RFC 7252 §5.8.4).
FETCH (RFC 8132 §2); observable like GET (RFC 8132 §2.4).
GET (RFC 7252 §5.8.1); also produces every Observe notification of an observable resource.
iPATCH (RFC 8132 §3).
PATCH (RFC 8132 §3).
POST (RFC 7252 §5.8.2).
PUT (RFC 7252 §5.8.3).
Tells the observers that the state changed. Returns at once; notifications are sent in the background.
Removes and returns the child called name. Its observers, and those of its children, get a 4.04 notification and are removed (RFC 7641 §3.2).