Updated with latest version changes to original source by Politecnico di Torino.

svn path=/trunk/; revision=3551

reactos/lib/packet/include/packet32.h

@@ -19,6 +19,17 @@
  * MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
  */
 
+/** @ingroup packetapi
+ *  @{ 
+ */
+
+/** @defgroup packet32h Packet.dll definitions and data structures
+ *  Packet32.h contains the data structures and the definitions used by packet.dll.
+ *  The file is used both by the Win9x and the WinNTx versions of packet.dll, and can be included
+ *  by the applications that use the functions of this library
+ *  @{
+ */
+
 #ifndef __PACKET32
 #define __PACKET32
 
@@ -42,31 +53,41 @@
 #define IOCTL_OPEN                  CTL_CODE(FILE_DEVICE_PROTOCOL, 7 , METHOD_BUFFERED, FILE_ANY_ACCESS)
 #define IOCTL_CLOSE                 CTL_CODE(FILE_DEVICE_PROTOCOL, 8 , METHOD_BUFFERED, FILE_ANY_ACCESS)
 
-#define	 pBIOCSETBUFFERSIZE 9592
+#define	 pBIOCSETBUFFERSIZE 9592		///< IOCTL code: set kernel buffer size.
-#define	 pBIOCSETF 9030
+#define	 pBIOCSETF 9030					///< IOCTL code: set packet filtering program.
-#define  pBIOCGSTATS 9031
+#define  pBIOCGSTATS 9031				///< IOCTL code: get the capture stats.
-#define	 pBIOCSRTIMEOUT 7416
+#define	 pBIOCSRTIMEOUT 7416			///< IOCTL code: set the read timeout.
-#define	 pBIOCSMODE 7412
+#define	 pBIOCSMODE 7412				///< IOCTL code: set working mode.
-#define	 pBIOCSWRITEREP 7413
+#define	 pBIOCSWRITEREP 7413			///< IOCTL code: set number of physical repetions of every packet written by the app.
-#define	 pBIOCSMINTOCOPY 7414
+#define	 pBIOCSMINTOCOPY 7414			///< IOCTL code: set minimum amount of data in the kernel buffer that unlocks a read call.
-#define	 pBIOCSETOID 2147483648
+#define	 pBIOCSETOID 2147483648			///< IOCTL code: set an OID value.
-#define	 pBIOCQUERYOID 2147483652
+#define	 pBIOCQUERYOID 2147483652		///< IOCTL code: get an OID value.
-#define	 pATTACHPROCESS 7117
+#define	 pATTACHPROCESS 7117			///< IOCTL code: attach a process to the driver. Used in Win9x only.
-#define	 pDETACHPROCESS 7118
+#define	 pDETACHPROCESS 7118			///< IOCTL code: detach a process from the driver. Used in Win9x only.
-#define  pBIOCSETDUMPFILENAME 9029
+#define  pBIOCSETDUMPFILENAME 9029		///< IOCTL code: set the name of a the file used by kernel dump mode.
-#define  pBIOCEVNAME 7415
+#define  pBIOCEVNAME 7415				///< IOCTL code: get the name of the event that the driver signals when some data is present in the buffer.
+#define  pBIOCSENDPACKETSNOSYNC 9032	///< IOCTL code: Send a buffer containing multiple packets to the network, ignoring the timestamps associated with the packets.
+#define  pBIOCSENDPACKETSSYNC 9033		///< IOCTL code: Send a buffer containing multiple packets to the network, respecting the timestamps associated with the packets.
+#define  pBIOCSETDUMPLIMITS 9034		///< IOCTL code: Set the dump file limits. See the PacketSetDumpLimits() function.
+#define  pBIOCISDUMPENDED 7411			///< IOCTL code: Get the status of the kernel dump process. See the PacketIsDumpEnded() function.
 
-#define  pBIOCSTIMEZONE 7471
+#define  pBIOCSTIMEZONE 7471			///< IOCTL code: set time zone. Used in Win9x only.
 
-// Alignment macros.  Packet_WORDALIGN rounds up to the next 
+
-// even multiple of Packet_ALIGNMENT. 
+/// Alignment macro. Defines the alignment size.
 #define Packet_ALIGNMENT sizeof(int)
+/// Alignment macro. Rounds up to the next even multiple of Packet_ALIGNMENT. 
 #define Packet_WORDALIGN(x) (((x)+(Packet_ALIGNMENT-1))&~(Packet_ALIGNMENT-1))
 
