jingle_s5b: Document this module.
This commit is contained in:
parent
eeeae25cb1
commit
22b424f43a
1 changed files with 88 additions and 23 deletions
|
@ -4,8 +4,6 @@
|
||||||
// License, v. 2.0. If a copy of the MPL was not distributed with this
|
// License, v. 2.0. If a copy of the MPL was not distributed with this
|
||||||
// file, You can obtain one at http://mozilla.org/MPL/2.0/.
|
// file, You can obtain one at http://mozilla.org/MPL/2.0/.
|
||||||
|
|
||||||
#![allow(missing_docs)]
|
|
||||||
|
|
||||||
use try_from::TryFrom;
|
use try_from::TryFrom;
|
||||||
use std::net::IpAddr;
|
use std::net::IpAddr;
|
||||||
|
|
||||||
|
@ -16,33 +14,72 @@ use error::Error;
|
||||||
|
|
||||||
use ns;
|
use ns;
|
||||||
|
|
||||||
generate_attribute!(Type, "type", {
|
generate_attribute!(
|
||||||
|
/// The type of the connection being proposed by this candidate.
|
||||||
|
Type, "type", {
|
||||||
|
/// Direct connection using NAT assisting technologies like NAT-PMP or
|
||||||
|
/// UPnP-IGD.
|
||||||
Assisted => "assisted",
|
Assisted => "assisted",
|
||||||
|
|
||||||
|
/// Direct connection using the given interface.
|
||||||
Direct => "direct",
|
Direct => "direct",
|
||||||
|
|
||||||
|
/// SOCKS5 relay.
|
||||||
Proxy => "proxy",
|
Proxy => "proxy",
|
||||||
|
|
||||||
|
/// Tunnel protocol such as Teredo.
|
||||||
Tunnel => "tunnel",
|
Tunnel => "tunnel",
|
||||||
}, Default = Direct);
|
}, Default = Direct
|
||||||
|
);
|
||||||
|
|
||||||
generate_attribute!(Mode, "mode", {
|
generate_attribute!(
|
||||||
|
/// Which mode to use for the connection.
|
||||||
|
Mode, "mode", {
|
||||||
|
/// Use TCP, which is the default.
|
||||||
Tcp => "tcp",
|
Tcp => "tcp",
|
||||||
|
|
||||||
|
/// Use UDP.
|
||||||
Udp => "udp",
|
Udp => "udp",
|
||||||
}, Default = Tcp);
|
}, Default = Tcp
|
||||||
|
);
|
||||||
|
|
||||||
generate_id!(CandidateId);
|
generate_id!(
|
||||||
|
/// An identifier for a candidate.
|
||||||
|
CandidateId
|
||||||
|
);
|
||||||
|
|
||||||
generate_id!(StreamId);
|
generate_id!(
|
||||||
|
/// An identifier for a stream.
|
||||||
|
StreamId
|
||||||
|
);
|
||||||
|
|
||||||
generate_element!(Candidate, "candidate", JINGLE_S5B,
|
generate_element!(
|
||||||
|
/// A candidate for a connection.
|
||||||
|
Candidate, "candidate", JINGLE_S5B,
|
||||||
attributes: [
|
attributes: [
|
||||||
|
/// The identifier for this candidate.
|
||||||
cid: CandidateId = "cid" => required,
|
cid: CandidateId = "cid" => required,
|
||||||
|
|
||||||
|
/// The host to connect to.
|
||||||
host: IpAddr = "host" => required,
|
host: IpAddr = "host" => required,
|
||||||
|
|
||||||
|
/// The JID to request at the given end.
|
||||||
jid: Jid = "jid" => required,
|
jid: Jid = "jid" => required,
|
||||||
|
|
||||||
|
/// The port to connect to.
|
||||||
port: Option<u16> = "port" => optional,
|
port: Option<u16> = "port" => optional,
|
||||||
|
|
||||||
|
/// The priority of this candidate, computed using this formula:
|
||||||
|
/// priority = (2^16)*(type preference) + (local preference)
|
||||||
priority: u32 = "priority" => required,
|
priority: u32 = "priority" => required,
|
||||||
|
|
||||||
|
/// The type of the connection being proposed by this candidate.
|
||||||
type_: Type = "type" => default,
|
type_: Type = "type" => default,
|
||||||
]);
|
]
|
||||||
|
);
|
||||||
|
|
||||||
impl Candidate {
|
impl Candidate {
|
||||||
|
/// Creates a new candidate with the given parameters.
|
||||||
pub fn new(cid: CandidateId, host: IpAddr, jid: Jid, priority: u32) -> Candidate {
|
pub fn new(cid: CandidateId, host: IpAddr, jid: Jid, priority: u32) -> Candidate {
|
||||||
Candidate {
|
Candidate {
|
||||||
cid,
|
cid,
|
||||||
|
@ -54,36 +91,61 @@ impl Candidate {
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|
||||||
|
/// Sets the port of this candidate.
|
||||||
pub fn with_port(mut self, port: u16) -> Candidate {
|
pub fn with_port(mut self, port: u16) -> Candidate {
|
||||||
self.port = Some(port);
|
self.port = Some(port);
|
||||||
self
|
self
|
||||||
}
|
}
|
||||||
|
|
||||||
|
/// Sets the type of this candidate.
|
||||||
pub fn with_type(mut self, type_: Type) -> Candidate {
|
pub fn with_type(mut self, type_: Type) -> Candidate {
|
||||||
self.type_ = type_;
|
self.type_ = type_;
|
||||||
self
|
self
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|
||||||
|
/// The payload of a transport.
|
||||||
#[derive(Debug, Clone)]
|
#[derive(Debug, Clone)]
|
||||||
pub enum TransportPayload {
|
pub enum TransportPayload {
|
||||||
|
/// The responder informs the initiator that the bytestream pointed by this
|
||||||
|
/// candidate has been activated.
|
||||||
Activated(CandidateId),
|
Activated(CandidateId),
|
||||||
|
|
||||||
|
/// A list of suggested candidates.
|
||||||
Candidates(Vec<Candidate>),
|
Candidates(Vec<Candidate>),
|
||||||
|
|
||||||
|
/// Both parties failed to use a candidate, they should fallback to another
|
||||||
|
/// transport.
|
||||||
CandidateError,
|
CandidateError,
|
||||||
|
|
||||||
|
/// The candidate pointed here should be used by both parties.
|
||||||
CandidateUsed(CandidateId),
|
CandidateUsed(CandidateId),
|
||||||
|
|
||||||
|
/// This entity can’t connect to the SOCKS5 proxy.
|
||||||
ProxyError,
|
ProxyError,
|
||||||
|
|
||||||
|
/// XXX: Invalid, should not be found in the wild.
|
||||||
None,
|
None,
|
||||||
}
|
}
|
||||||
|
|
||||||
|
/// Describes a Jingle transport using a direct or proxied connection.
|
||||||
#[derive(Debug, Clone)]
|
#[derive(Debug, Clone)]
|
||||||
pub struct Transport {
|
pub struct Transport {
|
||||||
|
/// The stream identifier for this transport.
|
||||||
pub sid: StreamId,
|
pub sid: StreamId,
|
||||||
|
|
||||||
|
/// The destination address.
|
||||||
pub dstaddr: Option<String>,
|
pub dstaddr: Option<String>,
|
||||||
|
|
||||||
|
/// The mode to be used for the transfer.
|
||||||
pub mode: Mode,
|
pub mode: Mode,
|
||||||
|
|
||||||
|
/// The payload of this transport.
|
||||||
pub payload: TransportPayload,
|
pub payload: TransportPayload,
|
||||||
}
|
}
|
||||||
|
|
||||||
impl Transport {
|
impl Transport {
|
||||||
|
/// Creates a new transport element.
|
||||||
pub fn new(sid: StreamId) -> Transport {
|
pub fn new(sid: StreamId) -> Transport {
|
||||||
Transport {
|
Transport {
|
||||||
sid,
|
sid,
|
||||||
|
@ -93,16 +155,19 @@ impl Transport {
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|
||||||
|
/// Sets the destination address of this transport.
|
||||||
pub fn with_dstaddr(mut self, dstaddr: String) -> Transport {
|
pub fn with_dstaddr(mut self, dstaddr: String) -> Transport {
|
||||||
self.dstaddr = Some(dstaddr);
|
self.dstaddr = Some(dstaddr);
|
||||||
self
|
self
|
||||||
}
|
}
|
||||||
|
|
||||||
|
/// Sets the mode of this transport.
|
||||||
pub fn with_mode(mut self, mode: Mode) -> Transport {
|
pub fn with_mode(mut self, mode: Mode) -> Transport {
|
||||||
self.mode = mode;
|
self.mode = mode;
|
||||||
self
|
self
|
||||||
}
|
}
|
||||||
|
|
||||||
|
/// Sets the payload of this transport.
|
||||||
pub fn with_payload(mut self, payload: TransportPayload) -> Transport {
|
pub fn with_payload(mut self, payload: TransportPayload) -> Transport {
|
||||||
self.payload = payload;
|
self.payload = payload;
|
||||||
self
|
self
|
||||||
|
|
Loading…
Reference in a new issue