Struct CoapUri

pub struct CoapUri { /* private fields */ }

Representation of a URI for CoAP requests, responses or proxy URIs.

See https://datatracker.ietf.org/doc/html/rfc7252#section-6 for a description of how a URI should look like.

Examples

The easiest way to instantiate a request or location CoAP URI is by parsing a string (either using the FromStr implementation or using CoapUri::try_from_str):

use libcoap_rs::error::UriParsingError;
use libcoap_rs::types::{CoapUri, CoapUriScheme};

let uri: CoapUri = "coap://example.com:4711/foo/bar?answer=42".parse()?;

assert_eq!(uri.scheme(), Some(CoapUriScheme::Coap));
assert_eq!(uri.host(), Some("example.com".as_bytes()));
assert_eq!(uri.port(), Some(4711));
assert_eq!(uri.path(), Some("foo/bar".as_bytes()));
assert_eq!(uri.query(), Some("answer=42".as_bytes()));
assert!(!uri.is_proxy());

Alternatively, a CoapUri may be constructed from its parts using CoapUri::new or CoapUri::new_relative or from a Url (requires the url feature), refer to the method level documentation for more information.

If you want to create a proxy URI, refer to the method-level documentation CoapUri::new_proxy, CoapUri::try_from_str_proxy or CoapUri::try_from_url_proxy.

Note on URI Length Limits

Due to the specified limits of CoAP option lengths, the URI path components, query components, and hostnames for a URI must not exceed 255 bytes each, i.e. a full path with more than 255 bytes is fine, but each individual path segment must be smaller than 255 bytes.

For proxy URIs, there is a length limit of 255 bytes for the scheme. As we use the Uri-* options for encoding proxy URIs instead of the Proxy-Uri option (as specified in RFC 7252, section 5.10.2), the above limits regarding path and query components also apply here.

Implementations

impl CoapUri

pub fn new( scheme: CoapUriScheme, host: &[u8], port: u16, path: Option<&[u8]>, query: Option<&[u8]>, ) -> Result<CoapUri, UriParsingError>

Creates a new CoapUri for use as a request or location URI from its constituent parts.

Errors

May fail if the provided fields do not represent a valid relative URI or if the arguments exceed maximum lengths (see the struct level documentation).

Examples

use libcoap_rs::error::UriParsingError;
use libcoap_rs::types::{CoapUri, CoapUriScheme};

let uri: CoapUri = CoapUri::new(
    CoapUriScheme::Coap,
    "example.com".as_bytes(),
    4711,
    Some("/foo/bar".as_bytes()),
    Some("?answer=42".as_bytes())
)?;

assert_eq!(uri.scheme(), Some(CoapUriScheme::Coap));
assert_eq!(uri.host(), Some("example.com".as_bytes()));
assert_eq!(uri.port(), Some(4711));
assert_eq!(uri.path(), Some("foo/bar".as_bytes()));
assert_eq!(uri.query(), Some("answer=42".as_bytes()));
assert!(!uri.is_proxy());

pub fn new_proxy( scheme: CoapUriScheme, host: &[u8], port: u16, path: Option<&[u8]>, query: Option<&[u8]>, ) -> Result<CoapUri, UriParsingError>

Creates a new CoapUri for use as a proxy URI from its constituent parts.

Errors

May fail if the provided fields do not represent a valid relative URI or if the arguments exceed maximum lengths (see the struct level documentation).

Examples

use libcoap_rs::error::UriParsingError;
use libcoap_rs::types::{CoapUri, CoapUriScheme};

let uri: CoapUri = CoapUri::new_proxy(
    CoapUriScheme::Coap,
    "example.com".as_bytes(),
    4711,
    Some("/foo/bar".as_bytes()),
    Some("?answer=42".as_bytes())
)?;

assert_eq!(uri.scheme(), Some(CoapUriScheme::Coap));
assert_eq!(uri.host(), Some("example.com".as_bytes()));
assert_eq!(uri.port(), Some(4711));
assert_eq!(uri.path(), Some("foo/bar".as_bytes()));
assert_eq!(uri.query(), Some("answer=42".as_bytes()));
assert!(uri.is_proxy());

pub fn new_relative( path: Option<&[u8]>, query: Option<&[u8]>, ) -> Result<CoapUri, UriParsingError>

Attempts to convert the provided path and query into a relative CoapUri suitable as a request/location URI.

Errors

May fail if the provided path and query do not represent a valid relative URI or if the arguments exceed maximum lengths (see the struct level documentation).

Examples

use libcoap_rs::error::UriParsingError;
use libcoap_rs::types::{CoapUri, CoapUriScheme};

let uri: CoapUri = CoapUri::new_relative(
    Some("/foo/bar".as_bytes()),
    Some("?answer=42".as_bytes())
)?;

