//! pcap is a packet capture library available on Linux, Windows and Mac. This

//! crate supports creating and configuring capture contexts, sniffing packets,

//! sending packets to interfaces, listing devices, and recording packet captures

//! to pcap-format dump files.

//!

//! # Capturing packets

//! The easiest way to open an active capture handle and begin sniffing is to

//! use `.open()` on a `Device`. You can obtain the "default" device using

//! `Device::lookup()`, or you can obtain the device(s) you need via `Device::list()`.

//!

//! ```no_run

//! use pcap::Device;

//!

//! let mut cap = Device::lookup().unwrap().unwrap().open().unwrap();

//!

//! while let Ok(packet) = cap.next_packet() {

//!     println!("received packet! {:?}", packet);

//! }

//!

//! ```

//!

//! `Capture`'s `.next_packet()` will produce a `Packet` which can be dereferenced to access the

//! `&[u8]` packet contents.

//!

//! # Custom configuration

//!

//! You may want to configure the `timeout`, `snaplen` or other parameters for the capture

//! handle. In this case, use `Capture::from_device()` to obtain a `Capture<Inactive>`, and

//! proceed to configure the capture handle. When you're finished, run `.open()` on it to

//! turn it into a `Capture<Active>`.

//!

//! ```no_run

//! use pcap::{Device, Capture};

//!

//! let main_device = Device::lookup().unwrap().unwrap();

//! let mut cap = Capture::from_device(main_device).unwrap()

//!                   .promisc(true)

//!                   .snaplen(5000)

//!                   .open().unwrap();

//!

//! while let Ok(packet) = cap.next_packet() {

//!     println!("received packet! {:?}", packet);

//! }

//! ```

//!

//! # Abstracting over different capture types

//!

//! You can abstract over live captures (`Capture<Active>`) and file captures

//! (`Capture<Offline>`) using generics and the [`Activated`] trait, for example:

//!

//! ```

//! use pcap::{Activated, Capture};

//!

//! fn read_packets<T: Activated>(mut capture: Capture<T>) {

//!     while let Ok(packet) = capture.next_packet() {

//!         println!("received packet! {:?}", packet);

//!     }

//! }

//! ```

#![cfg_attr(docsrs, feature(doc_cfg))]

use std::ffi::{self, CStr, CString};

use std::fmt;

use std::path::Path;

use self::Error::*;

mod capture;

mod codec;

mod device;

mod linktype;

mod packet;

#[cfg(not(windows))]

pub use capture::activated::open_raw_fd;

pub use capture::{

    activated::{

        BpfInstruction, BpfProgram, BreakLoop, Direction, Savefile, Stat, iterator::PacketIter,

    },

    inactive::TimestampType,

    {Activated, Active, Capture, Dead, Inactive, Offline, Precision, State, Warning, WarningCode},

};

pub use codec::PacketCodec;

pub use device::{Address, ConnectionStatus, Device, DeviceFlags, IfFlags};

pub use linktype::Linktype;

pub use packet::{Packet, PacketHeader};

#[deprecated(note = "Renamed to TimestampType")]

/// An old name for `TimestampType`, kept around for backward-compatibility.

pub type TstampType = TimestampType;

mod raw;

#[cfg(windows)]

#[cfg_attr(docsrs, doc(cfg(windows)))]

pub mod sendqueue;

#[cfg(feature = "capture-stream")]

mod sink;

#[cfg(feature = "capture-stream")]

#[cfg_attr(docsrs, doc(cfg(feature = "capture-stream")))]

pub use sink::PacketSink;

#[cfg(feature = "capture-stream")]

mod stream;

#[cfg(feature = "capture-stream")]

#[cfg_attr(docsrs, doc(cfg(feature = "capture-stream")))]

pub use stream::PacketStream;

/// A list of libpcap's own error codes.

///

/// Anything else it fails with arrives as [`Error::PcapError`], with only the message to go on.

/// Not all of these can be reached through this crate, but libpcap defines them and so they are

/// all here.

#[derive(Debug, PartialEq, Eq, Clone, Copy)]

#[non_exhaustive]

pub enum ErrorCode {

    /// The loop was terminated by `BreakLoop::breakloop`

    Break,

    /// The capture has not been activated

    NotActivated,

    /// The capture has already been activated

    AlreadyActivated,

    /// No such device exists

    NoSuchDevice,

    /// The device does not support monitor mode

    MonitorModeNotSupported,

    /// The operation is only supported in monitor mode

    NotInMonitorMode,

    /// No permission to open the device

    PermissionDenied,

    /// The interface is not up

    InterfaceNotUp,

    /// The device does not support setting the timestamp type

    CannotSetTimestampType,

    /// No permission to capture in promiscuous mode

