Module async_coap::send_desc

Send Descriptors

Send Descriptors are types that implement SendDesc that can be passed to the send* methods of LocalEndpoint and RemoteEndpoint. They define almost every aspect of how a message transaction is handled.

Typical usage of this crate does not require writing implementing SendDesc by hand, although you could certainly do so if needed. Instead, SyncDesc instances are easily constructed using combinators.

Example

Here we create a SendDesc instance that just sends a GET request and waits for a response:

let mut remote_endpoint = local_endpoint
    .remote_endpoint_from_uri(uri!("coap://coap.me:5683/test"))
    .expect("Remote endpoint lookup failed");

let future = remote_endpoint.send(CoapRequest::get());

assert_eq!(future.await, Ok(()));

That SendDesc was perhaps a little too simple: it doesn't even interpret the results, returning Ok(()) for any message responding with a 2.05 Content message!

By using the combinator .emit_successful_response(), we can have our SendDesc return an owned copy of the message it received (OwnedImmutableMessage):

let send_desc = CoapRequest::get().emit_successful_response();

let future = remote_endpoint.send(send_desc);

let message = future.await.expect("Request failed");

println!("Got reply: {:?}", message);

What if we wanted the response in JSON? What if it was really large and we knew we would need to do a block2 transfer? We can do that easily:

let send_desc = CoapRequest::get()
    .accept(ContentFormat::APPLICATION_JSON)
    .block2(None)
    .emit_successful_collected_response();

// Here we are specifying that we want to send the request to a specific
// path on the remote endpoint, `/large` in this case.
let future = remote_endpoint.send_to(rel_ref!("/large"), send_desc);

let message = future.await.expect("Request failed");

println!("Got reply: {:?}", message);

But if this is a large amount of data, we won't get any indication about the transfer until it is done. What if we wanted to add some printouts about the status?

let send_desc = CoapRequest::get()
    .accept(ContentFormat::APPLICATION_JSON)
    .block2(None)
    .emit_successful_collected_response()
    .inspect(|context| {
        let addr = context.remote_address();
        let msg = context.message();

        // Print out each individual block message received.
        println!("Got {:?} from {}", msg, addr);
    });

let future = remote_endpoint.send_to(rel_ref!("/large"), send_desc);

let message = future.await.expect("Request failed");

println!("Got reply: {:?}", message);

There are many more combinators for doing all sorts of things, such as adding additional options and block2 message aggregation.

Structs

AddOption	Combinator for Send Descriptors created by SendDescExt::add_option.
CoapRequestMethod	Send descriptor created by CoapRequest::method used for sending CoAP requests with a programmatically defined method.
EmitAnyResponse	Combinator for Send Descriptors created by SendDescExt::emit_any_response.
EmitMsgCode	Combinator for Send Descriptors created by SendDescExt::emit_msg_code.
EmitSuccessfulResponse	Combinator for Send Descriptors created by SendDescExt::emit_successful_response.
Handler	Combinator for Send Descriptors created by SendDescExt::use_handler.
IncludeSocketAddr	Combinator for Send Descriptors created by SendDescExt::include_socket_addr.
Inspect	Combinator for Send Descriptors created by SendDescExt::inspect.
Multicast	Multicast send descriptor combinator created by the multicast() method on SendGet, SendPut, SendPost, SendDelete, and SendObserve.
Nonconfirmable	Nonconfirmable send descriptor combinator created by the nonconfirmable() method on SendGet, SendPut, SendPost, SendDelete, and SendObserve.
PayloadWriter	Combinator for Send Descriptors created by SendDescExt::payload_writer.
Ping	Send descriptor for sending a CoAP ping.
SendDelete	Send descriptor created by CoapRequest::delete used for sending CoAP DELETE requests.
SendGet	Send descriptor created by CoapRequest::get used for sending CoAP GET requests.
SendObserve	Send descriptor created by CoapRequest::observe used for sending CoAP GET requests that observe changing resources.
SendPost	Send descriptor created by CoapRequest::post used for sending CoAP POST requests.
SendPut	Send descriptor created by CoapRequest::put used for sending CoAP PUT requests.
UnicastBlock2	Unicast Block2 Tracking combinator, created by SendDescUnicast::block2.
UnicastBlock2Collect	Unicast Block2 Collecting combinator, created by UnicastBlock2::emit_successful_collected_response.
UriHostPath	Combinator for Send Descriptors created by SendDescExt::uri_host_path.

Enums

CoapRequest

Seed combinator used for creating send descriptors for CoAP requests.

Traits

SendDesc	Send Descriptor Trait
SendDescExt	Combinator extension trait for Send Descriptors.
SendDescMulticast	Marker trait for identifying that this SendDesc is for multicast requests. Also contains multicast-specific extensions.
SendDescUnicast	Marker trait for identifying that this SendDesc is for unicast requests. Also contains unicast-specific combinators, such as block2().