assert_eq!(uri.scheme(), None);
assert_eq!(uri.host(), None);
assert_eq!(uri.port(), Some(5683));
assert_eq!(uri.path(), Some("foo/bar".as_bytes()));
assert_eq!(uri.query(), Some("answer=42".as_bytes()));
assert!(!uri.is_proxy());

pub fn try_from_str(uri_str: &str) -> Result<CoapUri, UriParsingError>

Attempts to convert the provided uri_str into a CoapUri suitable as a request/location URI.

Errors

May fail if the provided uri_str is not a valid URI or if the URI components exceed maximum lengths (see the struct level documentation).

Examples

use libcoap_rs::error::UriParsingError;
use libcoap_rs::types::{CoapUri, CoapUriScheme};

let uri: CoapUri = CoapUri::try_from_str("coap://example.com:4711/foo/bar?answer=42")?;

assert_eq!(uri.scheme(), Some(CoapUriScheme::Coap));
assert_eq!(uri.host(), Some("example.com".as_bytes()));
assert_eq!(uri.port(), Some(4711));
assert_eq!(uri.path(), Some("foo/bar".as_bytes()));
assert_eq!(uri.query(), Some("answer=42".as_bytes()));
assert!(!uri.is_proxy());

pub fn try_from_str_proxy(uri_str: &str) -> Result<CoapUri, UriParsingError>

Attempts to convert the provided uri_str into a CoapUri suitable as a proxy URI.

Errors

May fail if the provided uri_str is not a valid proxy URI or if the URI components exceed maximum lengths (see the struct level documentation).

Examples

use libcoap_rs::error::UriParsingError;
use libcoap_rs::types::{CoapUri, CoapUriScheme};

let uri: CoapUri = CoapUri::try_from_str_proxy("coap://example.com:4711/foo/bar?answer=42")?;

assert_eq!(uri.scheme(), Some(CoapUriScheme::Coap));
assert_eq!(uri.host(), Some("example.com".as_bytes()));
assert_eq!(uri.port(), Some(4711));
assert_eq!(uri.path(), Some("foo/bar".as_bytes()));
assert_eq!(uri.query(), Some("answer=42".as_bytes()));
assert!(uri.is_proxy());

pub fn try_from_url(url: &Url) -> Result<CoapUri, UriParsingError>

Attempts to convert a Url into a CoapUri.

Errors

May fail if the provided Url is not a valid URI supported by libcoap or if the URI components exceed maximum lengths (see the struct level documentation).

pub fn try_from_url_proxy(url: &Url) -> Result<CoapUri, UriParsingError>

Attempts to convert a Url into a proxy CoapUri.

Errors

May fail if the provided Url is not a valid proxy URI supported by libcoap or if the URI components exceed maximum lengths (see the struct level documentation).

pub fn scheme(&self) -> Option<CoapUriScheme>

Returns the scheme part of this URI.

pub fn host(&self) -> Option<&[u8]>

Returns the host part of this URI.

pub fn port(&self) -> Option<UriPort>

Returns the port of this URI (if provided).

pub fn path(&self) -> Option<&[u8]>

Returns the URI path part of this URI.

pub fn query(&self) -> Option<&[u8]>

Returns the host part of this URI.

pub fn is_proxy(&self) -> bool

Returns whether this URI is a proxy URI.

pub fn into_options(self) -> Vec<CoapOption>

Converts the given URI into a Vec of CoapOptions that can be added to a crate::message::CoapMessage.

pub fn as_raw_uri(&self) -> &coap_uri_t

Provides a reference to the raw [coap_uri_t] struct represented by this CoapUri.

Note that while obtaining this struct and reading the fields is safe (which is why this method is safe), modifying the referenced URI parts by (unsafely) dereferencing and mutating the const pointers inside is not.

pub unsafe fn from_raw_uri( raw_uri: *const coap_uri_t, is_proxy: bool, ) -> CoapUri

Converts the given raw_uri to a new CoapUri instance.

This method will create a copy of the provided URI, i.e. raw_uri will remain valid and not be owned by the created CoapUri instance.

Safety

The provided raw_uri must point to a valid instance of [coap_uri_t]. In particular, the provided pointers for the URI components must also be valid.

Panics

Panics if the provided raw_uri is null or the provided URI contains a null byte.

Trait Implementations

impl Clone for CoapUri

fn clone(&self) -> Self

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for CoapUri

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Display for CoapUri

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl FromStr for CoapUri

type Err = UriParsingError

The associated error which can be returned from parsing.

fn from_str(s: &str) -> Result<Self, Self::Err>

Parses a string s to return a value of this type.

impl PartialEq for CoapUri

fn eq(&self, other: &Self) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl TryFrom<&Url> for CoapUri

type Error = UriParsingError

The type returned in the event of a conversion error.

fn try_from(value: &Url) -> Result<Self, Self::Error>

Performs the conversion.

impl Eq for CoapUri