    PromiscuousPermissionDenied,

    /// The device does not support the requested timestamp precision

    TimestampPrecisionNotSupported,

    /// The capture mechanism is not available

    CaptureNotSupported,

}

impl fmt::Display for ErrorCode {

            ErrorCode::CannotSetTimestampType => {

            }

            ErrorCode::PromiscuousPermissionDenied => {

            }

            ErrorCode::TimestampPrecisionNotSupported => {

            }

        })

}

/// An error received from pcap

#[derive(Debug, PartialEq, Eq)]

#[non_exhaustive]

pub enum Error {

    /// The underlying library returned invalid UTF-8

    MalformedError(std::str::Utf8Error),

    /// The underlying library returned a null string

    InvalidString,

    /// The unerlying library returned an error

    PcapError(String),

    /// The underlying library returned an error it has a code for, along with the message it

    /// left behind. The message is sometimes the more useful of the two.

    PcapErrorCode(ErrorCode, String),

    /// The linktype was invalid or unknown

    InvalidLinktype,

    /// The capture device does not support the timestamp type

    UnsupportedTimestampType,

    /// The capture device does not support the timestamp precision

    UnsupportedTimestampPrecision,

    /// The timeout expired while reading from a live capture

    TimeoutExpired,

    /// No more packets to read from the file

    NoMorePackets,

    /// The interface being captured from went away

    InterfaceDisappeared,

    /// Must be in non-blocking mode to function

    NonNonBlock,

    /// There is not sufficent memory to create a dead capture

    InsufficientMemory,

    /// An invalid input string (internal null)

    InvalidInputString,

    /// An IO error occurred

    IoError(std::io::ErrorKind),

    #[cfg(not(windows))]

    /// An invalid raw file descriptor was provided

    InvalidRawFd,

    #[cfg(windows)]

    /// A path that libpcap cannot be given because it is not valid UTF-8

    InvalidPath,

    /// Errno error

    ErrnoError(errno::Errno),

    #[cfg(windows)]

    /// The capture library could not be loaded

    LibraryNotFound,

    #[cfg(windows)]

    /// The capture library does not have an entrypoint the call needs

    EntrypointNotFound(&'static str),

    /// Buffer size overflows capacity

    BufferOverflow,

}

impl Error {

        // An interface going away is reported as PCAP_ERROR like every other failure, so the

        // message is all there is to go on. Windows adds the error code it got to the end,

        // which is why this matches the start rather than the whole string.

    /// Read one of the status codes libpcap returns, along with the message it left behind.

        // A loop that was told to stop is the one case libpcap leaves no message for, so the

        // error buffer still holds the last thing that went wrong on the handle. Do not read it.

            // PCAP_ERROR is what libpcap uses when it has no more specific code, and a code it

            // gained after this was written would land here too. Either way the message is all

            // that tells the conditions apart.

        };

    {

}

// Strict, for a string that goes back to libpcap: a device name that will not round-trip is worse

// than no name at all.

// Lossy, for a string that is only displayed: a message truncated mid-sequence at

// PCAP_ERRBUF_SIZE, or a description in the local Windows code page, is worth showing anyway.

    #[cfg(not(windows))]

        use std::os::unix::ffi::OsStrExt;

    };

    // libpcap has no entrypoints taking wide strings. It reads the path in the local code page,

    // or in UTF-8 once pcap_init has been asked for that, so give it the UTF-8 form. A path that

    // is not valid UTF-8 holds an unpaired surrogate, which has no form libpcap would accept.

    #[cfg(windows)]

    let bytes = path

        .as_os_str()

        .to_str()

        .ok_or(Error::InvalidPath)?

        .as_bytes();

impl fmt::Display for Error {

            // The code is what a caller matches on; the message is what libpcap writes for a

            // reader, and it usually says the same thing at more length. Only fall back to

            // describing the code when there is no message, as for a loop that was told to stop.

            #[cfg(not(windows))]

            #[cfg(windows)]

            InvalidPath => write!(f, "invalid path (not valid UTF-8)"),

            #[cfg(windows)]

            LibraryNotFound => write!(f, "could not load wpcap.dll, Npcap may not be installed"),

            #[cfg(windows)]

            EntrypointNotFound(name) => {

                write!(

                    f,

                    "the installed wpcap.dll does not export {name}, upgrade to a newer Npcap"

                )

            }

        }

}

// Using description is deprecated. Remove in next version.

impl std::error::Error for Error {

            #[cfg(not(windows))]

            #[cfg(windows)]

            InvalidPath => "invalid path (not valid UTF-8)",

            #[cfg(windows)]

            LibraryNotFound => "could not load wpcap.dll",

            #[cfg(windows)]

