Struct MessageBuilder

pub struct MessageBuilder<'a> { /* private fields */ }

A builder of a STUN Message to a sequence of bytes.

Implementations

impl<'a> MessageBuilder<'a>

pub fn into_owned<'b>(self) -> MessageBuilder<'b>

Consume this builder and produce a new owned version.

pub fn transaction_id(&self) -> TransactionId

Retrieves the 96-bit transaction ID of the Message

Examples

let mtype = MessageType::from_class_method(MessageClass::Request, BINDING);
let transaction_id = TransactionId::generate();
let message = Message::builder(mtype, transaction_id).build();
let message = Message::from_bytes(&message).unwrap();
assert_eq!(message.transaction_id(), transaction_id);

pub fn has_class(&self, cls: MessageClass) -> bool

Whether this MessageBuilder is for a particular MessageClass

pub fn build(&self) -> Vec<u8>

Serialize a MessageBuilder to network bytes

Examples

let mut message = Message::builder(MessageType::from_class_method(MessageClass::Request, BINDING), 1000.into());
let attr = RawAttribute::new(1.into(), &[3]);
assert!(message.add_raw_attribute(attr).is_ok());
assert_eq!(message.build(), vec![0, 1, 0, 8, 33, 18, 164, 66, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 3, 232, 0, 1, 0, 1, 3, 0, 0, 0]);

pub fn write_into(&self, dest: &mut [u8]) -> Result<usize, StunWriteError>

Write this builder into the provided destination buffer returning the length in bytes that has been written, or an error.

pub fn byte_len(&self) -> usize

The length in bytes this MessageBuilder would require to successfully construct a message.

pub fn add_message_integrity( &mut self, credentials: &MessageIntegrityCredentials, algorithm: IntegrityAlgorithm, ) -> Result<(), StunWriteError>

Adds MESSAGE_INTEGRITY attribute to a Message using the provided credentials

Errors

• If a MessageIntegrity attribute is already present
• If a MessageIntegritySha256 attribute is already present
• If a Fingerprint attribute is already present

Examples

    MessageIntegrityCredentials, ShortTermCredentials, IntegrityAlgorithm, StunWriteError};
    MessageIntegritySha256};
let mut message = Message::builder_request(BINDING);
let credentials = ShortTermCredentials::new("pass".to_owned()).into();
assert!(message.add_message_integrity(&credentials, IntegrityAlgorithm::Sha1).is_ok());

// duplicate MessageIntegrity is an error
assert!(matches!(
    message.add_message_integrity(&credentials, IntegrityAlgorithm::Sha1),
    Err(StunWriteError::AttributeExists(MessageIntegrity::TYPE)),
));

// both MessageIntegrity, and MessageIntegritySha256 are allowed, however Sha256 must be
// after Sha1
assert!(message.add_message_integrity(&credentials, IntegrityAlgorithm::Sha256).is_ok());

let data = message.build();
let message = Message::from_bytes(&data).unwrap();
assert!(message.validate_integrity(&credentials).is_ok());

pub fn add_fingerprint(&mut self) -> Result<(), StunWriteError>

Adds Fingerprint attribute to a Message

Errors

• If a Fingerprint attribute is already present

Examples

let mut message = Message::builder_request(BINDING);
assert!(message.add_fingerprint().is_ok());

// duplicate FINGERPRINT is an error
assert!(message.add_fingerprint().is_err());

pub fn add_attribute( &mut self, attr: &'a dyn AttributeWrite, ) -> Result<(), StunWriteError>

Add a Attribute to this Message. Only one AttributeType can be added for each Attribute. Attempting to add multiple Atributes of the same AttributeType` will fail.

Errors

• If the attribute already exists within the message
• If attempting to add attributes when MessageIntegrity, MessageIntegritySha256 or Fingerprint atributes already exist.

Panics

• if a MessageIntegrity or MessageIntegritySha256 attribute is attempted to be added. Use Message::add_message_integrity instead.
• if a Fingerprint attribute is attempted to be added. Use Message::add_fingerprint instead.

Examples

Add an Attribute

let mut message = Message::builder_request(BINDING);
let attr = RawAttribute::new(1.into(), &[3]);
assert!(message.add_raw_attribute(attr.clone()).is_ok());
assert!(message.add_raw_attribute(attr).is_err());

pub fn add_raw_attribute( &mut self, attr: RawAttribute<'a>, ) -> Result<(), StunWriteError>

Add RawAttribute to this Message. Only one AttributeType can be added for each Attribute. Attempting to add multiple Atributes of the same AttributeType` will fail.

Errors

• If the attribute already exists within the message
• If attempting to add attributes when MessageIntegrity, MessageIntegritySha256 or Fingerprint atributes already exist.

Panics

• if a MessageIntegrity or MessageIntegritySha256 attribute is attempted to be added. Use Message::add_message_integrity instead.
• if a Fingerprint attribute is attempted to be added. Use Message::add_fingerprint instead.

pub fn has_attribute(&self, atype: AttributeType) -> bool

Return whether this MessageBuilder contains a particular attribute.

pub fn has_any_attribute( &self, atypes: &[AttributeType], ) -> Option<AttributeType>

Return whether this MessageBuilder contains any of the provided attributes and returns the attribute found.

Trait Implementations

impl<'a> Clone for MessageBuilder<'a>

fn clone(&self) -> MessageBuilder<'a>

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<'a> Debug for MessageBuilder<'a>

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

Formats the value using the given formatter.