utp/
stream.rs

1use std::io::{Read, Write, Result};
2use std::net::{ToSocketAddrs, SocketAddr};
3use std::ops::Deref;
4use socket::UtpSocket;
5
6/// A structure that represents a uTP (Micro Transport Protocol) stream between a local socket and a
7/// remote socket.
8///
9/// The connection will be closed when the value is dropped (either explicitly or when it goes out
10/// of scope).
11///
12/// The default maximum retransmission retries is 5, which translates to about 16 seconds. It can be
13/// changed by calling `set_max_retransmission_retries`. Notice that the initial congestion timeout
14/// is 500 ms and doubles with each timeout.
15///
16/// # Examples
17///
18/// ```no_run
19/// use utp::UtpStream;
20/// use std::io::{Read, Write};
21///
22/// let mut stream = UtpStream::bind("127.0.0.1:1234").expect("Error binding stream");
23/// let _ = stream.write(&[1]);
24/// let _ = stream.read(&mut [0; 1000]);
25/// ```
26pub struct UtpStream {
27    socket: UtpSocket,
28}
29
30impl UtpStream {
31    /// Creates a uTP stream listening on the given address.
32    ///
33    /// The address type can be any implementer of the `ToSocketAddr` trait. See its documentation
34    /// for concrete examples.
35    ///
36    /// If more than one valid address is specified, only the first will be used.
37    pub fn bind<A: ToSocketAddrs>(addr: A) -> Result<UtpStream> {
38        UtpSocket::bind(addr).map(|s| UtpStream { socket: s })
39    }
40
41    /// Opens a uTP connection to a remote host by hostname or IP address.
42    ///
43    /// The address type can be any implementer of the `ToSocketAddr` trait. See its documentation
44    /// for concrete examples.
45    ///
46    /// If more than one valid address is specified, only the first will be used.
47    pub fn connect<A: ToSocketAddrs>(dst: A) -> Result<UtpStream> {
48        // Port 0 means the operating system gets to choose it
49        UtpSocket::connect(dst).map(|s| UtpStream { socket: s })
50    }
51
52    /// Gracefully closes connection to peer.
53    ///
54    /// This method allows both peers to receive all packets still in
55    /// flight.
56    pub fn close(&mut self) -> Result<()> {
57        self.socket.close()
58    }
59
60    /// Returns the socket address of the local half of this uTP connection.
61    pub fn local_addr(&self) -> Result<SocketAddr> {
62        self.socket.local_addr()
63    }
64
65    /// Changes the maximum number of retransmission retries on the underlying socket.
66    pub fn set_max_retransmission_retries(&mut self, n: u32) {
67        self.socket.max_retransmission_retries = n;
68    }
69
70    /// Try to send a keepalive packet to the peer, ensuring the connection stays active.
71    pub fn send_keepalive(&mut self) {
72        self.socket.send_keepalive();
73    }
74}
75
76impl Read for UtpStream {
77    fn read(&mut self, buf: &mut [u8]) -> Result<usize> {
78        self.socket.recv_from(buf).map(|(read, _src)| read)
79    }
80}
81
82impl Write for UtpStream {
83    fn write(&mut self, buf: &[u8]) -> Result<usize> {
84        self.socket.send_to(buf)
85    }
86
87    fn flush(&mut self) -> Result<()> {
88        self.socket.flush()
89    }
90}
91
92impl Into<UtpStream> for UtpSocket {
93    fn into(self) -> UtpStream {
94        UtpStream { socket: self }
95    }
96}
97
98impl Deref for UtpStream {
99    type Target = UtpSocket;
100
101    fn deref(&self) -> &UtpSocket {
102        &self.socket
103    }
104}
utp/stream.rs

utp/
stream.rs