+/*!
+  \brief Network type structure.
+
+  This structure is used by the PacketGetNetType() function to return information on the current adapter's type and speed.
+*/
 typedef struct NetType
 {
-	UINT LinkType;	
+	UINT LinkType;	///< The MAC of the current network adapter (see function PacketGetNetType() for more information)
-	UINT LinkSpeed;
+	UINT LinkSpeed;	///< The speed of the network in bits per second
 }NetType;
 
 
@@ -74,75 +95,160 @@ typedef struct NetType
 
 #ifndef BPF_MAJOR_VERSION
 
+/*!
+  \brief A BPF pseudo-assembly program.
+
+  The program will be injected in the kernel by the PacketSetBPF() function and applied to every incoming packet. 
+*/
 struct bpf_program {
-	UINT bf_len;				
+	UINT bf_len;				///< Indicates the number of instructions of the program, i.e. the number of struct bpf_insn that will follow.
-	struct bpf_insn *bf_insns;	
+	struct bpf_insn *bf_insns;	///< A pointer to the first instruction of the program.
 };
 
+/*!
+  \brief A single BPF pseudo-instruction.
+
+  bpf_insn contains a single instruction for the BPF register-machine. It is used to send a filter program to the driver.
+*/
 struct bpf_insn {
-	USHORT	code;		
+	USHORT	code;		///< Instruction type and addressing mode.
-	UCHAR 	jt;			
+	UCHAR 	jt;			///< Jump if true
-	UCHAR 	jf;			
+	UCHAR 	jf;			///< Jump if false
-	int k;				
+	int k;				///< Generic field used for various purposes.
 };
 
+/*!
+  \brief Structure that contains a couple of statistics values on the current capture.
+
+  It is used by packet.dll to return statistics about a capture session.
+*/
 struct bpf_stat {
-	UINT bs_recv;		
+	UINT bs_recv;		///< Number of packets that the driver received from the network adapter 
+						///< from the beginning of the current capture. This value includes the packets 
+						///< lost by the driver.
+	UINT bs_drop;		///< number of packets that the driver lost from the beginning of a capture. 
+						///< Basically, a packet is lost when the the buffer of the driver is full. 
+						///< In this situation the packet cannot be stored and the driver rejects it.
+	UINT ps_ifdrop;		///< drops by interface. XXX not yet supported
+	UINT bs_capt;		///< number of packets that pass the filter, find place in the kernel buffer and
+						///< thus reach the application.
+};
 						
+/*!
+  \brief Packet header.
 						
-	UINT bs_drop;		
+  This structure defines the header associated with every packet delivered to the application.
+*/
+struct bpf_hdr {
+	struct timeval	bh_tstamp;	///< The timestamp associated with the captured packet. 
+								///< It is stored in a TimeVal structure.
+	UINT	bh_caplen;			///< Length of captured portion. The captured portion <b>can be different</b>
+								///< from the original packet, because it is possible (with a proper filter)
+								///< to instruct the driver to capture only a portion of the packets.
+	UINT	bh_datalen;			///< Original length of packet
+	USHORT		bh_hdrlen;		///< Length of bpf header (this struct plus alignment padding). In some cases,
+								///< a padding could be added between the end of this structure and the packet
+								///< data for performance reasons. This filed can be used to retrieve the actual data 
+								///< of the packet.
+};
 						
+/*!
+  \brief Dump packet header.
 						
+  This structure defines the header associated with the packets in a buffer to be used with PacketSendPackets().
+  It is simpler than the bpf_hdr, because it corresponds to the header associated by WinPcap and libpcap to a
+  packet in a dump file. This makes straightforward sending WinPcap dump files to the network.
+*/
+struct dump_bpf_hdr{
+    struct timeval	ts;			///< Time stamp of the packet
+    UINT			caplen;		///< Length of captured portion. The captured portion can smaller than the 
+								///< the original packet, because it is possible (with a proper filter) to 
+								///< instruct the driver to capture only a portion of the packets. 
+    UINT			len;		///< Length of the original packet (off wire).
 };
 
-struct bpf_hdr {
-	struct timeval	bh_tstamp;	
-	UINT	bh_caplen;			
-	UINT	bh_datalen;			
-	USHORT		bh_hdrlen;										
-};
 
 #endif
 
