airpcap.h

Go to the documentation of this file.

 
#if !defined(AIRPCAP_H__EAE405F5_0171_9592_B3C2_C19EC426AD34__INCLUDED_)
#define AIRPCAP_H__EAE405F5_0171_9592_B3C2_C19EC426AD34__INCLUDED_
 
#ifdef _MSC_VER
/* This stops VS2005 ranting against stdio. */
#pragma warning( disable : 4996)
#endif
 
#ifdef _WIN32
#include <winsock2.h>
#endif
 
#ifdef __cplusplus
extern "C" {
#endif
 
/*
    \mainpage AirPcap interface documentation
 
    \section Introduction
 
    This document describes the data structures and the functions exported by the CACE Technologies AirPcap library.
    The AirPcap library provides low-level access to the AirPcap driver including advanced capabilities such as channel setting,
    link type control and WEP configuration.<br>
    This manual includes the following sections:
 
    \note throughout this documentation, \e device refers to a physical USB AirPcap device, while \e adapter is an open API
    instance. Most of the AirPcap API operations are adapter-specific but some of them, like setting the channel, are
    per-device and will be reflected on all the open adapters. These functions will have "Device" in their name, e.g.
    AirpcapSetDeviceChannel().
 
    \b Sections:
 
    - \ref airpcapfuncs
    - \ref airpcapdefs
    - \ref radiotap
*/
 
#define AIRPCAP_DEVICE_NAME_PREFIX        "\\\\.\\airpcap"
 
#define AIRPCAP_DEVICE_NUMBER_EXTRACT_STRING         "\\\\.\\airpcap%u"
 
#define AIRPCAP_DEVICE_ANY_EXTRACT_STRING "\\\\.\\airpcap_any"
 
typedef struct _AirpcapDeviceDescription
{
    struct    _AirpcapDeviceDescription *next;  /* < Next element in the list */
    char *    Name;                            /* < Device name */
    char *    Description;                     /* < Device description */
} AirpcapDeviceDescription, *PAirpcapDeviceDescription;
 
#define MAX_ENCRYPTION_KEYS 64
 
#define WEP_KEY_MAX_SIZE 32        /* < Maximum size of a WEP key, in bytes. This is the size of an entry in the
                                      < AirpcapWepKeysCollection structure. */
 
#ifdef _WIN32
#ifndef __MINGW32__
#pragma pack(push)
#pragma pack(1)
#endif
#endif
 
#define AIRPCAP_KEYTYPE_WEP    0    /* < Key type: WEP. The key can have an arbitrary length smaller than 32 bytes. */
#define AIRPCAP_KEYTYPE_TKIP   1    /* < Key type: TKIP (WPA). NOT SUPPORTED YET. */
#define AIRPCAP_KEYTYPE_CCMP   2    /* < Key type: CCMP (WPA2). NOT SUPPORTED YET. */
 
typedef struct _AirpcapKey
{
    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. */
    unsigned KeyLen;                     /* < Length of the key, in bytes */
    uint8_t KeyData[WEP_KEY_MAX_SIZE]; /* < Key Data */
}
#ifdef __MINGW32__
__attribute__((__packed__))
#endif
AirpcapKey, *PAirpcapKey;
 
typedef enum _AirpcapChannelBand
{
    AIRPCAP_CB_AUTO = 1,                /* < Automatically pick the best frequency band */
    AIRPCAP_CB_2_4_GHZ = 2,             /* < 2.4 GHz frequency band */
    AIRPCAP_CB_4_GHZ = 4,               /* < 4 GHz frequency band */
    AIRPCAP_CB_5_GHZ = 5                /* < 5 GHz frequency band */
}AirpcapChannelBand, *PAirpcapChannelBand;
 
typedef enum _AirpcapValidationType
{
    AIRPCAP_VT_ACCEPT_EVERYTHING = 1,     /* < Accept all the frames the device captures */
    AIRPCAP_VT_ACCEPT_CORRECT_FRAMES = 2, /* < Accept correct frames only, i.e. frames with correct Frame Check Sequence (FCS). */
    AIRPCAP_VT_ACCEPT_CORRUPT_FRAMES = 3, /* < Accept corrupt frames only, i.e. frames with wrong Frame Check Sequence (FCS). */
    AIRPCAP_VT_UNKNOWN = 4                /* < Unknown validation type. You should see it only in case of error. */
}AirpcapValidationType, *PAirpcapValidationType;
 
typedef enum _AirpcapDecryptionState
{
    AIRPCAP_DECRYPTION_ON = 1,        /* < This adapter performs decryption */
    AIRPCAP_DECRYPTION_OFF = 2        /* < This adapter does not perform decryption */
}AirpcapDecryptionState, *PAirpcapDecryptionState;
 
 
typedef struct _AirpcapMacAddress
{
    uint8_t Address[6];        /* < MAC address bytes */
}
#ifdef __MINGW32__
__attribute__((__packed__))
#endif
AirpcapMacAddress, *PAirpcapMacAddress;
 
typedef struct _AirpcapKeysCollection
{
    unsigned nKeys;                    /* < Number of keys in the collection */
    AirpcapKey Keys[1];             /* < Array of nKeys keys. */
} AirpcapKeysCollection, *PAirpcapKeysCollection;
 
#define AirpcapKeysCollectionSize(nKeys) \
    ((sizeof(AirpcapKeysCollection) - sizeof(AirpcapKey)) + ((nKeys) * sizeof(AirpcapKey)))
#define AirpcapKeysCollectionSizeToKeyCount(size) \
    (unsigned)(((size) - AirpcapKeysCollectionSize(0))/sizeof(AirpcapKey))
 
typedef struct _AirpcapBpfHeader
{
    unsigned TsSec;        /* < Timestamp associated with the captured packet. SECONDS. */
    unsigned TsUsec;       /* < Timestamp associated with the captured packet. MICROSECONDS. */
    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. */
    unsigned Originallen;  /* < Original length of packet */
    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. */
}
#ifdef __MINGW32__
__attribute__((__packed__))
#endif
AirpcapBpfHeader, *PAirpcapBpfHeader;
 
/* Helper macros to extract packets coming from the driver. Rounds up to the next even multiple of AIRPCAP_ALIGNMENT. */
#define AIRPCAP_ALIGNMENT sizeof(int)
#define AIRPCAP_WORDALIGN(x) (((x)+(AIRPCAP_ALIGNMENT-1))&~(AIRPCAP_ALIGNMENT-1))
 
#ifdef _WIN32
#ifndef __MINGW32__
#pragma pack(pop)
#endif
#endif
 
#define AIRPCAP_ERRBUF_SIZE 512        /* < Size of the error buffer, in bytes */
 
#ifndef __AIRPCAP_DRIVER__
 
#undef _AirpcapLinkType
typedef enum _AirpcapLinkType
{
    AIRPCAP_LT_802_11 = 1,            /* < plain 802.11 linktype. Every packet in the buffer contains the raw 802.11 frame, including MAC FCS. */
    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. */
    AIRPCAP_LT_UNKNOWN = 3,           /* < Unknown linktype. You should see it only in case of error. */
    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. */
}AirpcapLinkType, *PAirpcapLinkType;
 
#if !defined(AIRPCAP_HANDLE__EAE405F5_0171_9592_B3C2_C19EC426AD34__DEFINED_)
#define AIRPCAP_HANDLE__EAE405F5_0171_9592_B3C2_C19EC426AD34__DEFINED_
typedef struct _AirpcapHandle AirpcapHandle, *PAirpcapHandle;
#endif
 
typedef struct _AirpcapStats
{
    unsigned Recvs;        /* < Number of packets that the driver received by the adapter */
                        /* < from the beginning of the current capture. This value includes the packets */
                        /* < dropped because of buffer full. */
    unsigned Drops;        /* < number of packets that the driver dropped from the beginning of a capture. */
                        /* < A packet is lost when the driver's buffer is full. */
    unsigned IfDrops;      /* < Packets dropped by the card before going to the USB bus. */
                        /* < Not supported at the moment. */
    unsigned Capt;         /* < number of packets that pass the BPF filter, find place in the kernel buffer and */
                        /* < therefore reach the application. */
}AirpcapStats, *PAirpcapStats;
 
typedef struct _AirpcapChannelInfo
{
    unsigned Frequency;    /* < Channel frequency, in MHz. */
    int8_t ExtChannel;
    uint8_t Reserved[3]; /* < Reserved. It should be set to {0,0,0}. */
}
    AirpcapChannelInfo, *PAirpcapChannelInfo;
 
 
void AirpcapGetVersion(unsigned * VersionMajor, unsigned * VersionMinor, unsigned * VersionRev, unsigned * VersionBuild);
 
char * AirpcapGetLastError(PAirpcapHandle AdapterHandle);
 
bool AirpcapGetDeviceList(PAirpcapDeviceDescription *PPAllDevs, char * Ebuf);
 
void AirpcapFreeDeviceList(PAirpcapDeviceDescription PAllDevs);
 
PAirpcapHandle AirpcapOpen(char * DeviceName, char * Ebuf);
 
void AirpcapClose(PAirpcapHandle AdapterHandle);
 
bool AirpcapSetMonitorMode(PAirpcapHandle AdapterHandle, bool MonitorModeEnabled);
 
bool AirpcapGetMonitorMode(PAirpcapHandle AdapterHandle, bool * PMonitorModeEnabled);
 
bool AirpcapSetLinkType(PAirpcapHandle AdapterHandle, AirpcapLinkType NewLinkType);
 
bool AirpcapGetLinkType(PAirpcapHandle AdapterHandle, PAirpcapLinkType PLinkType);
 
bool AirpcapSetFcsPresence(PAirpcapHandle AdapterHandle, bool IsFcsPresent);
 
bool AirpcapGetFcsPresence(PAirpcapHandle AdapterHandle, bool * PIsFcsPresent);
 
bool AirpcapSetFcsValidation(PAirpcapHandle AdapterHandle, AirpcapValidationType ValidationType);
 
bool AirpcapGetFcsValidation(PAirpcapHandle AdapterHandle, PAirpcapValidationType ValidationType);
 
bool AirpcapSetDeviceKeys(PAirpcapHandle AdapterHandle, PAirpcapKeysCollection KeysCollection);
 
bool AirpcapGetDeviceKeys(PAirpcapHandle AdapterHandle, PAirpcapKeysCollection KeysCollection, unsigned * PKeysCollectionSize);
 
bool AirpcapSetDriverKeys(PAirpcapHandle AdapterHandle, PAirpcapKeysCollection KeysCollection);
 
bool AirpcapGetDriverKeys(PAirpcapHandle AdapterHandle, PAirpcapKeysCollection KeysCollection, unsigned * PKeysCollectionSize);
 
bool AirpcapSetDecryptionState(PAirpcapHandle AdapterHandle, AirpcapDecryptionState Enable);
 
bool AirpcapGetDecryptionState(PAirpcapHandle AdapterHandle, PAirpcapDecryptionState PEnable);
 
bool AirpcapSetDriverDecryptionState(PAirpcapHandle AdapterHandle, AirpcapDecryptionState Enable);
 
bool AirpcapGetDriverDecryptionState(PAirpcapHandle AdapterHandle, PAirpcapDecryptionState PEnable);
 
bool AirpcapSetDeviceChannel(PAirpcapHandle AdapterHandle, unsigned Channel);
 
bool AirpcapGetDeviceChannel(PAirpcapHandle AdapterHandle, unsigned * PChannel);
 
bool AirpcapSetKernelBuffer(PAirpcapHandle AdapterHandle, unsigned BufferSize);
 
bool AirpcapGetKernelBufferSize(PAirpcapHandle AdapterHandle, unsigned * PSizeBytes);
 
bool AirpcapStoreCurConfigAsAdapterDefault(PAirpcapHandle AdapterHandle);
 
bool AirpcapSetFilter(PAirpcapHandle AdapterHandle, void * Instructions, unsigned Len);
 
bool AirpcapGetMacAddress(PAirpcapHandle AdapterHandle, PAirpcapMacAddress PMacAddress);
 
bool AirpcapSetMinToCopy(PAirpcapHandle AdapterHandle, unsigned MinToCopy);
 
bool AirpcapGetReadEvent(PAirpcapHandle AdapterHandle, void *** PReadEvent);
 
bool AirpcapRead(PAirpcapHandle AdapterHandle, uint8_t * Buffer, unsigned BufSize, unsigned * PReceievedBytes);
 
bool AirpcapWrite(PAirpcapHandle AdapterHandle, char * TxPacket, uint32_t PacketLen);
 
bool AirpcapGetStats(PAirpcapHandle AdapterHandle, PAirpcapStats PStats);
 
bool AirpcapGetLedsNumber(PAirpcapHandle AdapterHandle, unsigned * NumberOfLeds);
 
bool AirpcapTurnLedOn(PAirpcapHandle AdapterHandle, unsigned LedNumber);
 
bool AirpcapTurnLedOff(PAirpcapHandle AdapterHandle, unsigned LedNumber);
 
bool AirpcapSetDeviceChannelEx(PAirpcapHandle AdapterHandle, AirpcapChannelInfo ChannelInfo);
 
bool AirpcapGetDeviceChannelEx(PAirpcapHandle AdapterHandle, PAirpcapChannelInfo PChannelInfo);
 
bool AirpcapGetDeviceSupportedChannels(PAirpcapHandle AdapterHandle, PAirpcapChannelInfo *ppChannelInfo, unsigned * pNumChannelInfo);
 
bool AirpcapConvertFrequencyToChannel(unsigned Frequency, unsigned * PChannel, PAirpcapChannelBand PBand);
 
bool AirpcapConvertChannelToFrequency(unsigned Channel, unsigned * PFrequency);
 
 
#endif /* __AIRPCAP_DRIVER__ */
 
#ifdef __cplusplus
}
#endif
 
#endif /* !defined(AIRPCAP_H__EAE405F5_0171_9592_B3C2_C19EC426AD34__INCLUDED_) */