get_port/
lib.rs

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
pub mod tcp;
mod tests;
pub mod udp;

pub struct Range {
    pub min: u16,
    pub max: u16,
}

type Port = u16;

impl Default for Range {
    fn default() -> Self {
        Range {
            min: 1024,
            max: 65535,
        }
    }
}

/// A trait for defining behaviour on the lib's functions
pub trait Ops {
    /// Returns any port in default range.
    ///
    /// # Arguments
    ///* `host` - a string slice pointing to the hostname to test the port availability on.
    ///
    /// # Examples
    ///```
    ///use get_port::tcp::TcpPort;
    ///use get_port::udp::UdpPort;
    ///use get_port::Ops;
    ///
    ///let tcp_port = TcpPort::any("127.0.0.1").unwrap();
    ///let udp_port = UdpPort::any("127.0.0.1").unwrap();
    /// ```
    fn any(host: &str) -> Option<Port>;

    /// Returns any port in given range.
    ///
    /// # Arguments
    /// * `host` - a string slice pointing to the hostname to test the port availability on.
    /// * `r` - the Range to choose a port from.
    ///
    /// # Examples
    /// ```
    /// use get_port::tcp::TcpPort;
    /// use get_port::{Ops, Range};
    /// use get_port::udp::UdpPort;
    ///
    /// let tcp_port = TcpPort::in_range("127.0.0.1", Range {min: 6000, max: 7000 }).unwrap();
    /// let udp_port = UdpPort::in_range("127.0.0.1", Range {min: 8000, max: 9000 }).unwrap();
    /// ```
    fn in_range(host: &str, r: Range) -> Option<Port>;

    /// Returns any port from the supplied list.
    ///
    /// # Arguments
    /// * `host` - a string slice pointing to the hostname to test the port availability on.
    /// * `v` - a vector of Ports (`u16`) to choose from.
    ///
    /// # Examples
    /// ```
    /// use get_port::tcp::TcpPort;
    /// use get_port::Ops;
    /// use get_port::udp::UdpPort;
    ///
    /// let tcp_port = TcpPort::from_list("127.0.0.1", vec![5000, 6000]).unwrap();
    /// let udp_port = UdpPort::from_list("127.0.0.1", vec![5000, 6000]).unwrap();
    /// ```
    fn from_list(host: &str, v: Vec<Port>) -> Option<Port>;

    /// Returns any port from the default range except for the ones in the supplied list.
    ///
    /// # Arguments
    /// * `host` - a string slice pointing to the hostname to test the port availability on.
    /// * `v` - a vector of Ports (`u16`) to exclude.
    ///
    /// # Examples
    /// ```
    /// use get_port::tcp::TcpPort;
    /// use get_port::Ops;
    /// use get_port::udp::UdpPort;
    ///
    /// let tcp_port = TcpPort::except("127.0.0.1", vec![1456, 6541]).unwrap();
    /// let udp_port = UdpPort::except("127.0.0.1", vec![1456, 6541]).unwrap();
    /// ```
    fn except(host: &str, v: Vec<Port>) -> Option<Port>;

    /// Returns any port from the supplied range except for the ones in the supplied list.
    ///
    /// # Arguments
    /// * `host` - a string slice pointing to the hostname to test the port availability on.
    /// * `r` - the Range to choose a port from.
    /// * `v` - a vector of Ports (`u16`) to exclude.
    ///
    /// # Examples
    /// ```
    /// use get_port::tcp::TcpPort;
    /// use get_port::{Ops, Range};
    /// use get_port::udp::UdpPort;
    ///
    /// let tcp_port = TcpPort::in_range_except("127.0.0.1", Range { min: 6000, max: 7000 }, vec![6500]).unwrap();
    /// let udp_port = UdpPort::in_range_except("127.0.0.1", Range { min: 6000, max: 7000 }, vec![6500]).unwrap();
    /// ```
    fn in_range_except(host: &str, r: Range, v: Vec<Port>) -> Option<Port>;

    /// Utility function to check whether a port is available or not.
    fn is_port_available(host: &str, p: Port) -> bool;
}