Sendqueue pkt header size (#379)

* Make docs.rs source view generate links to definitions.

* Disable default features for eui48 crate so it will no longer pull in rustc-serialize, which has had a history of causing builds to print deprecation warnings.

* Revert "Disable default features for eui48 crate so it will no longer pull in rustc-serialize, which has had a history of causing builds to print deprecation warnings."

This reverts commit 36138ca.

* Add `SendQueue::packet_header_size()` which can be used by applications
that want to precalculate required total SendQueue size.

This size is available using other types in the crate, but tying the
query to the `SendQueue` allows us to avoid a breaking change in case
the SendQueue's header ever changes (even though this is highly unlikely
to happen).

* Update changelog.

* Move packet header size query function and add a test case.

* Document how to get the size of the implicitly added packet header.

---------

Co-authored-by: Jan Danielsson <jan@void>

CHANGELOG.md

@@ -2,6 +2,13 @@
 
 ## [Unreleased]
 
+### Added
+
+- Added `packet_header_size()` for applications that need to know the size of internal type
+  `pcap_pkthdr` (for instance to calculate exact send queue sizes).
+
+want to precalculate exact queue sizes.
+
 ## [2.2.0] - 2024-09-01
 
 ### Added

src/lib.rs

@@ -227,6 +227,14 @@ 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.
+pub const fn packet_header_size() -> usize {
+    std::mem::size_of::<raw::pcap_pkthdr>()
+}
+
 #[cfg(test)]
 mod tests {
     use std::error::Error as StdError;
@@ -279,4 +287,12 @@ mod tests {
             }
         }
     }
+
+    #[test]
+    fn test_packet_size() {
+        assert_eq!(
+            packet_header_size(),
+            std::mem::size_of::<raw::pcap_pkthdr>()
+        );
+    }
 }

src/sendqueue/windows.rs

@@ -46,6 +46,9 @@ impl SendQueue {
     ///
     /// The buffer size `memsize` must be able to contain both packet headers and actual packet
     /// contents.
+    ///
+    /// Applications that need to precalculate exact buffer sizes can use [`packet_header_size()`](crate::packet_header_size())
+    /// to get the size of the header that is implicitly added along with each packet.
     pub fn new(memsize: u32) -> Result<Self, Error> {
         let squeue = unsafe { raw::pcap_sendqueue_alloc(memsize) };
         let squeue = NonNull::new(squeue).ok_or(Error::InsufficientMemory)?;