Wireshark 4.5.0
The Wireshark network protocol analyzer
Loading...
Searching...
No Matches
airpcap.h
Go to the documentation of this file.
1
9#if !defined(AIRPCAP_H__EAE405F5_0171_9592_B3C2_C19EC426AD34__INCLUDED_)
10#define AIRPCAP_H__EAE405F5_0171_9592_B3C2_C19EC426AD34__INCLUDED_
11
12#ifdef _MSC_VER
13/* This stops VS2005 ranting against stdio. */
14#pragma warning( disable : 4996)
15#endif
16
17#ifdef _WIN32
18#include <winsock2.h>
19#endif
20
21#ifdef __cplusplus
22extern "C" {
23#endif
24
25/*
26 \mainpage AirPcap interface documentation
27
28 \section Introduction
29
30 This document describes the data structures and the functions exported by the CACE Technologies AirPcap library.
31 The AirPcap library provides low-level access to the AirPcap driver including advanced capabilities such as channel setting,
32 link type control and WEP configuration.<br>
33 This manual includes the following sections:
34
35 \note throughout this documentation, \e device refers to a physical USB AirPcap device, while \e adapter is an open API
36 instance. Most of the AirPcap API operations are adapter-specific but some of them, like setting the channel, are
37 per-device and will be reflected on all the open adapters. These functions will have "Device" in their name, e.g.
38 AirpcapSetDeviceChannel().
39
40 \b Sections:
41
42 - \ref airpcapfuncs
43 - \ref airpcapdefs
44 - \ref radiotap
45*/
46
55#define AIRPCAP_DEVICE_NAME_PREFIX "\\\\.\\airpcap"
56
61#define AIRPCAP_DEVICE_NUMBER_EXTRACT_STRING "\\\\.\\airpcap%u"
62
63#define AIRPCAP_DEVICE_ANY_EXTRACT_STRING "\\\\.\\airpcap_any"
64
69{
70 struct _AirpcapDeviceDescription *next; /* < Next element in the list */
71 char * Name; /* < Device name */
72 char * Description; /* < Device description */
74
75#define MAX_ENCRYPTION_KEYS 64
76
77#define WEP_KEY_MAX_SIZE 32 /* < Maximum size of a WEP key, in bytes. This is the size of an entry in the
78 < AirpcapWepKeysCollection structure. */
79
80#ifdef _WIN32
81#ifndef __MINGW32__
82#pragma pack(push)
83#pragma pack(1)
84#endif
85#endif
86
87#define AIRPCAP_KEYTYPE_WEP 0 /* < Key type: WEP. The key can have an arbitrary length smaller than 32 bytes. */
88#define AIRPCAP_KEYTYPE_TKIP 1 /* < Key type: TKIP (WPA). NOT SUPPORTED YET. */
89#define AIRPCAP_KEYTYPE_CCMP 2 /* < Key type: CCMP (WPA2). NOT SUPPORTED YET. */
90
94typedef struct _AirpcapKey
95{
96 unsigned KeyType; /* < Type of key, can be on of: \ref AIRPCAP_KEYTYPE_WEP, \ref AIRPCAP_KEYTYPE_TKIP, \ref AIRPCAP_KEYTYPE_CCMP. Only AIRPCAP_KEYTYPE_WEP is supported by the driver at the moment. */
97 unsigned KeyLen; /* < Length of the key, in bytes */
98 uint8_t KeyData[WEP_KEY_MAX_SIZE]; /* < Key Data */
99}
100#ifdef __MINGW32__
101__attribute__((__packed__))
102#endif
104
110typedef enum _AirpcapChannelBand
111{
112 AIRPCAP_CB_AUTO = 1, /* < Automatically pick the best frequency band */
113 AIRPCAP_CB_2_4_GHZ = 2, /* < 2.4 GHz frequency band */
114 AIRPCAP_CB_4_GHZ = 4, /* < 4 GHz frequency band */
115 AIRPCAP_CB_5_GHZ = 5 /* < 5 GHz frequency band */
116}AirpcapChannelBand, *PAirpcapChannelBand;
117
122typedef enum _AirpcapValidationType
123{
124 AIRPCAP_VT_ACCEPT_EVERYTHING = 1, /* < Accept all the frames the device captures */
125 AIRPCAP_VT_ACCEPT_CORRECT_FRAMES = 2, /* < Accept correct frames only, i.e. frames with correct Frame Check Sequence (FCS). */
126 AIRPCAP_VT_ACCEPT_CORRUPT_FRAMES = 3, /* < Accept corrupt frames only, i.e. frames with wrong Frame Check Sequence (FCS). */
127 AIRPCAP_VT_UNKNOWN = 4 /* < Unknown validation type. You should see it only in case of error. */
128}AirpcapValidationType, *PAirpcapValidationType;
129
135typedef enum _AirpcapDecryptionState
136{
137 AIRPCAP_DECRYPTION_ON = 1, /* < This adapter performs decryption */
138 AIRPCAP_DECRYPTION_OFF = 2 /* < This adapter does not perform decryption */
139}AirpcapDecryptionState, *PAirpcapDecryptionState;
140
141
145typedef struct _AirpcapMacAddress
146{
147 uint8_t Address[6]; /* < MAC address bytes */
148}
149#ifdef __MINGW32__
150__attribute__((__packed__))
151#endif
153
174typedef struct _AirpcapKeysCollection
175{
176 unsigned nKeys; /* < Number of keys in the collection */
177 AirpcapKey Keys[1]; /* < Array of nKeys keys. */
179
180#define AirpcapKeysCollectionSize(nKeys) \
181 ((sizeof(AirpcapKeysCollection) - sizeof(AirpcapKey)) + ((nKeys) * sizeof(AirpcapKey)))
182#define AirpcapKeysCollectionSizeToKeyCount(size) \
183 (unsigned)(((size) - AirpcapKeysCollectionSize(0))/sizeof(AirpcapKey))
184
190typedef struct _AirpcapBpfHeader
191{
192 unsigned TsSec; /* < Timestamp associated with the captured packet. SECONDS. */
193 unsigned TsUsec; /* < Timestamp associated with the captured packet. MICROSECONDS. */
194 unsigned 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. */
195 unsigned Originallen; /* < Original length of packet */
196 uint16_t 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 field can be used to retrieve the actual data of the packet. */
197}
198#ifdef __MINGW32__
199__attribute__((__packed__))
200#endif
202
203/* Helper macros to extract packets coming from the driver. Rounds up to the next even multiple of AIRPCAP_ALIGNMENT. */
204#define AIRPCAP_ALIGNMENT sizeof(int)
205#define AIRPCAP_WORDALIGN(x) (((x)+(AIRPCAP_ALIGNMENT-1))&~(AIRPCAP_ALIGNMENT-1))
206
207#ifdef _WIN32
208#ifndef __MINGW32__
209#pragma pack(pop)
210#endif
211#endif
212
213#define AIRPCAP_ERRBUF_SIZE 512 /* < Size of the error buffer, in bytes */
214
215#ifndef __AIRPCAP_DRIVER__
216
221#undef _AirpcapLinkType
222typedef enum _AirpcapLinkType
223{
224 AIRPCAP_LT_802_11 = 1, /* < plain 802.11 linktype. Every packet in the buffer contains the raw 802.11 frame, including MAC FCS. */
225 AIRPCAP_LT_802_11_PLUS_RADIO = 2, /* < 802.11 plus radiotap linktype. Every packet in the buffer contains a radiotap header followed by the 802.11 frame. MAC FCS is included. */
226 AIRPCAP_LT_UNKNOWN = 3, /* < Unknown linktype. You should see it only in case of error. */
227 AIRPCAP_LT_802_11_PLUS_PPI = 4 /* < 802.11 plus PPI header linktype. Every packet in the buffer contains a PPI header followed by the 802.11 frame. MAC FCS is included. */
228}AirpcapLinkType, *PAirpcapLinkType;
229
230#if !defined(AIRPCAP_HANDLE__EAE405F5_0171_9592_B3C2_C19EC426AD34__DEFINED_)
231#define AIRPCAP_HANDLE__EAE405F5_0171_9592_B3C2_C19EC426AD34__DEFINED_
235typedef struct _AirpcapHandle AirpcapHandle, *PAirpcapHandle;
236#endif
237
242typedef struct _AirpcapStats
243{
244 unsigned Recvs; /* < Number of packets that the driver received by the adapter */
245 /* < from the beginning of the current capture. This value includes the packets */
246 /* < dropped because of buffer full. */
247 unsigned Drops; /* < number of packets that the driver dropped from the beginning of a capture. */
248 /* < A packet is lost when the driver's buffer is full. */
249 unsigned IfDrops; /* < Packets dropped by the card before going to the USB bus. */
250 /* < Not supported at the moment. */
251 unsigned Capt; /* < number of packets that pass the BPF filter, find place in the kernel buffer and */
252 /* < therefore reach the application. */
254
259typedef struct _AirpcapChannelInfo
260{
261 unsigned Frequency; /* < Channel frequency, in MHz. */
272 int8_t ExtChannel;
273 uint8_t Reserved[3]; /* < Reserved. It should be set to {0,0,0}. */
276
277
291void AirpcapGetVersion(unsigned * VersionMajor, unsigned * VersionMinor, unsigned * VersionRev, unsigned * VersionBuild);
292
298char * AirpcapGetLastError(PAirpcapHandle AdapterHandle);
299
329bool AirpcapGetDeviceList(PAirpcapDeviceDescription *PPAllDevs, char * Ebuf);
330
336
343PAirpcapHandle AirpcapOpen(char * DeviceName, char * Ebuf);
344
349void AirpcapClose(PAirpcapHandle AdapterHandle);
350
381bool AirpcapSetMonitorMode(PAirpcapHandle AdapterHandle, bool MonitorModeEnabled);
382
393bool AirpcapGetMonitorMode(PAirpcapHandle AdapterHandle, bool * PMonitorModeEnabled);
394
414bool AirpcapSetLinkType(PAirpcapHandle AdapterHandle, AirpcapLinkType NewLinkType);
415
432bool AirpcapGetLinkType(PAirpcapHandle AdapterHandle, PAirpcapLinkType PLinkType);
433
447bool AirpcapSetFcsPresence(PAirpcapHandle AdapterHandle, bool IsFcsPresent);
448
462bool AirpcapGetFcsPresence(PAirpcapHandle AdapterHandle, bool * PIsFcsPresent);
463
472bool AirpcapSetFcsValidation(PAirpcapHandle AdapterHandle, AirpcapValidationType ValidationType);
473
482bool AirpcapGetFcsValidation(PAirpcapHandle AdapterHandle, PAirpcapValidationType ValidationType);
483
505bool AirpcapSetDeviceKeys(PAirpcapHandle AdapterHandle, PAirpcapKeysCollection KeysCollection);
506
531bool AirpcapGetDeviceKeys(PAirpcapHandle AdapterHandle, PAirpcapKeysCollection KeysCollection, unsigned * PKeysCollectionSize);
532
554bool AirpcapSetDriverKeys(PAirpcapHandle AdapterHandle, PAirpcapKeysCollection KeysCollection);
555
576bool AirpcapGetDriverKeys(PAirpcapHandle AdapterHandle, PAirpcapKeysCollection KeysCollection, unsigned * PKeysCollectionSize);
577
587bool AirpcapSetDecryptionState(PAirpcapHandle AdapterHandle, AirpcapDecryptionState Enable);
588
598bool AirpcapGetDecryptionState(PAirpcapHandle AdapterHandle, PAirpcapDecryptionState PEnable);
599
609bool AirpcapSetDriverDecryptionState(PAirpcapHandle AdapterHandle, AirpcapDecryptionState Enable);
610
620bool AirpcapGetDriverDecryptionState(PAirpcapHandle AdapterHandle, PAirpcapDecryptionState PEnable);
621
633bool AirpcapSetDeviceChannel(PAirpcapHandle AdapterHandle, unsigned Channel);
634
646bool AirpcapGetDeviceChannel(PAirpcapHandle AdapterHandle, unsigned * PChannel);
647
662bool AirpcapSetKernelBuffer(PAirpcapHandle AdapterHandle, unsigned BufferSize);
663
673bool AirpcapGetKernelBufferSize(PAirpcapHandle AdapterHandle, unsigned * PSizeBytes);
674
712bool AirpcapStoreCurConfigAsAdapterDefault(PAirpcapHandle AdapterHandle);
713
732bool AirpcapSetFilter(PAirpcapHandle AdapterHandle, void * Instructions, unsigned Len);
733
741bool AirpcapGetMacAddress(PAirpcapHandle AdapterHandle, PAirpcapMacAddress PMacAddress);
742
756bool AirpcapSetMinToCopy(PAirpcapHandle AdapterHandle, unsigned MinToCopy);
757
768bool AirpcapGetReadEvent(PAirpcapHandle AdapterHandle, void *** PReadEvent);
769
787bool AirpcapRead(PAirpcapHandle AdapterHandle, uint8_t * Buffer, unsigned BufSize, unsigned * PReceievedBytes);
788
806bool AirpcapWrite(PAirpcapHandle AdapterHandle, char * TxPacket, uint32_t PacketLen);
807
814bool AirpcapGetStats(PAirpcapHandle AdapterHandle, PAirpcapStats PStats);
815
822bool AirpcapGetLedsNumber(PAirpcapHandle AdapterHandle, unsigned * NumberOfLeds);
823
830bool AirpcapTurnLedOn(PAirpcapHandle AdapterHandle, unsigned LedNumber);
831
838bool AirpcapTurnLedOff(PAirpcapHandle AdapterHandle, unsigned LedNumber);
839
849bool AirpcapSetDeviceChannelEx(PAirpcapHandle AdapterHandle, AirpcapChannelInfo ChannelInfo);
850
860bool AirpcapGetDeviceChannelEx(PAirpcapHandle AdapterHandle, PAirpcapChannelInfo PChannelInfo);
861
876bool AirpcapGetDeviceSupportedChannels(PAirpcapHandle AdapterHandle, PAirpcapChannelInfo *ppChannelInfo, unsigned * pNumChannelInfo);
877
886bool AirpcapConvertFrequencyToChannel(unsigned Frequency, unsigned * PChannel, PAirpcapChannelBand PBand);
887
895bool AirpcapConvertChannelToFrequency(unsigned Channel, unsigned * PFrequency);
896
897
900#endif /* __AIRPCAP_DRIVER__ */
901
902#ifdef __cplusplus
903}
904#endif
905
906#endif /* !defined(AIRPCAP_H__EAE405F5_0171_9592_B3C2_C19EC426AD34__INCLUDED_) */
struct _AirpcapChannelInfo AirpcapChannelInfo
Channel information. Used by AirpcapSetDeviceChannelEx(), AirpcapGetDeviceChannelEx(),...
_AirpcapValidationType
Type of frame validation the adapter performs. An adapter can be instructed to accept different kind ...
Definition airpcap.h:122
struct _AirpcapKey AirpcapKey
WEP key container.
struct _AirpcapHandle AirpcapHandle
Adapter handle.
Definition airpcap.h:234
enum _AirpcapLinkType AirpcapLinkType
Link type. AirPcap supports two kind of 802.11 linktypes: plain 802.11 and radiotap.
enum _AirpcapDecryptionState AirpcapDecryptionState
Type of decryption the adapter performs. An adapter can be instructed to turn decryption (based on th...
struct _AirpcapStats AirpcapStats
Capture statistics. Returned by AirpcapGetStats();.
struct _AirpcapDeviceDescription AirpcapDeviceDescription
Entry in the list returned by AirpcapGetDeviceList();.
_AirpcapLinkType
Link type. AirPcap supports two kind of 802.11 linktypes: plain 802.11 and radiotap.
Definition airpcap.h:222
struct _AirpcapKeysCollection AirpcapKeysCollection
This structure is used to store a collection of WEP keys. Note that the definition of the structure h...
struct _AirpcapBpfHeader AirpcapBpfHeader
Packet header.
_AirpcapDecryptionState
Type of decryption the adapter performs. An adapter can be instructed to turn decryption (based on th...
Definition airpcap.h:135
struct _AirpcapMacAddress AirpcapMacAddress
Storage for a MAC address.
enum _AirpcapValidationType AirpcapValidationType
Type of frame validation the adapter performs. An adapter can be instructed to accept different kind ...
_AirpcapChannelBand
frequency Band. 802.11 adapters can support different frequency bands, the most important of which ar...
Definition airpcap.h:110
enum _AirpcapChannelBand AirpcapChannelBand
frequency Band. 802.11 adapters can support different frequency bands, the most important of which ar...
bool AirpcapSetDriverDecryptionState(PAirpcapHandle AdapterHandle, AirpcapDecryptionState Enable)
Turns on or off the decryption of the incoming frames with the global driver set of keys.
bool AirpcapGetLinkType(PAirpcapHandle AdapterHandle, PAirpcapLinkType PLinkType)
Get the link type of the specified adapter.
bool AirpcapSetMinToCopy(PAirpcapHandle AdapterHandle, unsigned MinToCopy)
Set the mintocopy parameter for an open adapter.
bool AirpcapRead(PAirpcapHandle AdapterHandle, uint8_t *Buffer, unsigned BufSize, unsigned *PReceievedBytes)
Fills a user-provided buffer with zero or more packets that have been captured on the referenced adap...
bool AirpcapSetLinkType(PAirpcapHandle AdapterHandle, AirpcapLinkType NewLinkType)
Set the link type of an adapter.
bool AirpcapConvertChannelToFrequency(unsigned Channel, unsigned *PFrequency)
Converts a given channel to the corresponding frequency.
int8_t ExtChannel
802.11n specific. Offset of the extension channel in case of 40MHz channels.
Definition airpcap.h:271
bool AirpcapGetLedsNumber(PAirpcapHandle AdapterHandle, unsigned *NumberOfLeds)
Get the number of LEDs the referenced adapter has available.
bool AirpcapGetMacAddress(PAirpcapHandle AdapterHandle, PAirpcapMacAddress PMacAddress)
Return the MAC address of an adapter.
bool AirpcapGetDecryptionState(PAirpcapHandle AdapterHandle, PAirpcapDecryptionState PEnable)
Tells if this open instance is configured to perform the decryption of the incoming frames with the a...
void AirpcapGetVersion(unsigned *VersionMajor, unsigned *VersionMinor, unsigned *VersionRev, unsigned *VersionBuild)
Return a string with the API version.
void AirpcapFreeDeviceList(PAirpcapDeviceDescription PAllDevs)
Free a list of devices returned by AirpcapGetDeviceList()
bool AirpcapSetDeviceChannelEx(PAirpcapHandle AdapterHandle, AirpcapChannelInfo ChannelInfo)
Set the channel of a device through its radio frequency. In case of 802.11n enabled devices,...
bool AirpcapGetDeviceKeys(PAirpcapHandle AdapterHandle, PAirpcapKeysCollection KeysCollection, unsigned *PKeysCollectionSize)
Returns the list of decryption keys in the driver that are currently associated with the specified de...
bool AirpcapSetDecryptionState(PAirpcapHandle AdapterHandle, AirpcapDecryptionState Enable)
Turns on or off the decryption of the incoming frames with the adapter-specific keys.
bool AirpcapSetMonitorMode(PAirpcapHandle AdapterHandle, bool MonitorModeEnabled)
Sets the monitor mode for the specified adapter.
bool AirpcapGetKernelBufferSize(PAirpcapHandle AdapterHandle, unsigned *PSizeBytes)
Get the size of the kernel packet buffer for this adapter.
bool AirpcapGetFcsPresence(PAirpcapHandle AdapterHandle, bool *PIsFcsPresent)
Returns true if the specified adapter includes the MAC Frame Check Sequence in the captured packets.
bool AirpcapSetFilter(PAirpcapHandle AdapterHandle, void *Instructions, unsigned Len)
Set the BPF kernel filter for an adapter.
bool AirpcapSetKernelBuffer(PAirpcapHandle AdapterHandle, unsigned BufferSize)
Set the size of the kernel packet buffer for this adapter.
bool AirpcapGetFcsValidation(PAirpcapHandle AdapterHandle, PAirpcapValidationType ValidationType)
Checks if the specified adapter is configured to capture frames with incorrect an incorrect Frame Che...
void AirpcapClose(PAirpcapHandle AdapterHandle)
Close an adapter.
bool AirpcapWrite(PAirpcapHandle AdapterHandle, char *TxPacket, uint32_t PacketLen)
Transmits a packet.
char * AirpcapGetLastError(PAirpcapHandle AdapterHandle)
Return the last error related to the specified handle.
bool AirpcapGetDeviceSupportedChannels(PAirpcapHandle AdapterHandle, PAirpcapChannelInfo *ppChannelInfo, unsigned *pNumChannelInfo)
Get the list of supported channels for a given device. In case of a 802.11n capable device,...
bool AirpcapGetDeviceChannelEx(PAirpcapHandle AdapterHandle, PAirpcapChannelInfo PChannelInfo)
Get the channel of a device through its radiofrequency. In case of 802.11n enabled devices,...
bool AirpcapSetDeviceChannel(PAirpcapHandle AdapterHandle, unsigned Channel)
Set the radio channel of a device.
bool AirpcapSetFcsValidation(PAirpcapHandle AdapterHandle, AirpcapValidationType ValidationType)
Configures the adapter to accept or drop frames with an incorrect Frame Check sequence (FCS).
PAirpcapHandle AirpcapOpen(char *DeviceName, char *Ebuf)
Open an adapter.
bool AirpcapSetDeviceKeys(PAirpcapHandle AdapterHandle, PAirpcapKeysCollection KeysCollection)
Set the list of decryption keys that the driver is going to use with the specified device.
bool AirpcapGetDeviceChannel(PAirpcapHandle AdapterHandle, unsigned *PChannel)
Get the radio channel of a device.
bool AirpcapGetMonitorMode(PAirpcapHandle AdapterHandle, bool *PMonitorModeEnabled)
Returns true if the specified adapter is in monitor mode.
bool AirpcapConvertFrequencyToChannel(unsigned Frequency, unsigned *PChannel, PAirpcapChannelBand PBand)
Converts a given frequency to the corresponding channel.
bool AirpcapSetFcsPresence(PAirpcapHandle AdapterHandle, bool IsFcsPresent)
Configures the adapter on whether to include the MAC Frame Check Sequence in the captured packets.
bool AirpcapGetDriverKeys(PAirpcapHandle AdapterHandle, PAirpcapKeysCollection KeysCollection, unsigned *PKeysCollectionSize)
Returns the global list of decryption keys in the driver that are associated with all the devices.
bool AirpcapTurnLedOff(PAirpcapHandle AdapterHandle, unsigned LedNumber)
Turn off one of the adapter's LEDs.
bool AirpcapStoreCurConfigAsAdapterDefault(PAirpcapHandle AdapterHandle)
Saves the configuration of the specified adapter in the registry, so that it becomes the default for ...
bool AirpcapTurnLedOn(PAirpcapHandle AdapterHandle, unsigned LedNumber)
Turn on one of the adapter's LEDs.
bool AirpcapGetDeviceList(PAirpcapDeviceDescription *PPAllDevs, char *Ebuf)
Return the list of available devices.
bool AirpcapGetReadEvent(PAirpcapHandle AdapterHandle, void ***PReadEvent)
Gets an event that is signaled when that is signalled when packets are available in the kernel buffer...
bool AirpcapGetDriverDecryptionState(PAirpcapHandle AdapterHandle, PAirpcapDecryptionState PEnable)
Tells if this open instance is configured to perform the decryption of the incoming frames with the g...
bool AirpcapSetDriverKeys(PAirpcapHandle AdapterHandle, PAirpcapKeysCollection KeysCollection)
Set the global list of decryption keys that the driver is going to use with all the devices.
bool AirpcapGetStats(PAirpcapHandle AdapterHandle, PAirpcapStats PStats)
Get per-adapter WinPcap-compatible capture statistics.
Packet header.
Definition airpcap.h:190
Channel information. Used by AirpcapSetDeviceChannelEx(), AirpcapGetDeviceChannelEx(),...
Definition airpcap.h:259
Entry in the list returned by AirpcapGetDeviceList();.
Definition airpcap.h:69
WEP key container.
Definition airpcap.h:94
This structure is used to store a collection of WEP keys. Note that the definition of the structure h...
Definition airpcap.h:174
Storage for a MAC address.
Definition airpcap.h:145
Capture statistics. Returned by AirpcapGetStats();.
Definition airpcap.h:242
Definition address.h:56
Definition buffer.h:22