2 * Copyright (c) 1999 - 2005 NetGroup, Politecnico di Torino (Italy)
3 * Copyright (c) 2005 - 2006 CACE Technologies, Davis (California)
6 * Redistribution and use in source and binary forms, with or without
7 * modification, are permitted provided that the following conditions
10 * 1. Redistributions of source code must retain the above copyright
11 * notice, this list of conditions and the following disclaimer.
12 * 2. Redistributions in binary form must reproduce the above copyright
13 * notice, this list of conditions and the following disclaimer in the
14 * documentation and/or other materials provided with the distribution.
15 * 3. Neither the name of the Politecnico di Torino, CACE Technologies
16 * nor the names of its contributors may be used to endorse or promote
17 * products derived from this software without specific prior written
20 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
21 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
22 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
23 * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
24 * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
25 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
26 * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
27 * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
28 * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
29 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
30 * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
34 /** @ingroup packetapi
38 /** @defgroup packet32h Packet.dll definitions and data structures
39 * Packet32.h contains the data structures and the definitions used by packet.dll.
40 * The file is used both by the Win9x and the WinNTx versions of packet.dll, and can be included
41 * by the applications that use the functions of this library
52 #ifdef HAVE_AIRPCAP_API
55 #if !defined(AIRPCAP_HANDLE__EAE405F5_0171_9592_B3C2_C19EC426AD34__DEFINED_)
56 #define AIRPCAP_HANDLE__EAE405F5_0171_9592_B3C2_C19EC426AD34__DEFINED_
57 typedef struct _AirpcapHandle *PAirpcapHandle;
58 #endif /* AIRPCAP_HANDLE__EAE405F5_0171_9592_B3C2_C19EC426AD34__DEFINED_ */
59 #endif /* HAVE_AIRPCAP_API */
63 #endif /* HAVE_DAG_API */
66 #define PACKET_MODE_CAPT 0x0 ///< Capture mode
67 #define PACKET_MODE_STAT 0x1 ///< Statistical mode
68 #define PACKET_MODE_MON 0x2 ///< Monitoring mode
69 #define PACKET_MODE_DUMP 0x10 ///< Dump mode
70 #define PACKET_MODE_STAT_DUMP MODE_DUMP | MODE_STAT ///< Statistical dump Mode
73 #define FILE_DEVICE_PROTOCOL 0x8000
75 #define IOCTL_PROTOCOL_STATISTICS CTL_CODE(FILE_DEVICE_PROTOCOL, 2 , METHOD_BUFFERED, FILE_ANY_ACCESS)
76 #define IOCTL_PROTOCOL_RESET CTL_CODE(FILE_DEVICE_PROTOCOL, 3 , METHOD_BUFFERED, FILE_ANY_ACCESS)
77 #define IOCTL_PROTOCOL_READ CTL_CODE(FILE_DEVICE_PROTOCOL, 4 , METHOD_BUFFERED, FILE_ANY_ACCESS)
78 #define IOCTL_PROTOCOL_WRITE CTL_CODE(FILE_DEVICE_PROTOCOL, 5 , METHOD_BUFFERED, FILE_ANY_ACCESS)
79 #define IOCTL_PROTOCOL_MACNAME CTL_CODE(FILE_DEVICE_PROTOCOL, 6 , METHOD_BUFFERED, FILE_ANY_ACCESS)
80 #define IOCTL_OPEN CTL_CODE(FILE_DEVICE_PROTOCOL, 7 , METHOD_BUFFERED, FILE_ANY_ACCESS)
81 #define IOCTL_CLOSE CTL_CODE(FILE_DEVICE_PROTOCOL, 8 , METHOD_BUFFERED, FILE_ANY_ACCESS)
83 #define pBIOCSETBUFFERSIZE 9592 ///< IOCTL code: set kernel buffer size.
84 #define pBIOCSETF 9030 ///< IOCTL code: set packet filtering program.
85 #define pBIOCGSTATS 9031 ///< IOCTL code: get the capture stats.
86 #define pBIOCSRTIMEOUT 7416 ///< IOCTL code: set the read timeout.
87 #define pBIOCSMODE 7412 ///< IOCTL code: set working mode.
88 #define pBIOCSWRITEREP 7413 ///< IOCTL code: set number of physical repetions of every packet written by the app.
89 #define pBIOCSMINTOCOPY 7414 ///< IOCTL code: set minimum amount of data in the kernel buffer that unlocks a read call.
90 #define pBIOCSETOID 2147483648U ///< IOCTL code: set an OID value.
91 #define pBIOCQUERYOID 2147483652U ///< IOCTL code: get an OID value.
92 #define pATTACHPROCESS 7117 ///< IOCTL code: attach a process to the driver. Used in Win9x only.
93 #define pDETACHPROCESS 7118 ///< IOCTL code: detach a process from the driver. Used in Win9x only.
94 #define pBIOCSETDUMPFILENAME 9029 ///< IOCTL code: set the name of a the file used by kernel dump mode.
95 #define pBIOCEVNAME 7415 ///< IOCTL code: get the name of the event that the driver signals when some data is present in the buffer.
96 #define pBIOCSENDPACKETSNOSYNC 9032 ///< IOCTL code: Send a buffer containing multiple packets to the network, ignoring the timestamps associated with the packets.
97 #define pBIOCSENDPACKETSSYNC 9033 ///< IOCTL code: Send a buffer containing multiple packets to the network, respecting the timestamps associated with the packets.
98 #define pBIOCSETDUMPLIMITS 9034 ///< IOCTL code: Set the dump file limits. See the PacketSetDumpLimits() function.
99 #define pBIOCISDUMPENDED 7411 ///< IOCTL code: Get the status of the kernel dump process. See the PacketIsDumpEnded() function.
100 #define pBIOCISETLOBBEH 7410 ///< IOCTL code: Set the loopback behavior of the driver with packets sent by itself: capture or drop.
101 #define pBIOCSETEVENTHANDLE 7920 ///< IOCTL code: Passes the read event HANDLE allocated by the user (packet.dll) to the kernel level driver.
103 #define pBIOCSTIMEZONE 7471 ///< IOCTL code: set time zone. Used in Win9x only.
106 /// Alignment macro. Defines the alignment size.
107 #define Packet_ALIGNMENT sizeof(int)
108 /// Alignment macro. Rounds up to the next even multiple of Packet_ALIGNMENT.
109 #define Packet_WORDALIGN(x) (((x)+(Packet_ALIGNMENT-1))&~(Packet_ALIGNMENT-1))
111 #define NdisMediumNull -1 ///< Custom linktype: NDIS doesn't provide an equivalent
112 #define NdisMediumCHDLC -2 ///< Custom linktype: NDIS doesn't provide an equivalent
113 #define NdisMediumPPPSerial -3 ///< Custom linktype: NDIS doesn't provide an equivalent
114 #define NdisMediumBare80211 -4 ///< Custom linktype: NDIS doesn't provide an equivalent
115 #define NdisMediumRadio80211 -5 ///< Custom linktype: NDIS doesn't provide an equivalent
117 // Loopback behaviour definitions
118 #define NPF_DISABLE_LOOPBACK 1 ///< Drop the packets sent by the NPF driver
119 #define NPF_ENABLE_LOOPBACK 2 ///< Capture the packets sent by the NPF driver
122 \brief Network type structure.
124 This structure is used by the PacketGetNetType() function to return information on the current adapter's type and speed.
126 typedef struct NetType
128 UINT LinkType; ///< The MAC of the current network adapter (see function PacketGetNetType() for more information)
129 ULONGLONG LinkSpeed; ///< The speed of the network in bits per second
133 //some definitions stolen from libpcap
135 #ifndef BPF_MAJOR_VERSION
138 \brief A BPF pseudo-assembly program.
140 The program will be injected in the kernel by the PacketSetBPF() function and applied to every incoming packet.
144 UINT bf_len; ///< Indicates the number of instructions of the program, i.e. the number of struct bpf_insn that will follow.
145 struct bpf_insn *bf_insns; ///< A pointer to the first instruction of the program.
149 \brief A single BPF pseudo-instruction.
151 bpf_insn contains a single instruction for the BPF register-machine. It is used to send a filter program to the driver.
155 USHORT code; ///< Instruction type and addressing mode.
156 UCHAR jt; ///< Jump if true
157 UCHAR jf; ///< Jump if false
158 int k; ///< Generic field used for various purposes.
162 \brief Structure that contains a couple of statistics values on the current capture.
164 It is used by packet.dll to return statistics about a capture session.
168 UINT bs_recv; ///< Number of packets that the driver received from the network adapter
169 ///< from the beginning of the current capture. This value includes the packets
170 ///< lost by the driver.
171 UINT bs_drop; ///< number of packets that the driver lost from the beginning of a capture.
172 ///< Basically, a packet is lost when the the buffer of the driver is full.
173 ///< In this situation the packet cannot be stored and the driver rejects it.
174 UINT ps_ifdrop; ///< drops by interface. XXX not yet supported
175 UINT bs_capt; ///< number of packets that pass the filter, find place in the kernel buffer and
176 ///< thus reach the application.
180 \brief Packet header.
182 This structure defines the header associated with every packet delivered to the application.
186 struct timeval bh_tstamp; ///< The timestamp associated with the captured packet.
187 ///< It is stored in a TimeVal structure.
188 UINT bh_caplen; ///< Length of captured portion. The captured portion <b>can be different</b>
189 ///< from the original packet, because it is possible (with a proper filter)
190 ///< to instruct the driver to capture only a portion of the packets.
191 UINT bh_datalen; ///< Original length of packet
192 USHORT bh_hdrlen; ///< Length of bpf header (this struct plus alignment padding). In some cases,
193 ///< a padding could be added between the end of this structure and the packet
194 ///< data for performance reasons. This filed can be used to retrieve the actual data
199 \brief Dump packet header.
201 This structure defines the header associated with the packets in a buffer to be used with PacketSendPackets().
202 It is simpler than the bpf_hdr, because it corresponds to the header associated by WinPcap and libpcap to a
203 packet in a dump file. This makes straightforward sending WinPcap dump files to the network.
206 struct timeval ts; ///< Time stamp of the packet
207 UINT caplen; ///< Length of captured portion. The captured portion can smaller than the
208 ///< the original packet, because it is possible (with a proper filter) to
209 ///< instruct the driver to capture only a portion of the packets.
210 UINT len; ///< Length of the original packet (off wire).
218 #define DOSNAMEPREFIX TEXT("Packet_") ///< Prefix added to the adapters device names to create the WinPcap devices
219 #define MAX_LINK_NAME_LENGTH 64 //< Maximum length of the devices symbolic links
220 #define NMAX_PACKET 65535
223 \brief Addresses of a network adapter.
225 This structure is used by the PacketGetNetInfoEx() function to return the IP addresses associated with
228 typedef struct npf_if_addr {
229 struct sockaddr_storage IPAddress; ///< IP address.
230 struct sockaddr_storage SubnetMask; ///< Netmask for that address.
231 struct sockaddr_storage Broadcast; ///< Broadcast address.
235 #define ADAPTER_NAME_LENGTH 256 + 12 ///< Maximum length for the name of an adapter. The value is the same used by the IP Helper API.
236 #define ADAPTER_DESC_LENGTH 128 ///< Maximum length for the description of an adapter. The value is the same used by the IP Helper API.
237 #define MAX_MAC_ADDR_LENGTH 8 ///< Maximum length for the link layer address of an adapter. The value is the same used by the IP Helper API.
238 #define MAX_NETWORK_ADDRESSES 16 ///< Maximum length for the link layer address of an adapter. The value is the same used by the IP Helper API.
241 typedef struct WAN_ADAPTER_INT WAN_ADAPTER; ///< Describes an opened wan (dialup, VPN...) network adapter using the NetMon API
242 typedef WAN_ADAPTER *PWAN_ADAPTER; ///< Describes an opened wan (dialup, VPN...) network adapter using the NetMon API
244 #define INFO_FLAG_NDIS_ADAPTER 0 ///< Flag for ADAPTER_INFO: this is a traditional ndis adapter
245 #define INFO_FLAG_NDISWAN_ADAPTER 1 ///< Flag for ADAPTER_INFO: this is a NdisWan adapter, and it's managed by WANPACKET
246 #define INFO_FLAG_DAG_CARD 2 ///< Flag for ADAPTER_INFO: this is a DAG card
247 #define INFO_FLAG_DAG_FILE 6 ///< Flag for ADAPTER_INFO: this is a DAG file
248 #define INFO_FLAG_DONT_EXPORT 8 ///< Flag for ADAPTER_INFO: when this flag is set, the adapter will not be listed or openend by winpcap. This allows to prevent exporting broken network adapters, like for example FireWire ones.
249 #define INFO_FLAG_AIRPCAP_CARD 16 ///< Flag for ADAPTER_INFO: this is an airpcap card
250 #define INFO_FLAG_NPFIM_DEVICE 32
252 \brief Contains comprehensive information about a network adapter.
254 This structure is filled with all the accessory information that the user can need about an adapter installed
257 typedef struct _ADAPTER_INFO
259 struct _ADAPTER_INFO *Next; ///< Pointer to the next adapter in the list.
260 CHAR Name[ADAPTER_NAME_LENGTH + 1]; ///< Name of the device representing the adapter.
261 CHAR Description[ADAPTER_DESC_LENGTH + 1]; ///< Human understandable description of the adapter
262 UINT MacAddressLen; ///< Length of the link layer address.
263 UCHAR MacAddress[MAX_MAC_ADDR_LENGTH]; ///< Link layer address.
264 NetType LinkLayer; ///< Physical characteristics of this adapter. This NetType structure contains the link type and the speed of the adapter.
265 INT NNetworkAddresses; ///< Number of network layer addresses of this adapter.
266 npf_if_addr *NetworkAddresses; ///< Pointer to an array of npf_if_addr, each of which specifies a network address of this adapter.
267 UINT Flags; ///< Adapter's flags. Tell if this adapter must be treated in a different way, using the Netmon API or the dagc API.
269 ADAPTER_INFO, *PADAPTER_INFO;
272 \brief Describes an opened network adapter.
274 This structure is the most important for the functioning of packet.dll, but the great part of its fields
275 should be ignored by the user, since the library offers functions that avoid to cope with low-level parameters
277 typedef struct _ADAPTER {
278 HANDLE hFile; ///< \internal Handle to an open instance of the NPF driver.
279 CHAR SymbolicLink[MAX_LINK_NAME_LENGTH]; ///< \internal A string containing the name of the network adapter currently opened.
280 int NumWrites; ///< \internal Number of times a packets written on this adapter will be repeated
282 HANDLE ReadEvent; ///< A notification event associated with the read calls on the adapter.
283 ///< It can be passed to standard Win32 functions (like WaitForSingleObject
284 ///< or WaitForMultipleObjects) to wait until the driver's buffer contains some
285 ///< data. It is particularly useful in GUI applications that need to wait
286 ///< concurrently on several events. In Windows NT/2000 the PacketSetMinToCopy()
287 ///< function can be used to define the minimum amount of data in the kernel buffer
288 ///< that will cause the event to be signalled.
290 UINT ReadTimeOut; ///< \internal The amount of time after which a read on the driver will be released and
291 ///< ReadEvent will be signaled, also if no packets were captured
292 CHAR Name[ADAPTER_NAME_LENGTH];
293 PWAN_ADAPTER pWanAdapter;
294 UINT Flags; ///< Adapter's flags. Tell if this adapter must be treated in a different way, using the Netmon API or the dagc API.
296 #ifdef HAVE_AIRPCAP_API
297 PAirpcapHandle AirpcapAd;
298 #endif // HAVE_AIRPCAP_API
300 #ifdef HAVE_NPFIM_API
302 #endif // HAVE_NPFIM_API
305 dagc_t *pDagCard; ///< Pointer to the dagc API adapter descriptor for this adapter
306 PCHAR DagBuffer; ///< Pointer to the buffer with the packets that is received from the DAG card
307 struct timeval DagReadTimeout; ///< Read timeout. The dagc API requires a timeval structure
308 unsigned DagFcsLen; ///< Length of the frame check sequence attached to any packet by the card. Obtained from the registry
309 DWORD DagFastProcess; ///< True if the user requests fast capture processing on this card. Higher level applications can use this value to provide a faster but possibly unprecise capture (for example, libpcap doesn't convert the timestamps).
310 #endif // HAVE_DAG_API
311 } ADAPTER, *LPADAPTER;
314 \brief Structure that contains a group of packets coming from the driver.
316 This structure defines the header associated with every packet delivered to the application.
318 typedef struct _PACKET {
319 HANDLE hEvent; ///< \deprecated Still present for compatibility with old applications.
320 OVERLAPPED OverLapped; ///< \deprecated Still present for compatibility with old applications.
321 PVOID Buffer; ///< Buffer with containing the packets. See the PacketReceivePacket() for
322 ///< details about the organization of the data in this buffer
323 UINT Length; ///< Length of the buffer
324 DWORD ulBytesReceived; ///< Number of valid bytes present in the buffer, i.e. amount of data
325 ///< received by the last call to PacketReceivePacket()
326 BOOLEAN bIoComplete; ///< \deprecated Still present for compatibility with old applications.
330 \brief Structure containing an OID request.
332 It is used by the PacketRequest() function to send an OID to the interface card driver.
333 It can be used, for example, to retrieve the status of the error counters on the adapter, its MAC address,
334 the list of the multicast groups defined on it, and so on.
336 struct _PACKET_OID_DATA {
337 ULONG Oid; ///< OID code. See the Microsoft DDK documentation or the file ntddndis.h
338 ///< for a complete list of valid codes.
339 ULONG Length; ///< Length of the data field
340 UCHAR Data[1]; ///< variable-lenght field that contains the information passed to or received
341 ///< from the adapter.
343 typedef struct _PACKET_OID_DATA PACKET_OID_DATA, *PPACKET_OID_DATA;
354 BOOLEAN QueryWinPcapRegistryStringA(CHAR *SubKeyName,
359 BOOLEAN QueryWinPcapRegistryStringW(WCHAR *SubKeyName,
365 //---------------------------------------------------------------------------
366 // EXPORTED FUNCTIONS
367 //---------------------------------------------------------------------------
369 PCHAR PacketGetVersion();
370 PCHAR PacketGetDriverVersion();
371 BOOLEAN PacketSetMinToCopy(LPADAPTER AdapterObject,int nbytes);
372 BOOLEAN PacketSetNumWrites(LPADAPTER AdapterObject,int nwrites);
373 BOOLEAN PacketSetMode(LPADAPTER AdapterObject,int mode);
374 BOOLEAN PacketSetReadTimeout(LPADAPTER AdapterObject,int timeout);
375 BOOLEAN PacketSetBpf(LPADAPTER AdapterObject,struct bpf_program *fp);
376 BOOLEAN PacketSetLoopbackBehavior(LPADAPTER AdapterObject, UINT LoopbackBehavior);
377 INT PacketSetSnapLen(LPADAPTER AdapterObject,int snaplen);
378 BOOLEAN PacketGetStats(LPADAPTER AdapterObject,struct bpf_stat *s);
379 BOOLEAN PacketGetStatsEx(LPADAPTER AdapterObject,struct bpf_stat *s);
380 BOOLEAN PacketSetBuff(LPADAPTER AdapterObject,int dim);
381 BOOLEAN PacketGetNetType (LPADAPTER AdapterObject,NetType *type);
382 LPADAPTER PacketOpenAdapter(PCHAR AdapterName);
383 BOOLEAN PacketSendPacket(LPADAPTER AdapterObject,LPPACKET pPacket,BOOLEAN Sync);
384 INT PacketSendPackets(LPADAPTER AdapterObject,PVOID PacketBuff,ULONG Size, BOOLEAN Sync);
385 LPPACKET PacketAllocatePacket(void);
386 VOID PacketInitPacket(LPPACKET lpPacket,PVOID Buffer,UINT Length);
387 VOID PacketFreePacket(LPPACKET lpPacket);
388 BOOLEAN PacketReceivePacket(LPADAPTER AdapterObject,LPPACKET lpPacket,BOOLEAN Sync);
389 BOOLEAN PacketSetHwFilter(LPADAPTER AdapterObject,ULONG Filter);
390 BOOLEAN PacketGetAdapterNames(PTSTR pStr,PULONG BufferSize);
391 BOOLEAN PacketGetNetInfoEx(PCHAR AdapterName, npf_if_addr* buffer, PLONG NEntries);
392 BOOLEAN PacketRequest(LPADAPTER AdapterObject,BOOLEAN Set,PPACKET_OID_DATA OidData);
393 HANDLE PacketGetReadEvent(LPADAPTER AdapterObject);
394 BOOLEAN PacketSetDumpName(LPADAPTER AdapterObject, void *name, int len);
395 BOOLEAN PacketSetDumpLimits(LPADAPTER AdapterObject, UINT maxfilesize, UINT maxnpacks);
396 BOOLEAN PacketIsDumpEnded(LPADAPTER AdapterObject, BOOLEAN sync);
397 BOOL PacketStopDriver();
398 VOID PacketCloseAdapter(LPADAPTER lpAdapter);
399 BOOLEAN PacketStartOem(PCHAR errorString, UINT errorStringLength);
400 PAirpcapHandle PacketGetAirPcapHandle(LPADAPTER AdapterObject);