KcoapException

The root of the exceptions kcoap's facades fail with at runtime: what went wrong with the peer, the network, message security, the protocol or the endpoint's lifecycle, as opposed to a mistake of the caller, which is an IllegalArgumentException or IllegalStateException. Each protocol has its own subtype, which says what failed and carries what that protocol needs to answer:

ModuleSubtype
kcoap-coapCoapException, with its Reason (RFC 7252, RFC 8323)
kcoap-oscoreOscoreException, with its OscoreError (RFC 8613 §8.2, §7.4)
kcoap-edhocEdhocException, with its EdhocError (RFC 9528 §6), and EdhocPeerErrorException
kcoap-edhoc-oscoreEdhocTransferException, an EdhocException (RFC 9528 Appendix A.2)
kcoap-cborCborException (RFC 8949), also for COSE structures (RFC 9052)
kcoap-cryptoCertificateFormatException (RFC 5280 §4.1)

Catching KcoapException handles every such failure of any kcoap call at once; catching the subtype handles those of one protocol. The signals of the SPIs between the layers stay outside this root, since each layer translates them at its boundary: MessageSecurityException, CoapFormatException, SessionEndedException, AeadAuthenticationException, UnsupportedAlgorithmException and CertificateValidationException.

Swift and Objective-C. The public suspend entry points (the CoapClient requests, discover and ping, the EDHOC steps, SecurityContext.derive and the others) list this class and CancellationException in @Throws, so on Apple platforms such a failure reaches Swift as an NSError that a do/catch handles, with the Kotlin exception in its userInfo under the key "KotlinException". An exception of a type the function does not list, such as the IllegalArgumentException of a mistake of the caller, still ends the process there, as a failed precondition does in Swift. CoapUri.parse, whose input is often typed in, lists IllegalArgumentException so that Swift can catch a malformed URI.

The class is open with a protected constructor, which takes the cause or null, for kcoap's protocol modules. Nothing stops another module from extending it, but applications should not, so that catching KcoapException means a failure of kcoap.

Properties

Link copied to clipboard
expect open val cause: Throwable?
Link copied to clipboard
expect open val message: String?