2 * Copyright (c) 1999, 2000
3 * Politecnico di Torino. All rights reserved.
5 * Redistribution and use in source and binary forms, with or without
6 * modification, are permitted provided that: (1) source code distributions
7 * retain the above copyright notice and this paragraph in its entirety, (2)
8 * distributions including binary code include the above copyright notice and
9 * this paragraph in its entirety in the documentation or other materials
10 * provided with the distribution, and (3) all advertising materials mentioning
11 * features or use of this software display the following acknowledgement:
12 * ``This product includes software developed by the Politecnico
13 * di Torino, and its contributors.'' Neither the name of
14 * the University nor the names of its contributors may be used to endorse
15 * or promote products derived from this software without specific prior
17 * THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR IMPLIED
18 * WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
19 * MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
22 /** @ingroup packetapi
26 /** @defgroup packet32h Packet.dll definitions and data structures
27 * Packet32.h contains the data structures and the definitions used by packet.dll.
28 * The file is used both by the Win9x and the WinNTx versions of packet.dll, and can be included
29 * by the applications that use the functions of this library
40 #define PACKET_MODE_CAPT 0x0 ///< Capture mode
41 #define PACKET_MODE_STAT 0x1 ///< Statistical mode
42 #define PACKET_MODE_DUMP 0x10 ///< Dump mode
43 #define PACKET_MODE_STAT_DUMP MODE_DUMP | MODE_STAT ///< Statistical dump Mode
46 #define FILE_DEVICE_PROTOCOL 0x8000
48 #define IOCTL_PROTOCOL_STATISTICS CTL_CODE(FILE_DEVICE_PROTOCOL, 2 , METHOD_BUFFERED, FILE_ANY_ACCESS)
49 #define IOCTL_PROTOCOL_RESET CTL_CODE(FILE_DEVICE_PROTOCOL, 3 , METHOD_BUFFERED, FILE_ANY_ACCESS)
50 #define IOCTL_PROTOCOL_READ CTL_CODE(FILE_DEVICE_PROTOCOL, 4 , METHOD_BUFFERED, FILE_ANY_ACCESS)
51 #define IOCTL_PROTOCOL_WRITE CTL_CODE(FILE_DEVICE_PROTOCOL, 5 , METHOD_BUFFERED, FILE_ANY_ACCESS)
52 #define IOCTL_PROTOCOL_MACNAME CTL_CODE(FILE_DEVICE_PROTOCOL, 6 , METHOD_BUFFERED, FILE_ANY_ACCESS)
53 #define IOCTL_OPEN CTL_CODE(FILE_DEVICE_PROTOCOL, 7 , METHOD_BUFFERED, FILE_ANY_ACCESS)
54 #define IOCTL_CLOSE CTL_CODE(FILE_DEVICE_PROTOCOL, 8 , METHOD_BUFFERED, FILE_ANY_ACCESS)
56 #define pBIOCSETBUFFERSIZE 9592 ///< IOCTL code: set kernel buffer size.
57 #define pBIOCSETF 9030 ///< IOCTL code: set packet filtering program.
58 #define pBIOCGSTATS 9031 ///< IOCTL code: get the capture stats.
59 #define pBIOCSRTIMEOUT 7416 ///< IOCTL code: set the read timeout.
60 #define pBIOCSMODE 7412 ///< IOCTL code: set working mode.
61 #define pBIOCSWRITEREP 7413 ///< IOCTL code: set number of physical repetions of every packet written by the app.
62 #define pBIOCSMINTOCOPY 7414 ///< IOCTL code: set minimum amount of data in the kernel buffer that unlocks a read call.
63 #define pBIOCSETOID 2147483648 ///< IOCTL code: set an OID value.
64 #define pBIOCQUERYOID 2147483652 ///< IOCTL code: get an OID value.
65 #define pATTACHPROCESS 7117 ///< IOCTL code: attach a process to the driver. Used in Win9x only.
66 #define pDETACHPROCESS 7118 ///< IOCTL code: detach a process from the driver. Used in Win9x only.
67 #define pBIOCSETDUMPFILENAME 9029 ///< IOCTL code: set the name of a the file used by kernel dump mode.
68 #define pBIOCEVNAME 7415 ///< IOCTL code: get the name of the event that the driver signals when some data is present in the buffer.
69 #define pBIOCSENDPACKETSNOSYNC 9032 ///< IOCTL code: Send a buffer containing multiple packets to the network, ignoring the timestamps associated with the packets.
70 #define pBIOCSENDPACKETSSYNC 9033 ///< IOCTL code: Send a buffer containing multiple packets to the network, respecting the timestamps associated with the packets.
71 #define pBIOCSETDUMPLIMITS 9034 ///< IOCTL code: Set the dump file limits. See the PacketSetDumpLimits() function.
72 #define pBIOCISDUMPENDED 7411 ///< IOCTL code: Get the status of the kernel dump process. See the PacketIsDumpEnded() function.
74 #define pBIOCSTIMEZONE 7471 ///< IOCTL code: set time zone. Used in Win9x only.
77 /// Alignment macro. Defines the alignment size.
78 #define Packet_ALIGNMENT sizeof(int)
79 /// Alignment macro. Rounds up to the next even multiple of Packet_ALIGNMENT.
80 #define Packet_WORDALIGN(x) (((x)+(Packet_ALIGNMENT-1))&~(Packet_ALIGNMENT-1))
83 \brief Network type structure.
85 This structure is used by the PacketGetNetType() function to return information on the current adapter's type and speed.
87 typedef struct NetType
89 UINT LinkType; ///< The MAC of the current network adapter (see function PacketGetNetType() for more information)
90 UINT LinkSpeed; ///< The speed of the network in bits per second
94 //some definitions stolen from libpcap
96 #ifndef BPF_MAJOR_VERSION
99 \brief A BPF pseudo-assembly program.
101 The program will be injected in the kernel by the PacketSetBPF() function and applied to every incoming packet.
104 UINT bf_len; ///< Indicates the number of instructions of the program, i.e. the number of struct bpf_insn that will follow.
105 struct bpf_insn *bf_insns; ///< A pointer to the first instruction of the program.
109 \brief A single BPF pseudo-instruction.
111 bpf_insn contains a single instruction for the BPF register-machine. It is used to send a filter program to the driver.
114 USHORT code; ///< Instruction type and addressing mode.
115 UCHAR jt; ///< Jump if true
116 UCHAR jf; ///< Jump if false
117 int k; ///< Generic field used for various purposes.
121 \brief Structure that contains a couple of statistics values on the current capture.
123 It is used by packet.dll to return statistics about a capture session.
126 UINT bs_recv; ///< Number of packets that the driver received from the network adapter
127 ///< from the beginning of the current capture. This value includes the packets
128 ///< lost by the driver.
129 UINT bs_drop; ///< number of packets that the driver lost from the beginning of a capture.
130 ///< Basically, a packet is lost when the the buffer of the driver is full.
131 ///< In this situation the packet cannot be stored and the driver rejects it.
132 UINT ps_ifdrop; ///< drops by interface. XXX not yet supported
133 UINT bs_capt; ///< number of packets that pass the filter, find place in the kernel buffer and
134 ///< thus reach the application.
138 \brief Packet header.
140 This structure defines the header associated with every packet delivered to the application.
143 struct timeval bh_tstamp; ///< The timestamp associated with the captured packet.
144 ///< It is stored in a TimeVal structure.
145 UINT bh_caplen; ///< Length of captured portion. The captured portion <b>can be different</b>
146 ///< from the original packet, because it is possible (with a proper filter)
147 ///< to instruct the driver to capture only a portion of the packets.
148 UINT bh_datalen; ///< Original length of packet
149 USHORT bh_hdrlen; ///< Length of bpf header (this struct plus alignment padding). In some cases,
150 ///< a padding could be added between the end of this structure and the packet
151 ///< data for performance reasons. This filed can be used to retrieve the actual data
156 \brief Dump packet header.
158 This structure defines the header associated with the packets in a buffer to be used with PacketSendPackets().
159 It is simpler than the bpf_hdr, because it corresponds to the header associated by WinPcap and libpcap to a
160 packet in a dump file. This makes straightforward sending WinPcap dump files to the network.
163 struct timeval ts; ///< Time stamp of the packet
164 UINT caplen; ///< Length of captured portion. The captured portion can smaller than the
165 ///< the original packet, because it is possible (with a proper filter) to
166 ///< instruct the driver to capture only a portion of the packets.
167 UINT len; ///< Length of the original packet (off wire).
173 #define DOSNAMEPREFIX TEXT("Packet_") ///< Prefix added to the adapters device names to create the WinPcap devices
174 #define MAX_LINK_NAME_LENGTH 64 //< Maximum length of the devices symbolic links
175 #define NMAX_PACKET 65535
178 \brief Describes a network adapter.
180 This structure is the most important for the functioning of packet.dll, but the great part of its fields
181 should be ignored by the user, since the library offers functions that avoid to cope with low-level parameters
183 typedef struct _ADAPTER {
184 HANDLE hFile; ///< \internal Handle to an open instance of the NPF driver.
185 CHAR SymbolicLink[MAX_LINK_NAME_LENGTH]; ///< \internal A string containing the name of the network adapter currently opened.
186 int NumWrites; ///< \internal Number of times a packets written on this adapter will be repeated
188 HANDLE ReadEvent; ///< A notification event associated with the read calls on the adapter.
189 ///< It can be passed to standard Win32 functions (like WaitForSingleObject
190 ///< or WaitForMultipleObjects) to wait until the driver's buffer contains some
191 ///< data. It is particularly useful in GUI applications that need to wait
192 ///< concurrently on several events. In Windows NT/2000 the PacketSetMinToCopy()
193 ///< function can be used to define the minimum amount of data in the kernel buffer
194 ///< that will cause the event to be signalled.
196 UINT ReadTimeOut; ///< \internal The amount of time after which a read on the driver will be released and
197 ///< ReadEvent will be signaled, also if no packets were captured
198 } ADAPTER, *LPADAPTER;
201 \brief Structure that contains a group of packets coming from the driver.
203 This structure defines the header associated with every packet delivered to the application.
205 typedef struct _PACKET {
206 HANDLE hEvent; ///< \deprecated Still present for compatibility with old applications.
207 OVERLAPPED OverLapped; ///< \deprecated Still present for compatibility with old applications.
208 PVOID Buffer; ///< Buffer with containing the packets. See the PacketReceivePacket() for
209 ///< details about the organization of the data in this buffer
210 UINT Length; ///< Length of the buffer
211 DWORD ulBytesReceived; ///< Number of valid bytes present in the buffer, i.e. amount of data
212 ///< received by the last call to PacketReceivePacket()
213 BOOLEAN bIoComplete; ///< \deprecated Still present for compatibility with old applications.
217 \brief Structure containing an OID request.
219 It is used by the PacketRequest() function to send an OID to the interface card driver.
220 It can be used, for example, to retrieve the status of the error counters on the adapter, its MAC address,
221 the list of the multicast groups defined on it, and so on.
223 struct _PACKET_OID_DATA {
224 ULONG Oid; ///< OID code. See the Microsoft DDK documentation or the file ntddndis.h
225 ///< for a complete list of valid codes.
226 ULONG Length; ///< Length of the data field
227 UCHAR Data[1]; ///< variable-lenght field that contains the information passed to or received
228 ///< from the adapter.
230 typedef struct _PACKET_OID_DATA PACKET_OID_DATA, *PPACKET_OID_DATA;
233 \brief Addresses of a network adapter.
235 This structure is used by the PacketGetNetInfoEx() function to return the IP addresses associated with
238 typedef struct npf_if_addr {
239 struct sockaddr IPAddress; ///< IP address.
240 struct sockaddr SubnetMask; ///< Netmask for that address.
241 struct sockaddr Broadcast; ///< Broadcast address.
252 //---------------------------------------------------------------------------
254 //---------------------------------------------------------------------------
256 PCHAR PacketGetVersion();
257 BOOLEAN PacketSetMinToCopy(LPADAPTER AdapterObject,int nbytes);
258 BOOLEAN PacketSetNumWrites(LPADAPTER AdapterObject,int nwrites);
259 BOOLEAN PacketSetMode(LPADAPTER AdapterObject,int mode);
260 BOOLEAN PacketSetReadTimeout(LPADAPTER AdapterObject,int timeout);
261 BOOLEAN PacketSetBpf(LPADAPTER AdapterObject,struct bpf_program *fp);
262 BOOLEAN PacketGetStats(LPADAPTER AdapterObject,struct bpf_stat *s);
263 BOOLEAN PacketGetStatsEx(LPADAPTER AdapterObject,struct bpf_stat *s);
264 BOOLEAN PacketSetBuff(LPADAPTER AdapterObject,int dim);
265 BOOLEAN PacketGetNetType (LPADAPTER AdapterObject,NetType *type);
266 LPADAPTER PacketOpenAdapter(LPTSTR AdapterName);
267 BOOLEAN PacketSendPacket(LPADAPTER AdapterObject,LPPACKET pPacket,BOOLEAN Sync);
268 INT PacketSendPackets(LPADAPTER AdapterObject,PVOID PacketBuff,ULONG Size, BOOLEAN Sync);
269 LPPACKET PacketAllocatePacket(void);
270 VOID PacketInitPacket(LPPACKET lpPacket,PVOID Buffer,UINT Length);
271 VOID PacketFreePacket(LPPACKET lpPacket);
272 BOOLEAN PacketReceivePacket(LPADAPTER AdapterObject,LPPACKET lpPacket,BOOLEAN Sync);
273 BOOLEAN PacketSetHwFilter(LPADAPTER AdapterObject,ULONG Filter);
274 BOOLEAN PacketGetAdapterNames(PTSTR pStr,PULONG BufferSize);
275 BOOLEAN PacketGetNetInfo(LPTSTR AdapterName, PULONG netp, PULONG maskp);
276 BOOLEAN PacketGetNetInfoEx(LPTSTR AdapterName, npf_if_addr* buffer, PLONG NEntries);
277 BOOLEAN PacketRequest(LPADAPTER AdapterObject,BOOLEAN Set,PPACKET_OID_DATA OidData);
278 HANDLE PacketGetReadEvent(LPADAPTER AdapterObject);
279 BOOLEAN PacketSetDumpName(LPADAPTER AdapterObject, void *name, int len);
280 BOOLEAN PacketSetDumpLimits(LPADAPTER AdapterObject, UINT maxfilesize, UINT maxnpacks);
281 BOOLEAN PacketIsDumpEnded(LPADAPTER AdapterObject, BOOLEAN sync);
282 BOOL PacketStopDriver();
283 VOID PacketCloseAdapter(LPADAPTER lpAdapter);