-#define        DOSNAMEPREFIX   TEXT("Packet_")
+#define        DOSNAMEPREFIX   TEXT("Packet_")	///< Prefix added to the adapters device names to create the WinPcap devices
-#define        MAX_LINK_NAME_LENGTH   64
+#define        MAX_LINK_NAME_LENGTH	64			//< Maximum length of the devices symbolic links
 #define        NMAX_PACKET 65535  
 
+/*!
+  \brief Describes a network adapter.
+
+  This structure is the most important for the functioning of packet.dll, but the great part of its fields
+  should be ignored by the user, since the library offers functions that avoid to cope with low-level parameters
+*/
 typedef struct _ADAPTER  { 
-	HANDLE hFile;				
+	HANDLE hFile;				///< \internal Handle to an open instance of the NPF driver.
-	TCHAR  SymbolicLink[MAX_LINK_NAME_LENGTH]; 
+	CHAR  SymbolicLink[MAX_LINK_NAME_LENGTH]; ///< \internal A string containing the name of the network adapter currently opened.
-	int NumWrites;				
+	int NumWrites;				///< \internal Number of times a packets written on this adapter will be repeated 
-	HANDLE ReadEvent;			
+								///< on the wire.
-	UINT ReadTimeOut;			
+	HANDLE ReadEvent;			///< A notification event associated with the read calls on the adapter.
+								///< It can be passed to standard Win32 functions (like WaitForSingleObject
+								///< or WaitForMultipleObjects) to wait until the driver's buffer contains some 
+								///< data. It is particularly useful in GUI applications that need to wait 
+								///< concurrently on several events. In Windows NT/2000 the PacketSetMinToCopy()
+								///< function can be used to define the minimum amount of data in the kernel buffer
+								///< that will cause the event to be signalled. 
+	
+	UINT ReadTimeOut;			///< \internal The amount of time after which a read on the driver will be released and 
+								///< ReadEvent will be signaled, also if no packets were captured
 }  ADAPTER, *LPADAPTER;
 
+/*!
+  \brief Structure that contains a group of packets coming from the driver.
+
+  This structure defines the header associated with every packet delivered to the application.
+*/
 typedef struct _PACKET {  
-	HANDLE       hEvent;		
+	HANDLE       hEvent;		///< \deprecated Still present for compatibility with old applications.
-	OVERLAPPED   OverLapped;	
+	OVERLAPPED   OverLapped;	///< \deprecated Still present for compatibility with old applications.
-	PVOID        Buffer;										
+	PVOID        Buffer;		///< Buffer with containing the packets. See the PacketReceivePacket() for
-	UINT         Length;		
+								///< details about the organization of the data in this buffer
-	UINT         ulBytesReceived;										
+	UINT         Length;		///< Length of the buffer
-	BOOLEAN      bIoComplete;	
+	DWORD        ulBytesReceived;	///< Number of valid bytes present in the buffer, i.e. amount of data
+									///< received by the last call to PacketReceivePacket()
+	BOOLEAN      bIoComplete;	///< \deprecated Still present for compatibility with old applications.
 }  PACKET, *LPPACKET;
 
