CoapEndpoint
A CoAP endpoint: the messaging layers and the exchange layer that matches responses to requests by peer and token. dev.kcoap.coap.client.CoapClient and dev.kcoap.coap.server.CoapServer are built on it and can share one endpoint, so a device can be client and server on the same port.
It runs CoAP over a DatagramTransport with the RFC 7252 messaging layer, and CoAP over reliable transports (RFC 8323) on connections: opened on demand through Connectors for coap+tcp, coaps+tcp, coap+ws and coaps+ws peers, reused per peer and released when idle, and accepted from ConnectionListeners. Every connection has a messaging layer of its own, so tokens are scoped to it, and its responses, notifications and failures stay with it (RFC 8323 §3.3, §7.4). One exchange layer serves all of them through an internal link per peer, chosen by the kind of the peer's Endpoint, so Block-wise, Observe, Q-Block and message security behave the same on every transport.
The endpoint runs its coroutines in scope and inherits its dispatcher. It starts receiving and accepting once a dev.kcoap.coap.server.CoapServer is attached or the first request or ping goes out, so a server's resources are in place before the first request arrives, whichever of a server and a dev.kcoap.coap.client.CoapClient sharing the endpoint is created first. On Android or iOS pass a scope such as lifecycleScope + Dispatchers.Default to keep the receive loop, timers and handlers off the main thread.
Lifecycle. An endpoint ends exactly once, in one terminal transition, whichever way it ends: close, cancelling scope, or a datagram transport whose receive fails. Then open exchanges fail, observations end with a failure for their collectors, connections are released (RFC 8323 §5.5), the transports are closed, and every later request, ping or observation fails at once with a CoapException like closeCause. awaitClosed waits for all of that, coroutines included.
Thread safety. All state is guarded by locks that are never held across a suspension, and effects such as sending and delivering run after the lock is released, so the endpoint is safe to use from any number of coroutines on any dispatcher.
val endpoint = CoapEndpoint(KtorUdpTransport.bind(port = 5683), scope)
val server = CoapServer(endpoint) { resource("hello") { get { CoapResponse.content("Hello") } } }
val client = CoapClient(endpoint)Constructors
An endpoint on transport, for coap peers; it has no connections.
An endpoint on any combination of transports: transport for coap peers, connectors to open connections to peers of the RFC 8323 schemes they serve, listeners to accept connections. close closes all of them. A request to a peer the endpoint has no transport for fails with CoapException.Reason.TRANSPORT_UNAVAILABLE: a coap peer without transport, or a peer of a scheme no connector serves, unless that peer already has a connection open, as one a listener accepted.
Properties
Why the endpoint closed, or null while it is open: CoapException.Reason.CLOSED after close or when its scope was cancelled; CoapException.Reason.TRANSPORT_FAILED, with the transport's exception as cause, when the datagram transport failed. Set once, in the terminal transition.
True once the endpoint is closed, however that happened; see closeCause.
The parameters messaging runs with.
Functions
Waits until the endpoint is closed, by any path, and every coroutine it ran has finished, request handlers included; returns closeCause. For graceful shutdown and tests. Called from one of the endpoint's own coroutines, such as a request handler, it never returns.
Closes the endpoint: the terminal transition, with CoapException.Reason.CLOSED. Open exchanges fail with it, observations end, connections are released (RFC 8323 §5.5), the endpoint's coroutines are cancelled and the transports closed. Returns once that is done; it does not wait for the cancelled coroutines, so a request handler may call it. Idempotent: after any terminal transition it only waits for that one to finish.
Sends a CoAP ping. To a datagram peer (RFC 7252 §4.3) an Empty Confirmable message, which a live peer answers with a Reset: true if it answered, false if it never did within MAX_TRANSMIT_WAIT. To a reliable peer (RFC 8323 §5.4) a Ping on its connection, opened if needed: true if the Pong came within ReliableTransportConfig.pingTimeout, false if not or if the connection failed.
How much the endpoint holds now: exchanges, running handlers, what the datagram messaging layer keeps and open connections (EndpointStats). Reading takes no lock, since every layer keeps its counts up to date as it changes them, so a metrics library may poll it as often as it likes, from any thread.