From 7be69181dc7a19fc09cfe88f3947dd6543c24d0d Mon Sep 17 00:00:00 2001 From: Brad Parker Date: Sat, 31 Aug 2013 20:58:09 -0400 Subject: [PATCH] add doxygen comments for Wireless class, change Neighbor list() method to return string hash so we can give both ip and mac for arp entries --- interface.cpp | 2 +- iptest/iptest.cpp | 6 +-- wireless.cpp | 94 ++++++++++++++++++++++++++++++++++++----------- wireless.h | 87 ++++++++++++++++++++++--------------------- 4 files changed, 121 insertions(+), 68 deletions(-) diff --git a/interface.cpp b/interface.cpp index 52af515..7e6eb00 100644 --- a/interface.cpp +++ b/interface.cpp @@ -25,7 +25,7 @@ extern "C" { /*! \class Interface - \brief The Interface class is used to manage IP address information associated with an interface. + \brief The Interface class is used to manage IP addresses associated with an interface. */ /*! diff --git a/iptest/iptest.cpp b/iptest/iptest.cpp index 51292dd..402ca83 100644 --- a/iptest/iptest.cpp +++ b/iptest/iptest.cpp @@ -47,9 +47,9 @@ int main(int argc, char *argv[]) { Wireless wi("wlp0s11u1"); - QList bands = wi.bandMap(); + QList bands = wi.bandMap(); - foreach(BandInfo band, bands) { + foreach(Wireless::BandInfo band, bands) { std::cout << "found band" << (((band.band & Wireless::BAND_2GHZ) == Wireless::BAND_2GHZ) ? " 2GHz" : "") << (((band.band & Wireless::BAND_5GHZ) == Wireless::BAND_5GHZ) ? " 5GHz" : "") << @@ -69,7 +69,7 @@ int main(int argc, char *argv[]) { std::cout << std::endl; if(band.channels.count() > 0) { - foreach(ChannelInfo info, band.channels) { + foreach(Wireless::ChannelInfo info, band.channels) { std::cout << " found channel " << info.chan << " (" << info.freq << "): " << "Disabled?: " << (info.disabled ? "yes" : "no") << " " << "Passive?: " << (info.passive ? "yes" : "no") << " " << diff --git a/wireless.cpp b/wireless.cpp index 44cc8d7..f8adf6f 100644 --- a/wireless.cpp +++ b/wireless.cpp @@ -83,6 +83,14 @@ struct nl_callback { void *bands; }; +/*! + \class Wireless + \brief The Wireless class is used to manage 802.11 wireless information associated with an interface. Currently this class makes the assumption that it will only be used within the United States FCC regulatory domain. Only drivers supporting the Linux kernel nl80211 interface are supported. +*/ + +/*! + Constructs a Wireless object. All operations will be limited to the specified \a interface. +*/ Wireless::Wireless(QString interface) : QObject(0), m_interface(interface), @@ -147,6 +155,9 @@ Wireless::~Wireless() { m_bands.clear(); } +/*! + Returns a list of integers representing all physically supported channels in all supported bands, regardless if TX/RX is allowed or not in the current regulatory domain. +*/ QList Wireless::allChannels() const { QList channels; @@ -159,15 +170,18 @@ QList Wireless::allChannels() const { return channels; } -QList Wireless::allowedChannels(Direction dir) const { +/*! + Returns a list of integers representing all channels (regardless of band) that are allowed to be used in the specified \a direction. Some channels are only available in the receive direction because of regulatory rules, or require that DFS/TPC be used in order to transmit. If \a direction is specified as \a Both, then all non-disabled channels regardless of TX/RX regulation will be returned. +*/ +QList Wireless::allowedChannels(Direction direction) const { QList channels; foreach(BandInfo info, m_bands) { foreach(ChannelInfo chan, info.channels) { if(!chan.disabled) { - if(((dir & Direction_Both) == Direction_Both) && (!chan.passive)) { + if(((direction & Direction_Both) == Direction_Both) && (!chan.passive)) { channels.append(chan.chan); - }else if(((dir & Direction_RX) == Direction_RX)) { + }else if(((direction & Direction_RX) == Direction_RX)) { channels.append(chan.chan); } } @@ -177,6 +191,9 @@ QList Wireless::allowedChannels(Direction dir) const { return channels; } +/*! + Returns a list of integers representing all physically supported frequencies (in MHz) in all supported bands, regardless if TX/RX is allowed or not in the current regulatory domain. +*/ QList Wireless::allFrequencies() const { QList freqs; @@ -189,15 +206,18 @@ QList Wireless::allFrequencies() const { return freqs; } -QList Wireless::allowedFrequencies(Direction dir) const { +/*! + Returns a list of integers representing all frequencies in MHz (regardless of band) that are allowed to be used in the specified \a direction. Some frequencies are only available in the receive direction because of regulatory rules, or require that DFS/TPC be used in order to transmit. If \a direction is specified as \a Both, then all non-disabled frequencies regardless of TX/RX regulation will be returned. +*/ +QList Wireless::allowedFrequencies(Direction direction) const { QList freqs; foreach(BandInfo band, m_bands) { foreach(ChannelInfo info, band.channels) { if(!info.disabled) { - if(((dir & Direction_Both) == Direction_Both) && (!info.passive)) { + if(((direction & Direction_Both) == Direction_Both) && (!info.passive)) { freqs.append(info.freq); - }else if(((dir & Direction_RX) == Direction_RX)) { + }else if(((direction & Direction_RX) == Direction_RX)) { freqs.append(info.freq); } } @@ -207,6 +227,9 @@ QList Wireless::allowedFrequencies(Direction dir) const { return freqs; } +/*! + Returns true if the specified channel is physically supported by the hardware, otherwise false. No checks are made in the regulatory domain as to the current TX/RX rules for the channel. +*/ bool Wireless::channelSupported(int chan) const { bool found = false; @@ -222,6 +245,9 @@ bool Wireless::channelSupported(int chan) const { return found; } +/*! + Returns true if the specified frequency (in MHz) is physically supported by the hardware, otherwise false. No checks are made in the regulatory domain as to the current TX/RX rules for the frequency. +*/ bool Wireless::frequencySupported(int freq) const { bool found = false; @@ -237,40 +263,55 @@ bool Wireless::frequencySupported(int freq) const { return found; } +/*! + Returns true if the interface exists and is supported by nl80211. If the interfaces does not exist, is unsupported, or an error occurred reading interface information, false is returned. +*/ bool Wireless::isValid() const { return m_isValid; } +/*! + Returns true if the interface is supported by nl80211, otherwise false. +*/ bool Wireless::isNL80211() const { return m_isNL80211; } +/*! + Returns the name of the interface used when the Wireless object was constructed. +*/ const QString& Wireless::name() const { return m_interface; } -int Wireless::ChanToFreq(int in_chan) { +/*! + Returns the specified \a channel converted to its corresponding frequency, in MHz. If the conversion failed, 0 is returned. +*/ +int Wireless::ChanToFreq(int channel) { int x = 0; while(IEEE80211Freq[x][0] != 0) { - if(IEEE80211Freq[x][0] == in_chan) { + if(IEEE80211Freq[x][0] == channel) { return IEEE80211Freq[x][1]; } ++x; } - return in_chan; + return 0; } -QString Wireless::ChanToFreq(QString in_chan, QString outputFormat) { +/*! + Returns the specified \a channel converted to its corresponding frequency, in MHz. If the conversion failed, an empty string is returned. +*/ +QString Wireless::ChanToFreq(QString channel, QString outputFormat) { QString freq; QRegularExpression re("[^\\d]"); - in_chan = in_chan.replace(re, ""); + channel = channel.replace(re, ""); if(outputFormat.isEmpty()) { bool ok = false; - int chanInt = in_chan.toInt(&ok); + int chanInt = channel.toInt(&ok); if(ok) { freq = QString::number(ChanToFreq(chanInt)); @@ -280,34 +321,40 @@ QString Wireless::ChanToFreq(QString in_chan, QString outputFormat) { return freq; } -int Wireless::FreqToChan(int in_freq) { +/*! + Returns the specified \a frequency converted to its corresponding channel. If the conversion failed, 0 is returned. +*/ +int Wireless::FreqToChan(int frequency) { int x = 0; while(IEEE80211Freq[x][1] != 0) { - if(IEEE80211Freq[x][1] == in_freq) { + if(IEEE80211Freq[x][1] == frequency) { return IEEE80211Freq[x][0]; } ++x; } - return in_freq; + return 0; } -QString Wireless::FreqToChan(QString in_freq, QString outputFormat) { +/*! + Returns the specified \a frequency converted to its corresponding channel. If the conversion failed, an empty string is returned. +*/ +QString Wireless::FreqToChan(QString frequency, QString outputFormat) { QString chan; QRegularExpression re("[^\\d]"); - in_freq = in_freq.replace(re, ""); + frequency = frequency.replace(re, ""); - if(in_freq.length() < 4) { - for(int i = in_freq.length() + 1; i <= 4; ++i) { - in_freq.append("0"); + if(frequency.length() < 4) { + for(int i = frequency.length() + 1; i <= 4; ++i) { + frequency.append("0"); } } if(outputFormat.isEmpty()) { bool ok = false; - int freqInt = in_freq.toInt(&ok); + int freqInt = frequency.toInt(&ok); if(ok) { chan = QString::number(FreqToChan(freqInt)); @@ -490,6 +537,9 @@ char* Wireless::nl80211_find_parent(const char *interface) const { return NULL; } -const QList& Wireless::bandMap() const { +/*! + Returns a list of BandInfo structs containing all information about the supported bands and frequencies of the interface. +*/ +const QList& Wireless::bandMap() const { return m_bands; } diff --git a/wireless.h b/wireless.h index 076499a..938d507 100644 --- a/wireless.h +++ b/wireless.h @@ -5,40 +5,6 @@ #include #include "libip_global.h" -struct ChannelInfo { - int chan; - int freq; - bool disabled; - bool passive; - bool radar; - int max_txpower; - - ChannelInfo() : - chan(0), - freq(0), - disabled(false), - passive(false), - radar(false), - max_txpower(0) - { - } -}; - -struct BandInfo { - int band; - int width; - int protocols; - QList channels; - - BandInfo() : - band(0), - width(0), - protocols(0), - channels() - { - } -}; - class LIBIP_EXPORT Wireless : public QObject { Q_OBJECT @@ -46,6 +12,43 @@ public: Wireless(QString interface = QString()); ~Wireless(); + struct ChannelInfo { + int chan; + int freq; + + // these boolean values may change depending on the current regulatory domain set + bool disabled; // both TX/RX disabled + bool passive; // RX-only channel + bool radar; // DFS (radar detection) required + + int max_txpower; // in millibels (mBm); 100 mBm = 1 dBm + + ChannelInfo() : + chan(0), + freq(0), + disabled(false), + passive(false), + radar(false), + max_txpower(0) + { + } + }; + + struct BandInfo { + int band; + int width; + int protocols; + QList channels; + + BandInfo() : + band(0), + width(0), + protocols(0), + channels() + { + } + }; + enum Bands { BAND_2GHZ = (1 << 0), BAND_5GHZ = (1 << 1), @@ -74,17 +77,17 @@ public: const QString& name() const; const QList& bandMap() const; QList allChannels() const; - QList allowedChannels(Direction dir) const; + QList allowedChannels(Direction direction) const; QList allFrequencies() const; - QList allowedFrequencies(Direction dir) const; - static int ChanToFreq(int in_chan); - static QString ChanToFreq(QString in_chan, QString outputFormat = QString()); - static int FreqToChan(int in_freq); - static QString FreqToChan(QString in_freq, QString outputFormat = QString()); + QList allowedFrequencies(Direction direction) const; + static int ChanToFreq(int channel); + static QString ChanToFreq(QString channel, QString outputFormat = QString()); + static int FreqToChan(int frequency); + static QString FreqToChan(QString frequency, QString outputFormat = QString()); bool isValid() const; bool isNL80211() const; - bool channelSupported(int chan) const; - bool frequencySupported(int freq) const; + bool channelSupported(int channel) const; + bool frequencySupported(int frequency) const; private: QString m_interface;