            EntrypointNotFound(..) => "wpcap.dll is missing an entrypoint",

        }

        }

}

impl From<ffi::NulError> for Error {

}

impl From<std::str::Utf8Error> for Error {

}

impl From<std::io::Error> for Error {

}

impl From<std::io::ErrorKind> for Error {

}

/// Return size of a commonly used packet header.

///

/// On Windows this packet header is implicitly added to send queues, so this size must be known

/// if an application needs to precalculate the exact send queue buffer size.

#[cfg(libpcap_1_10_0)]

#[repr(u32)]

#[derive(Debug, PartialEq, Eq, Clone, Copy)]

/// The character encoding libpcap uses for strings. Use with `init`.

pub enum CharEncoding {

    /// Strings are in the local character encoding. On UN*X that is taken to be UTF-8, on Windows

    /// it is the local ANSI code page. This is the default.

    Local = raw::PCAP_CHAR_ENC_LOCAL,

    /// Strings are in UTF-8.

    Utf8 = raw::PCAP_CHAR_ENC_UTF_8,

}

/// Initialize the library, choosing the character encoding it uses for the strings it is given

/// and the strings it returns.

///

/// This is optional, but it has to come before any other libpcap call, and a second call asking

/// for a different encoding fails. Without it strings are in the local character encoding.

///

/// On Windows this is what makes a path outside ASCII work, since the local code page is

/// usually not UTF-8.

#[cfg(libpcap_1_10_0)]

    #[cfg(windows)]

    if !raw::has_init() {

        return Err(Error::EntrypointNotFound("pcap_init"));

    }

#[cfg(test)]

mod tests {

    use std::error::Error as StdError;

    use std::{ffi::CString, io};

    #[cfg(libpcap_1_10_0)]

    use crate::raw::testmod::RAWMTX;

    use super::*;

    #[test]

    fn test_error_invalid_utf8() {

        let bytes: [u8; 8] = [0x78, 0xfe, 0xe9, 0x89, 0x00, 0x00, 0xed, 0x4f];

        let error = unsafe { Error::new(&bytes as *const _ as _) };

        // The message is kept, with the bytes that are not valid UTF-8 replaced.

        assert_eq!(error, Error::PcapError("x\u{fffd}\u{fffd}".to_string()));

    }

    #[test]

    fn test_error_null() {

        let error = unsafe { Error::new(std::ptr::null()) };

        assert_eq!(error, Error::PcapError("".to_string()));

    }

    #[test]

    fn test_error_interface_disappeared() {

        let message = CString::new("The interface disappeared").unwrap();

        let error = unsafe { Error::new(message.as_ptr()) };

        assert_eq!(error, Error::InterfaceDisappeared);

        // Windows puts the error code it got on the end of the message.

        let message = CString::new(

            "The interface disappeared (error code ERROR_DEVICE_REMOVED/STATUS_DEVICE_REMOVED)",

        )

        .unwrap();

        let error = unsafe { Error::new(message.as_ptr()) };

        assert_eq!(error, Error::InterfaceDisappeared);

        // Another message about the interface is still a plain one.

        let message = CString::new("The interface went down").unwrap();

        let error = unsafe { Error::new(message.as_ptr()) };

        assert_eq!(

            error,

            Error::PcapError("The interface went down".to_string())

        );

    }

    #[test]

    fn test_error_from_status() {

        let message = CString::new("no dice").unwrap();

        let cases = [

            (raw::PCAP_ERROR_BREAK, ErrorCode::Break),

            (raw::PCAP_ERROR_NOT_ACTIVATED, ErrorCode::NotActivated),

            (raw::PCAP_ERROR_ACTIVATED, ErrorCode::AlreadyActivated),

            (raw::PCAP_ERROR_NO_SUCH_DEVICE, ErrorCode::NoSuchDevice),

            (

                raw::PCAP_ERROR_RFMON_NOTSUP,

                ErrorCode::MonitorModeNotSupported,

            ),

            (raw::PCAP_ERROR_NOT_RFMON, ErrorCode::NotInMonitorMode),

            (raw::PCAP_ERROR_PERM_DENIED, ErrorCode::PermissionDenied),

            (raw::PCAP_ERROR_IFACE_NOT_UP, ErrorCode::InterfaceNotUp),

            (

                raw::PCAP_ERROR_CANTSET_TSTAMP_TYPE,

                ErrorCode::CannotSetTimestampType,

            ),

            (

                raw::PCAP_ERROR_PROMISC_PERM_DENIED,

                ErrorCode::PromiscuousPermissionDenied,

            ),

            (

                raw::PCAP_ERROR_TSTAMP_PRECISION_NOTSUP,

                ErrorCode::TimestampPrecisionNotSupported,

            ),

            (

                raw::PCAP_ERROR_CAPTURE_NOTSUP,

                ErrorCode::CaptureNotSupported,

            ),

        ];

        for (status, code) in cases {

            // A stopped loop is the one code that leaves the error buffer alone, so it is also

            // the one whose message is not read.

            let kept = match code {

                ErrorCode::Break => String::new(),

                _ => "no dice".to_string(),

            };

            let error = unsafe { Error::from_status(status, message.as_ptr()) };

            assert_eq!(error, Error::PcapErrorCode(code, kept));

            // With no message left behind, each code has to describe itself.

            let error = unsafe { Error::from_status(status, std::ptr::null()) };

            assert_eq!(error, Error::PcapErrorCode(code, String::new()));

            assert!(error.to_string().len() > "libpcap error: ".len());

        }

        // The generic code, and one libpcap has yet to define, leave only the message.

        for status in [raw::PCAP_ERROR, -99] {

            let error = unsafe { Error::from_status(status, message.as_ptr()) };

            assert_eq!(error, Error::PcapError("no dice".to_string()));

        }

    }

