Crate libcoap_rs

A safe wrapper around the libcoap C library.

This wrapper allows for safe and idiomatic usage of the libcoap C library in Rust.

Feature support

libcoap-rs currently supports the following subset of the libcoap feature set:

• Basic CoAP client
• Basic CoAP server
• Transports:
  • UDP
  • DTLS
    • DTLS using PSK
    • DTLS using PKI/RPK
  • TCP
  • TLS
  • OSCORE
  • WebSockets
• Blockwise Transfer
  • Receiving large messages
    • Note: Handled in libcoap by setting COAP_BLOCK_USE_LIBCOAP|COAP_BLOCK_SINGLE_BODY. Manually constructing and managing blockwise transfers is currently not in scope for this library.
  • sending client-side large messages
  • sending server-side large messages
• Resource observation
  • Observing resources as a client
  • Notifying observers as a server

Building

libcoap-rs is based on libcoap-sys, which provide many different ways to obtain and link against a system-provided or vendored version of the libcoap C library.

Refer to its documentation for detailed instructions on how to build libcoap-sys as well as this library.

Most of these instructions can be applied to libcoap-rs directly, although libcoap-rs does abstract away some of the features.

For your convenience, libcoap-rs “re-exports” some features that do not have any influence on the safe wrapper, but may have to be set in libcoap-sys to enable building (e.g., the dtls-<LIBRARY NAME>-sys features). This way, you don’t need to add libcoap-sys as a dependency yourself, and may just enable the feature in this crate instead.

Examples

Client

This example runs a simple CoAP client which makes a request to coap://[::1]:5683/hello_world and checks whether the result has the code 2.00 (Content) and the payload Hello World!.

use std::{
    net::{SocketAddr, UdpSocket},
    time::Duration,
};

use libcoap_rs::{
    CoapContext,
    message::{CoapMessageCommon, CoapResponse, CoapRequest},
    protocol::{CoapRequestCode, CoapResponseCode, CoapMessageCode, CoapMessageType},
    CoapRequestHandler, CoapResource,
    session::{CoapSessionCommon, CoapClientSession},
    types::{CoapUriScheme, CoapUri}
};

let server_address : SocketAddr = "[::1]:5683".parse().unwrap();

// Create a new context.
let mut context = CoapContext::new().expect("Failed to create CoAP context");

// Connect to the server at the specified address over UDP (no encryption)
let session = CoapClientSession::connect_udp(&mut context, server_address)
                .expect("Failed to create client-side session");

// Create a new CoAP URI to request from.
let uri = "coap://[::1]:5683/hello_world".parse().unwrap();

// Create a new request of type get with the specified URI.
let mut request = CoapRequest::new(CoapMessageType::Con, CoapRequestCode::Get, uri).unwrap();

// Send the request and wait for a response.
let req_handle = session.send_request(request).expect("Unable to send request");
loop {
    context.do_io(Some(Duration::from_secs(10))).expect("error during IO");
    // Poll for responses to a request using the request handle.
    for response in session.poll_handle(&req_handle) {
        assert_eq!(response.code(), CoapMessageCode::Response(CoapResponseCode::Content));
        assert_eq!(response.data().unwrap().as_ref(), "Hello World!".as_bytes());
        return;
    }
}

Server

This example runs a simple CoAP server that provides a resource under the URI path /hello_world with Hello World! as the response payload.

use std::{
    net::{SocketAddr, UdpSocket},
    time::Duration,
};

use libcoap_rs::{
    CoapContext,
    message::{CoapMessageCommon, CoapResponse, CoapRequest},
    protocol::{CoapRequestCode, CoapResponseCode},
    CoapRequestHandler, CoapResource,
    session::{CoapSessionCommon, CoapServerSession},
};

// a new CoAP context and bind to the generated SocketAddr.
let mut context = CoapContext::new().expect("Failed to create CoAP context");
context.add_endpoint_udp("[::1]:5683".parse().unwrap()).expect("Unable to add/bind to endpoint");

// Create a new resource that is available at the URI path `hello_world`
// The second argument can be used to provide any kind of user-specific data, which will
// then be passed to the handler function.
let resource = CoapResource::new("hello_world", (), false);
// Set a method handler for the GET method.
resource.set_method_handler(
    CoapRequestCode::Get,
    Some(CoapRequestHandler::new(
        // The handler can be a lambda or some other kind of function.
        // Using methods is also possible by setting the resource's user data to an instance
        // of the struct, as the first argument will then be a mutable reference to the
        // user data. Methods will then use this user data as the `&mut self` reference.
        //
        // The provided CoapResponse is already filled with the correct token to be
        // interpreted as a response to the correct request by the client.
        |completed: &mut (), session: &mut CoapServerSession, request: &CoapRequest, mut response: CoapResponse| {
            // Set content of the response message to "Hello World!"
            let data = Vec::<u8>::from("Hello World!".as_bytes());
            response.set_data(Some(data));
            // Set the response code to 2.00 "Content"
            response.set_code(CoapResponseCode::Content);
            // Send the response message.
            session.send(response).expect("Unable to send response");
        },
    )),
);

// Add the resource to the context.
context.add_resource(resource);
loop {
    // process IO in a loop...
    if let Err(e) = context.do_io(Some(Duration::from_secs(1))) {
        break;
    }
    // ...until we want to shut down.
}
// Properly shut down, completing outstanding IO requests and properly closing sessions.
context.shutdown(Some(Duration::from_secs(0))).unwrap();

Modules

crypto

Cryptography interfaces and types.

error

Error types

message

Types related to message handling, parsing and creation.

prng

Module containing methods for accessing or configuring the libcoap PRNG.

protocol

Various types that are specified and defined in the CoAP standard and its extensions.

session

transport

types

Types required for conversion between libcoap C library abstractions and Rust types.

Macros

resource_handler

Create a CoapRequestHandler using the provided function.

Structs

CoapContext

A CoAP Context — container for general state and configuration information relating to CoAP

CoapRequestHandler

A handler for CoAP requests on a resource.

CoapResource

Representation of a CoapResource that can be requested from a server.

Traits

CoapEventHandler

Trait for CoAP event handlers.