-struct _PACKET_OID_DATA {
+/*!
-    ULONG Oid;					
+  \brief Structure containing an OID request.
-    ULONG Length;				
-    UCHAR Data[1];				
 								
+  It is used by the PacketRequest() function to send an OID to the interface card driver. 
+  It can be used, for example, to retrieve the status of the error counters on the adapter, its MAC address, 
+  the list of the multicast groups defined on it, and so on.
+*/
+struct _PACKET_OID_DATA {
+    ULONG Oid;					///< OID code. See the Microsoft DDK documentation or the file ntddndis.h
+								///< for a complete list of valid codes.
+    ULONG Length;				///< Length of the data field
+    UCHAR Data[1];				///< variable-lenght field that contains the information passed to or received 
+								///< from the adapter.
 }; 
 typedef struct _PACKET_OID_DATA PACKET_OID_DATA, *PPACKET_OID_DATA;
 
+/*!
+  \brief Addresses of a network adapter.
+
+  This structure is used by the PacketGetNetInfoEx() function to return the IP addresses associated with 
+  an adapter.
+*/
 typedef struct npf_if_addr {
-	struct sockaddr IPAddress;	
+	struct sockaddr IPAddress;	///< IP address.
-	struct sockaddr SubnetMask;	
+	struct sockaddr SubnetMask;	///< Netmask for that address.
-	struct sockaddr Broadcast;	
+	struct sockaddr Broadcast;	///< Broadcast address.
 }npf_if_addr;
 
 #ifdef __cplusplus
 extern "C" {
 #endif
 
+/**
+ *  @}
+ */
+
 //---------------------------------------------------------------------------
 // FUNCTIONS
 //---------------------------------------------------------------------------
@@ -154,10 +260,12 @@ BOOLEAN PacketSetMode(LPADAPTER AdapterObject,int mode);
 BOOLEAN PacketSetReadTimeout(LPADAPTER AdapterObject,int timeout);
 BOOLEAN PacketSetBpf(LPADAPTER AdapterObject,struct bpf_program *fp);
 BOOLEAN PacketGetStats(LPADAPTER AdapterObject,struct bpf_stat *s);
+BOOLEAN PacketGetStatsEx(LPADAPTER AdapterObject,struct bpf_stat *s);
 BOOLEAN PacketSetBuff(LPADAPTER AdapterObject,int dim);
 BOOLEAN PacketGetNetType (LPADAPTER AdapterObject,NetType *type);
 LPADAPTER PacketOpenAdapter(LPTSTR AdapterName);
 BOOLEAN PacketSendPacket(LPADAPTER AdapterObject,LPPACKET pPacket,BOOLEAN Sync);
+INT PacketSendPackets(LPADAPTER AdapterObject,PVOID PacketBuff,ULONG Size, BOOLEAN Sync);
 LPPACKET PacketAllocatePacket(void);
 VOID PacketInitPacket(LPPACKET lpPacket,PVOID  Buffer,UINT  Length);
 VOID PacketFreePacket(LPPACKET lpPacket);
@@ -169,6 +277,8 @@ BOOLEAN PacketGetNetInfoEx(LPTSTR AdapterName, npf_if_addr* buffer, PLONG NEntri
 BOOLEAN PacketRequest(LPADAPTER  AdapterObject,BOOLEAN Set,PPACKET_OID_DATA  OidData);
 HANDLE PacketGetReadEvent(LPADAPTER AdapterObject);
 BOOLEAN PacketSetDumpName(LPADAPTER AdapterObject, void *name, int len);
+BOOLEAN PacketSetDumpLimits(LPADAPTER AdapterObject, UINT maxfilesize, UINT maxnpacks);
+BOOLEAN PacketIsDumpEnded(LPADAPTER AdapterObject, BOOLEAN sync);
 BOOL PacketStopDriver();
 VOID PacketCloseAdapter(LPADAPTER lpAdapter);
 

reactos/lib/packet/makefile

@@ -1,4 +1,4 @@
-# $Id: makefile,v 1.2 2002/08/17 15:58:38 robd Exp $
+# $Id: makefile,v 1.3 2002/09/24 15:08:14 robd Exp $
 
 PATH_TO_TOP = ../..
 
@@ -8,12 +8,13 @@ TARGET_NAME = packet
 
 TARGET_BASE = 0x77780000
 
-TARGET_CFLAGS = -I./include -DUNICODE -DLE -DDBG
+TARGET_CFLAGS = -I./include -DUNICODE -D_UNICODE -DLE -DDBG -D_DEBUG
 
 TARGET_SDKLIBS = ntdll.a kernel32.a advapi32.a
 
 TARGET_OBJECTS = \
-    Packet32.o
+	Packet32.o \
+	trace.o
 
 TARGET_CLEAN = $(TARGET_OBJECTS)
 

reactos/lib/packet/packet.def

@@ -3,27 +3,32 @@ LIBRARY packet
 DESCRIPTION 'Packet driver dll'
 
 EXPORTS
-PacketLibraryVersion
+		PacketLibraryVersion
-PacketGetVersion
+		PacketGetVersion
-PacketOpenAdapter
+		PacketOpenAdapter
-PacketSendPacket
+		PacketSendPacket
-PacketAllocatePacket
+		PacketSendPackets
-PacketInitPacket
+		PacketAllocatePacket
-PacketFreePacket
+		PacketInitPacket
-PacketReceivePacket
+		PacketFreePacket
-PacketCloseAdapter
+		PacketReceivePacket
-PacketSetHwFilter
+		PacketCloseAdapter
-PacketGetAdapterNames
+		PacketSetHwFilter
-PacketRequest
+		PacketGetAdapterNames
-PacketSetBuff
+		PacketRequest
-PacketSetBpf
+		PacketSetBuff
-PacketGetStats
+		PacketSetBpf
-PacketGetNetType
+		PacketGetStats
-PacketSetReadTimeout
+		PacketGetStatsEx
-PacketSetMode
+		PacketGetNetType
-PacketSetNumWrites
+		PacketSetReadTimeout
-PacketGetNetInfo
+		PacketSetMode
-PacketGetNetInfoEx
+		PacketSetNumWrites
-PacketSetMinToCopy
+		PacketGetNetInfo
-PacketGetReadEvent
+		PacketGetNetInfoEx
-PacketStopDriver
+		PacketSetMinToCopy
+		PacketGetReadEvent
+		PacketStopDriver
+		PacketSetDumpName
+		PacketSetDumpLimits
+		PacketIsDumpEnded

reactos/lib/packet/trace.c

@@ -0,0 +1,53 @@
+/////////////////////////////////////////////////////////////////////////////
+// Diagnostic Trace
+//
+#include <stdio.h> 
+#include <stdarg.h>
+#include <windows.h>
+//#include <tchar.h>
+#include "trace.h"
+
+#ifdef _DEBUG
+
+#undef THIS_FILE
+static char THIS_FILE[] = __FILE__;
+
+void _DebugBreak(void)
+{
+    DebugBreak();
+}
+
+//void Trace(TCHAR* lpszFormat, ...)
+void Trace(char* lpszFormat, ...)
+{
+    va_list args;
+    int nBuf;
+    char szBuffer[512];
+
+    va_start(args, lpszFormat);
+    nBuf = _vsnprintf(szBuffer, sizeof(szBuffer)/sizeof(TCHAR), lpszFormat, args);
+    OutputDebugStringA(szBuffer);
+    // was there an error? was the expanded string too long?
+    //ASSERT(nBuf >= 0);
+    va_end(args);
+}
+
+void Assert(void* assert, const char* file, int line, void* msg)
+{
+    if (msg == NULL) {
+        printf("ASSERT -- %s occured on line %u of file %s.\n",
+               assert, line, file);
+    } else {
+        printf("ASSERT -- %s occured on line %u of file %s: Message = %s.\n",
+               assert, line, file, msg);
+    }
+}
+
+#else
+
+//void Trace(TCHAR* lpszFormat, ...) { };
+void Trace(char* lpszFormat, ...) { };
+void Assert(void* assert, const char* file, int line, void* msg) { };
+
+#endif //_DEBUG
+/////////////////////////////////////////////////////////////////////////////

reactos/lib/packet/trace.h

@@ -0,0 +1,62 @@
+/////////////////////////////////////////////////////////////////////////////
+// Diagnostic Trace
+//
+#ifndef __TRACE_H__
+#define __TRACE_H__
+
+#ifdef _DEBUG
+
+#ifdef _X86_
+#define BreakPoint()        _asm { int 3h }
+#else
+#define BreakPoint()        _DebugBreak()
+#endif
+
+#ifndef ASSERT
+#define ASSERT(exp)                                 \
+{                                                   \
+    if (!(exp)) {                                   \
+        Assert(#exp, __FILE__, __LINE__, NULL);     \
+        BreakPoint();                               \
+    }                                               \
+}                                                   \
+
+#define ASSERTMSG(exp, msg)                         \
+{                                                   \
+    if (!(exp)) {                                   \
+        Assert(#exp, __FILE__, __LINE__, msg);      \
+        BreakPoint();                               \
+    }                                               \
+}
+#endif
+
+//=============================================================================
+//  MACRO: TRACE()
+//=============================================================================
+
+#define TRACE  Trace
+
+
+#else   // _DEBUG
+
+//=============================================================================
+//  Define away MACRO's ASSERT() and TRACE() in non debug builds
+//=============================================================================
+
+#ifndef ASSERT
+#define ASSERT(exp)
+#define ASSERTMSG(exp, msg)
+#endif
+
+#define TRACE 0 ? (void)0 : Trace
+
+#endif // !_DEBUG
+
+
+void Assert(void* assert, const char* file, int line, void* msg);
+//void Trace(TCHAR* lpszFormat, ...);
+void Trace(char* lpszFormat, ...);
+
+
+#endif // __TRACE_H__
+/////////////////////////////////////////////////////////////////////////////