    #[test]

    #[allow(deprecated)]

    fn test_errors() {

        let mut errors: Vec<Error> = vec![];

        let bytes: [u8; 8] = [0x78, 0xfe, 0xe9, 0x89, 0x00, 0x00, 0xed, 0x4f];

        let cstr = unsafe { CStr::from_ptr(&bytes as *const _ as _) };

        errors.push(cstr.to_str().unwrap_err().into());

        errors.push(Error::InvalidString);

        errors.push(Error::PcapError("git rekt".to_string()));

        errors.push(Error::InvalidLinktype);

        errors.push(Error::UnsupportedTimestampType);

        errors.push(Error::UnsupportedTimestampPrecision);

        errors.push(Error::TimeoutExpired);

        errors.push(Error::NoMorePackets);

        errors.push(Error::InterfaceDisappeared);

        errors.push(Error::PcapErrorCode(

            ErrorCode::PermissionDenied,

            "nope".to_string(),

        ));

        // A code libpcap leaves no message with still has to describe itself.

        errors.push(Error::PcapErrorCode(ErrorCode::Break, String::new()));

        errors.push(Error::NonNonBlock);

        errors.push(Error::InsufficientMemory);

        errors.push(CString::new(b"f\0oo".to_vec()).unwrap_err().into());

        errors.push(io::Error::new(io::ErrorKind::Interrupted, "error").into());

        #[cfg(not(windows))]

        errors.push(Error::InvalidRawFd);

        #[cfg(windows)]

        errors.push(Error::InvalidPath);

        errors.push(Error::ErrnoError(errno::Errno(125)));

        #[cfg(windows)]

        errors.push(Error::LibraryNotFound);

        #[cfg(windows)]

        errors.push(Error::EntrypointNotFound("pcap_set_immediate_mode"));

        errors.push(Error::BufferOverflow);

        for error in errors.iter() {

            assert!(!error.to_string().is_empty());

            assert!(!error.description().is_empty());

            match error {

                Error::MalformedError(_) => assert!(error.cause().is_some()),

                _ => assert!(error.cause().is_none()),

            }

        }

    }

    #[test]

    fn test_packet_size() {

        assert_eq!(

            packet_header_size(),

            std::mem::size_of::<raw::pcap_pkthdr>()

        );

    }

    #[test]

    #[cfg(windows)]

    fn test_path_to_cstring_not_utf8() {

        use std::ffi::OsString;

        use std::os::windows::ffi::OsStringExt;

        // An unpaired surrogate, which a Windows path may hold and UTF-8 cannot express.

        let name = OsString::from_wide(&[0xd800]);

        let result = path_to_cstring(Path::new(&name));

        assert_eq!(result.unwrap_err(), Error::InvalidPath);

    }

    #[test]

    #[cfg(libpcap_1_10_0)]

    fn test_init() {

        let _m = RAWMTX.lock();

        #[cfg(windows)]

        let has = raw::has_init_context();

        #[cfg(windows)]

        has.expect().times(..).return_const(true);

        let ctx = raw::pcap_init_context();

        ctx.expect()

            .withf_st(|_, arg1, _| *arg1 == raw::PCAP_CHAR_ENC_UTF_8)

            .return_once(|_, _, _| 0);

        let result = init(CharEncoding::Utf8);

        assert!(result.is_ok());

        let ctx = raw::pcap_init_context();

        ctx.checkpoint();

        ctx.expect()

            .withf_st(|_, arg1, _| *arg1 == raw::PCAP_CHAR_ENC_LOCAL)

            .return_once(|_, _, _| -1);

        let result = init(CharEncoding::Local);

        assert!(result.is_err());

    }

}