pnet 0.1.1

Cross-platform, low level networking using the Rust programming language.
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
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139

// Copyright (c) 2014, 2015 Robert Clipsham <robert@octarineparrot.com>
//
// Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
// http://www.apache.org/licenses/LICENSE-2.0> or the MIT license
// <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your
// option. This file may not be copied, modified, or distributed
// except according to those terms.

//! Support for sending and receiving data link layer packets

use std::io;
use std::iter::Iterator;
use std::option::{Option};

use packet::ethernet::{EtherType, EthernetPacket, MutableEthernetPacket};
use util::NetworkInterface;

#[cfg(windows)]
#[path = "winpcap.rs"]
mod backend;

#[cfg(all(not(feature = "netmap"),
          target_os = "linux"
          )
      )]
#[path = "linux.rs"]
mod backend;

#[cfg(all(not(feature = "netmap"),
          any(target_os = "freebsd",
              target_os = "macos")
             )
     )]
#[path = "bpf.rs"]
mod backend;

#[cfg(feature = "netmap")]
#[path = "netmap.rs"]
mod backend;

/// Type of data link channel to present
#[derive(Clone, Copy)]
pub enum DataLinkChannelType {
    /// Send and receive layer 2 packets directly, including headers
    Layer2,
    /// Send and receive "cooked" packets - send and receive network layer packets
    /// FIXME Currently unimplemented
    Layer3(EtherType)
}

/// Create a new (DataLinkSender, DataLinkReceiver) pair
///
/// This allows for sending and receiving packets at the data link layer.
///
/// A list of network interfaces can be retrieved using util::get_network_interfaces().
///
/// The buffer sizes should be large enough to handle the largest packet you wish
/// to send or receive. Note that these parameters may be ignored, depending on the operating
/// system.
///
/// The channel type specifies what layer to send and receive packets at, currently only layer 2 is
/// supported.
#[inline]
pub fn datalink_channel(network_interface: &NetworkInterface,
                        write_buffer_size: usize,
                        read_buffer_size: usize,
                        channel_type: DataLinkChannelType)
    -> io::Result<(DataLinkSender, DataLinkReceiver)> {
    match backend::datalink_channel(network_interface, write_buffer_size, read_buffer_size,
                                             channel_type) {
        Ok((tx, rx)) => Ok((DataLinkSender { dlsi: tx }, DataLinkReceiver { dlri: rx })),
        Err(e) => Err(e)
    }
}

/// Structure for sending packets at the data link layer. Should be constructed using
/// datalink_channel().
pub struct DataLinkSender {
    dlsi: backend::DataLinkSenderImpl
}

impl DataLinkSender {
    /// Create and send a number of packets
    ///
    /// This will call `func` `num_packets` times. The function will be provided with a mutable
    /// packet to manipulate, which will then be sent. This allows packets to be built in-place,
    /// avoiding the copy required for `send`. If there is not sufficient capacity in the buffer,
    /// None will be returned.
    #[inline]
    pub fn build_and_send<F>(&mut self, num_packets: usize, packet_size: usize,
                          func: &mut F) -> Option<io::Result<()>>
        where F : FnMut(MutableEthernetPacket)
    {
        self.dlsi.build_and_send(num_packets, packet_size, func)
    }

    /// Send a packet
    ///
    /// This may require an additional copy compared to `build_and_send`, depending on the
    /// operating system being used. The second parameter is currently ignored, however `None`
    /// should be passed.
    #[inline]
    pub fn send_to(&mut self, packet: &EthernetPacket, dst: Option<NetworkInterface>)
        -> Option<io::Result<()>> {
        self.dlsi.send_to(packet, dst)
    }
}

/// Structure for receiving packets at the data link layer. Should be constructed using
/// datalink_channel().
pub struct DataLinkReceiver {
    dlri: backend::DataLinkReceiverImpl
}

impl DataLinkReceiver {
    /// Returns an iterator over `EthernetPacket`s.
    ///
    /// This will likely be removed once other layer two types are supported.
    #[inline]
    pub fn iter<'a>(&'a mut self) -> DataLinkChannelIterator<'a> {
        DataLinkChannelIterator {
            imp: self.dlri.iter()
        }
    }
}

/// An iterator over data link layer packets
pub struct DataLinkChannelIterator<'a> {
    imp: backend::DataLinkChannelIteratorImpl<'a>,
}

impl<'a> DataLinkChannelIterator<'a> {
    /// Get the next EthernetPacket in the channel
    #[inline]
    pub fn next<'c>(&'c mut self) -> io::Result<EthernetPacket<'c>> {
        self.imp.next()
    }
}