stun_types

Module attribute

Source
Expand description

STUN Attributes

Provides implementations for generating, parsing and manipulating STUN attributes as specified in one of RFC8489, RFC5389, or RFC3489.

§Examples

§Parse and write an already defined Attribute

use stun_types::attribute::{RawAttribute, Software};
let software_name = "stun-types";
let software = Software::new(software_name).unwrap();
assert_eq!(software.software(), software_name);

let attribute_data = [
    0x80, 0x22, 0x00, 0x0a, // Attribute type (0x8022: Software) and length (0x000a)
    0x73, 0x74, 0x75, 0x6E, // s t u n
    0x2D, 0x74, 0x79, 0x70, // - t y p
    0x65, 0x73, 0x00, 0x00  // e s
];

let raw = RawAttribute::from(&software);
assert_eq!(raw.to_bytes(), attribute_data);

// Can also parse data into a typed attribute as needed
let software = Software::from_raw(raw).unwrap();
assert_eq!(software.software(), software_name);

§Defining your own Attribute

use byteorder::{BigEndian, ByteOrder};
use stun_types::attribute::{AttributeType, RawAttribute};
use stun_types::message::StunParseError;
#[derive(Debug)]
struct MyAttribute {
   value: u32,
}
impl AttributeStaticType for MyAttribute {
   const TYPE: AttributeType = AttributeType::new(0x8851);
}
impl Attribute for MyAttribute {
   fn get_type(&self) -> AttributeType {
       Self::TYPE
   }

   fn length(&self) -> u16 {
       4
   }
}
impl AttributeWrite for MyAttribute {
    fn to_raw(&self) -> RawAttribute {
        let mut ret = [0; 4];
        BigEndian::write_u32(&mut ret, self.value);
        RawAttribute::new(MyAttribute::TYPE, &ret).into_owned()
    }
    fn write_into_unchecked(&self, dest: &mut [u8]) {
        self.write_header_unchecked(dest);
        BigEndian::write_u32(&mut dest[4..], self.value);
    }
}
impl AttributeFromRaw<'_> for MyAttribute {
    fn from_raw_ref(raw: &RawAttribute) -> Result<Self, StunParseError>
    where
        Self: Sized,
    {
        raw.check_type_and_len(Self::TYPE, 4..=4)?;
        let value = BigEndian::read_u32(&raw.value);
        Ok(Self {
            value,
        })
    }
}

// Optional: if you want this attribute to be displayed nicely when the corresponding
// `RawAttribute` (based on `AttributeType`) is formatted using `RawAttribute`'s `Display`
// implementation.
impl std::fmt::Display for MyAttribute {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        write!(f, "MyAttribute: {}", self.value)
    }
}
stun_types::attribute_display!(MyAttribute);
MyAttribute::TYPE.add_name("MY-ATTRIBUTE");

let my_attr = MyAttribute { value: 0x4729 };
let raw = RawAttribute::from(&my_attr);

let attribute_data = [
    0x88, 0x51, 0x00, 0x04,
    0x00, 0x00, 0x47, 0x29,
];
assert_eq!(raw.to_bytes(), attribute_data);

let my_attr = MyAttribute::from_raw(raw).unwrap();
assert_eq!(my_attr.value, 0x4729);

Structs§

AlternateDomain
The AlternateDomain Attribute
AlternateServer
The AlternateServer Attribute
AttributeHeader
Structure for holding the header of a STUN attribute. Contains the type and the length
AttributeType
The type of an Attribute in a STUN Message
ErrorCode
The ErrorCode Attribute
Fingerprint
The Fingerprint Attribute
IceControlled
The IceControlled Attribute
IceControlling
The IceControlling Attribute
MappedSocketAddr
Helper struct for SocketAddrs that are stored as an attribute.
MessageIntegrity
The MessageIntegrity Attribute
MessageIntegritySha256
The MessageIntegritySha256 Attribute
Nonce
The Nonce Attribute
PasswordAlgorithm
The PasswordAlgorithm Attribute
PasswordAlgorithms
The PasswordAlgorithms Attribute
Priority
The Priority Attribute
RawAttribute
The header and raw bytes of an unparsed Attribute
Realm
The Realm Attribute
Software
The Software Attribute
UnknownAttributes
The UnknownAttributes Attribute
UseCandidate
The UseCandidate Attribute
Userhash
The Userhash Attribute
Username
The username Attribute
XorMappedAddress
The XorMappedAddress Attribute
XorSocketAddr
Helper struct for SocketAddr that are stored as an Attribute after an XOR operation with the TransactionId of a Message.

Enums§

AddressFamily
The address family of the socket
PasswordAlgorithmValue
The hashing algorithm for the password

Traits§

Attribute
A STUN attribute for use in Messages
AttributeExt
Automatically implemented trait providing some helper functions.
AttributeFromRaw
A trait for converting to a concrete Attribute from a RawAttribute
AttributeStaticType
A static type for an Attribute
AttributeWrite
Trait required when implementing writing an Attribute to a sequence of bytes
AttributeWriteExt
Automatically implemented trait providing helper functionality for writing an Attribute to a sequence of bytes.

Functions§

add_display_impl
Adds an externally provided Display implementation for a particular AttributeType. Any previous implementation is overidden.

Type Aliases§

AttributeDisplay
A closure definition for an externally provided Display implementation for a RawAttribute.