--- a/src/common/pcap-file-object.h Mon Feb 01 13:35:47 2010 -0800
+++ b/src/common/pcap-file-object.h Mon Feb 01 14:23:41 2010 -0800
@@ -39,24 +39,189 @@
PcapFileObject ();
~PcapFileObject ();
+ /**
+ * Create a new pcap file object representing a new or existing pcap file.
+ * Semantics are similar to the C standard library function \c fopen
+ *
+ * Possible modes are:
+ *
+ * \verbatim
+ * "r": Open a file for reading. The file must exist. The pcap header
+ * is assumed to exist in the file and will be read and checked.
+ * The file seek position indicator is set to point to the first
+ * packet on exit.
+ *
+ * "w": Create an empty file for writing. If a file with the same name
+ * already exists its content is erased and the file is treated as a
+ * new empty pcap file. The file is assumed not to have a pcap
+ * header and the caller is responsible for calling Init before saving
+ * any packet data. The file seek position indicator is set to point
+ * to the beginning of the file on exit since there will be no pcap
+ * header.
+ *
+ * "a": Append to an existing file. This mode allows for adding packet data
+ * to the end of an existing pcap file. The file must exist and have a
+ * valid pcap header written (N.B. this is different from standard fopen
+ * semantics). The file seek position indicator is set to point
+ * to the end of the file on exit.
+ *
+ * "r+": Open a file for update -- both reading and writing. The file must
+ * exist. The pcap header is assumed to have been written to the
+ * file and will be read and checked. The file seek position indicator
+ * is set to point to the first packet on exit.
+ *
+ * "w+": Create an empty file for both reading and writing. If a file with
+ * the same name already exists, its content is erased and the file is
+ * treated as a new empty pcap file. Since this new file will not have
+ * a pcap header, the caller is responsible for calling Init before
+ * saving any packet data. On exit, the file seek position indicator is
+ * set to point to the beginning of the file.
+ *
+ * "a+" Open a file for reading and appending. The file must exist and have a
+ * valid pcap header written (N.B. this is different from standard fopen
+ * semantics). The file seek position indicator is set to point
+ * to the end of the file on exit. Existing content is preserved.
+ * \endverbatim
+ *
+ * Since a pcap file is always a binary file, the file type is automatically
+ * selected as a binary file. For example, providing a mode string "a+"
+ * results in the underlying OS file being opened in "a+b" mode.
+ *
+ * \param filename String containing the name of the file.
+ *
+ * \param mode String containing the access mode for the file.
+ *
+ * \returns Error indication that should be interpreted as, "did an error
+ * happen"? That is, the method returns false if the open succeeds, true
+ * otherwise. The errno variable will be set by the OS to to provide a
+ * more descriptive failure indication.
+ */
bool Open (std::string const &filename, std::string const &mode);
+ /**
+ * Close the underlying pcap file.
+ */
void Close (void);
+ /**
+ * Initialize the pcap file associated with this object. This file must have
+ * been previously opened with write permissions.
+ *
+ * \param dataLinkType A data link type as defined in the pcap library. If
+ * you want to make resulting pcap files visible in existing tools, the
+ * data link type must match existing definitions, such as PCAP_ETHERNET,
+ * PCAP_PPP, PCAP_80211, etc. If you are storing different kinds of packet
+ * data, such as naked TCP headers, you are at liberty to locally define your
+ * own data link types. According to the pcap-linktype man page, "well-known"
+ * pcap linktypes range from 0 to 177. If you use a large random number for
+ * your type, chances are small for a collision.
+ *
+ * \param snapLen An optional maximum size for packets written to the file.
+ * Defaults to 65535. If packets exceed this length they are truncated.
+ *
+ * \param tzCorrection An integer describing the offset of your local
+ * time zone from UTC/GMT. For example, Pacific Standard Time in the US is
+ * GMT-8, so one would enter -8 for that correction. Defaults to 0 (UTC).
+ *
+ * \return false if the open succeeds, true otherwise.
+ *
+ * \warning Calling this method on an existing file will result in the loss
+ * any existing data.
+ */
bool Init (uint32_t dataLinkType,
uint32_t snapLen = PcapFile::SNAPLEN_DEFAULT,
int32_t tzCorrection = PcapFile::ZONE_DEFAULT);
+ /**
+ * \brief Write the next packet to file
+ *
+ * \param t Packet timestamp as ns3::Time.
+ * \param p Packet to write to the pcap file.
+ *
+ * \return true on error, false otherwise
+ */
bool Write (Time t, Ptr<const Packet> p);
+
+ /**
+ * \brief Write the provided header along with the packet to the pcap file.
+ *
+ * It is the case that adding a header to a packet prior to writing it to a
+ * file must trigger a deep copy in the Packet. By providing the header
+ * separately, we can avoid that copy.
+ *
+ * \param t Packet timestamp as ns3::Time.
+ * \param header The Header to prepend to the packet.
+ * \param p Packet to write to the pcap file.
+ *
+ * \return true on error, false otherwise
+ */
bool Write (Time t, Header &header, Ptr<const Packet> p);
+
+ /**
+ * \brief Write the provided data buffer to the pcap file.
+ *
+ * \param t Packet timestamp as ns3::Time.
+ * \param buffer The buffer to write.
+ * \param length The size of the buffer.
+ *
+ * \return true on error, false otherwise
+ */
bool Write (Time t, uint8_t const *buffer, uint32_t length);
+ /*
+ * \brief Returns the magic number of the pcap file as defined by the magic_number
+ * field in the pcap global header.
+ *
+ * See http://wiki.wireshark.org/Development/LibpcapFileFormat
+ */
uint32_t GetMagic (void);
+
+ /*
+ * \brief Returns the major version of the pcap file as defined by the version_major
+ * field in the pcap global header.
+ *
+ * See http://wiki.wireshark.org/Development/LibpcapFileFormat
+ */
uint16_t GetVersionMajor (void);
+
+ /*
+ * \brief Returns the minor version of the pcap file as defined by the version_minor
+ * field in the pcap global header.
+ *
+ * See http://wiki.wireshark.org/Development/LibpcapFileFormat
+ */
uint16_t GetVersionMinor (void);
+
+ /*
+ * \brief Returns the time zone offset of the pcap file as defined by the thiszone
+ * field in the pcap global header.
+ *
+ * See http://wiki.wireshark.org/Development/LibpcapFileFormat
+ */
int32_t GetTimeZoneOffset (void);
+
+ /*
+ * \brief Returns the accuracy of timestamps field of the pcap file as defined
+ * by the sigfigs field in the pcap global header.
+ *
+ * See http://wiki.wireshark.org/Development/LibpcapFileFormat
+ */
uint32_t GetSigFigs (void);
+
+ /*
+ * \brief Returns the max length of saved packets field of the pcap file as
+ * defined by the snaplen field in the pcap global header.
+ *
+ * See http://wiki.wireshark.org/Development/LibpcapFileFormat
+ */
uint32_t GetSnapLen (void);
+
+ /*
+ * \brief Returns the data link type field of the pcap file as defined by the
+ * network field in the pcap global header.
+ *
+ * See http://wiki.wireshark.org/Development/LibpcapFileFormat
+ */
uint32_t GetDataLinkType (void);
private:
--- a/src/common/pcap-file.h Mon Feb 01 13:35:47 2010 -0800
+++ b/src/common/pcap-file.h Mon Feb 01 14:23:41 2010 -0800
@@ -105,6 +105,9 @@
*/
bool Open (std::string const &filename, std::string const &mode);
+ /**
+ * Close the underlying file.
+ */
void Close (void);
/**