QBlockClientConfig

class QBlockClientConfig(val mode: QBlockMode = QBlockMode.OFF, val probePath: String = "/.well-known/core", val capabilityLifetime: Duration = 1.hours, val onReliableTransports: Boolean = false, val withMessageSecurity: Boolean = false, val missingBlockMBit: Boolean = false)(source)

How a CoapClient uses Q-Block (RFC 9177): bodies sent and received in bursts of MAX_PAYLOADS blocks (dev.kcoap.coap.stack.TransmissionParameters.maxPayloads) that recover lost blocks without a round trip per block. Off by default.

A body follows the message type of its request (RFC 9177 §7): a Confirmable request (the default) sends and receives Confirmable blocks in lock-step under NSTART (§7.1, Appendix A); a Non-confirmable one (CoapRequest.Builder.nonConfirmable()) gets the bursts of §7.2. A request carrying No-Response, Observe, or a Block or Q-Block option of the application's own always uses RFC 7959. Observations (CoapClient.observe) use Q-Block like requests (§4.5): every notification body comes in Q-Block2 and is emitted once it is whole, a FETCH body that needs blocks is uploaded in Q-Block1, and the bodies of a Non-confirmable observation are bursts.

Constructors

Link copied to clipboard
constructor(mode: QBlockMode = QBlockMode.OFF, probePath: String = "/.well-known/core", capabilityLifetime: Duration = 1.hours, onReliableTransports: Boolean = false, withMessageSecurity: Boolean = false, missingBlockMBit: Boolean = false)

Properties

Link copied to clipboard

how long a probe's answer is remembered per server, by the endpoint for all its clients. A probe that got no answer is repeated after at most a minute; a server's DTLS session ending or its connection closing forgets the answer at once, and so do a 4.02 or a Reset that answers a Q-Block body before anything else, a Reset to a Q-Block1 block, and a Non-confirmable body that got no response at all.

Link copied to clipboard

Whether the client uses Q-Block at all.

Link copied to clipboard

whether a request for missing blocks asks for the missing tail of a MAX_PAYLOADS set with one Q-Block2 option with M set (RFC 9177 §4.4), instead of one option per block.

Link copied to clipboard

whether Q-Block is used, and how the client finds out that a server supports it.

Link copied to clipboard

whether Q-Block is used over TCP and WebSockets (RFC 8323), where it only sends blocks back to back (RFC 9177 Appendix B); off by default, since BERT does the same with fewer messages.

Link copied to clipboard

the resource the QBlockMode.PROBE probe asks for, with Q-Block2 0/0/16: block 0 of 16 bytes and nothing more, the probe libcoap sends.

Link copied to clipboard

whether Q-Block is used when the client protects its requests (CoapClientConfig.security); off by default, so protected bodies use Inner Block1 and Block2 (RFC 7959; RFC 8613 §4.1.3.4.1). Several responses to one request fall outside OSCORE's single-response replay model (RFC 8613 §7.4): turned on, Q-Block1 and Q-Block2 go inside OSCORE (RFC 9177 §4, Table 2), and the security layer must accept several responses to a request carrying them, as kcoap-oscore's OscoreClient does with a replay window per request. It reports every unprotected error as ResponseVerification.Unverified (RFC 8613 §8.2), as OscoreClient does, and the client acts on none of them (ADR 0008): an unverified 4.08, 4.13, 4.02 or Echo challenge steers nothing of the body (RFC 9177 §11), which ends with CoapException.Reason.UNVERIFIED_RESPONSE, or which an established observation ignores. The probe and the capability it finds are kept apart from those of unprotected requests; a probe the security layer refuses to send, before a protection is installed, finds nothing and keeps nothing. The server has to opt in too (QBlockServerConfig.withMessageSecurity), or it answers 4.02, or a Reset to a Non-confirmable request, and the request is sent again with RFC 7959. Observations take it too: every block of a notification body is a notification with a Partial IV of its own (RFC 9177 §4.5, RFC 8613 §4.1.3.5.2), so the security layer must take the blocks of the freshest body in any order while it still refuses replays (§7.4.1) and older bodies, as OscoreClient does with a replay window per registration; the stack leaves the ordering of protected notifications to it.

Functions

Link copied to clipboard
open override fun toString(): String