A Discrete-Event Network Simulator
API
Loading...
Searching...
No Matches
wifi-assoc-manager.h
Go to the documentation of this file.
1/*
2 * Copyright (c) 2022 Universita' degli Studi di Napoli Federico II
3 *
4 * SPDX-License-Identifier: GPL-2.0-only
5 *
6 * Author: Stefano Avallone <stavallo@unina.it>
7 */
8
9#ifndef WIFI_ASSOC_MANAGER_H
10#define WIFI_ASSOC_MANAGER_H
11
12#include "qos-utils.h"
13#include "sta-wifi-mac.h"
14
15#include <optional>
16#include <set>
17#include <unordered_map>
18
19namespace ns3
20{
21
22/**
23 * \ingroup wifi
24 *
25 * Abstract base class for the Association Manager, which manages
26 * scanning and association for single link devices and ML discovery
27 * and setup for multi-link devices.
28 */
30{
31 /**
32 * Struct providing a function call operator to compare two ApInfo objects.
33 * This struct is used as the Compare template type parameter of the set of
34 * ApInfo objects maintained by the Association Manager.
35 */
37 {
38 /**
39 * Constructor.
40 *
41 * \param manager a pointer to the Association Manager
42 */
43 ApInfoCompare(const WifiAssocManager& manager);
44 /**
45 * Function call operator. Calls the Compare method of the Association Manager.
46 *
47 * \param lhs left hand side ApInfo object
48 * \param rhs right hand side ApInfo object
49 * \return true if the left hand side ApInfo object should be placed before the
50 * right hand side ApInfo object in the sorted list maintained by the
51 * Association Manager, false otherwise
52 */
53 bool operator()(const StaWifiMac::ApInfo& lhs, const StaWifiMac::ApInfo& rhs) const;
54
55 private:
56 const WifiAssocManager& m_manager; ///< Association Manager
57 };
58
59 public:
60 /**
61 * Struct to identify a specific TBTT Information field of a Neighbor AP Information
62 * field in a Reduced Neighbor Report element.
63 */
65 {
66 std::size_t m_nbrApInfoId; ///< Neighbor AP Information field index
67 std::size_t m_tbttInfoFieldId; ///< TBTT Information field index
68 };
69
70 /**
71 * \brief Get the type ID.
72 * \return the object TypeId
73 */
74 static TypeId GetTypeId();
75
76 ~WifiAssocManager() override;
77
78 /**
79 * Set the pointer to the STA wifi MAC.
80 *
81 * \param mac the pointer to the STA wifi MAC
82 */
84
85 /**
86 * Request the Association Manager to start a scanning procedure according to
87 * the given scanning parameters. At subclass' discretion, stored information
88 * about APs matching the given scanning parameters may be used and scanning
89 * not performed.
90 *
91 * \param scanParams the scanning parameters
92 */
93 void StartScanning(WifiScanParams&& scanParams);
94
95 /**
96 * STA wifi MAC received a Beacon frame or Probe Response frame while scanning
97 * and notifies us the AP information contained in the received frame.
98 *
99 * Note that the given ApInfo object is moved to the sorted list of ApInfo objects.
100 *
101 * \param apInfo the AP information contained in the received frame
102 */
103 virtual void NotifyApInfo(const StaWifiMac::ApInfo&& apInfo);
104
105 /**
106 * Notify that the given link has completed channel switching.
107 *
108 * \param linkId the ID of the given link
109 */
110 virtual void NotifyChannelSwitched(uint8_t linkId) = 0;
111
112 /**
113 * Compare two ApInfo objects for the purpose of keeping a sorted list of
114 * ApInfo objects.
115 *
116 * \param lhs left hand side ApInfo object
117 * \param rhs right hand side ApInfo object
118 * \return true if the left hand side ApInfo object should be placed before the
119 * right hand side ApInfo object in the sorted list of ApInfo objects,
120 * false otherwise
121 */
122 virtual bool Compare(const StaWifiMac::ApInfo& lhs, const StaWifiMac::ApInfo& rhs) const = 0;
123
124 /**
125 * Search the given RNR element for APs affiliated to the same AP MLD as the
126 * reporting AP. The search starts at the given Neighbor AP Information field.
127 *
128 * \param rnr the given RNR element
129 * \param nbrApInfoId the index of the given Neighbor AP Information field
130 * \return the index of the Neighbor AP Information field and the index of the
131 * TBTT Information field containing the next affiliated AP, if any.
132 */
133 static std::optional<WifiAssocManager::RnrLinkInfo> GetNextAffiliatedAp(
134 const ReducedNeighborReport& rnr,
135 std::size_t nbrApInfoId);
136
137 /**
138 * Find all the APs affiliated to the same AP MLD as the reporting AP that sent
139 * the given RNR element.
140 *
141 * \param rnr the given RNR element
142 * \return a list containing the index of the Neighbor AP Information field and the index of the
143 * TBTT Information field containing all the affiliated APs
144 */
145 static std::list<WifiAssocManager::RnrLinkInfo> GetAllAffiliatedAps(
146 const ReducedNeighborReport& rnr);
147
148 protected:
149 /**
150 * Constructor (protected as this is an abstract base class)
151 */
153 void DoDispose() override;
154
155 /// typedef for the sorted list of ApInfo objects
156 using SortedList = std::set<StaWifiMac::ApInfo, ApInfoCompare>;
157
158 /**
159 * \return a const reference to the sorted list of ApInfo objects.
160 */
161 const SortedList& GetSortedList() const;
162
163 /**
164 * Get a reference to the list of the links to setup with the given AP. This method
165 * allows subclasses to modify such a list.
166 *
167 * \param apInfo the info about the given AP
168 * \return a reference to the list of the links to setup with the given AP
169 */
170 std::list<StaWifiMac::ApInfo::SetupLinksInfo>& GetSetupLinks(const StaWifiMac::ApInfo& apInfo);
171
172 /**
173 * \return the scanning parameters.
174 */
175 const WifiScanParams& GetScanParams() const;
176
177 /**
178 * Check whether the given AP information match the current scanning parameters.
179 *
180 * \param apInfo the given AP information
181 * \return whether the given AP information match the current scanning parameters
182 */
183 bool MatchScanParams(const StaWifiMac::ApInfo& apInfo) const;
184
185 /**
186 * Allow subclasses to choose whether the given ApInfo shall be considered
187 * and hence inserted in the sorted list of ApInfo objects.
188 *
189 * \param apInfo the apInfo object to insert
190 * \return true if the apInfo object can be inserted, false otherwise
191 */
192 virtual bool CanBeInserted(const StaWifiMac::ApInfo& apInfo) const = 0;
193 /**
194 * Allow subclasses to choose whether the given ApInfo shall be returned or
195 * discarded when the STA wifi MAC requests information on the best AP.
196 *
197 * \param apInfo the apInfo object to return
198 * \return true if the apInfo object can be returned, false otherwise
199 */
200 virtual bool CanBeReturned(const StaWifiMac::ApInfo& apInfo) const = 0;
201
202 /**
203 * Extract the best AP to associate with from the sorted list and return
204 * it, if any, to the STA wifi MAC along with the notification that scanning
205 * is completed.
206 */
207 void ScanningTimeout();
208
209 /// typedef for an optional const reference to a ReducedNeighborReport object
210 using OptRnrConstRef = std::optional<std::reference_wrapper<const ReducedNeighborReport>>;
211 /// typedef for an optional const reference to a MultiLinkElement object
212 using OptMleConstRef = std::optional<std::reference_wrapper<const MultiLinkElement>>;
213
214 /**
215 * Check whether 11be Multi-Link setup can be established with the current best AP.
216 *
217 * \param[out] mle const reference to the Multi-Link Element present in the
218 * Beacon/Probe Response received from the best AP, if any
219 * \param[out] rnr const reference to the Reduced Neighbor Report Element present
220 * in the Beacon/Probe Response received from the best AP, if any.
221 * \return whether 11be Multi-Link setup can be established with the current best AP
222 */
224
225 Ptr<StaWifiMac> m_mac; ///< pointer to the STA wifi MAC
226 std::set<uint8_t> m_allowedLinks; /**< "Only Beacon and Probe Response frames received on a
227 link belonging to the this set are processed */
228
229 private:
230 /**
231 * Start a scanning procedure. This method needs to schedule a call to
232 * ScanningTimeout when the scanning procedure is completed.
233 */
234 virtual void DoStartScanning() = 0;
235
236 WifiScanParams m_scanParams; ///< scanning parameters
237 SortedList m_apList; ///< sorted list of candidate APs
238 /// hash table to help locate ApInfo objects in the sorted list based on the BSSID
239 std::unordered_map<Mac48Address, SortedList::const_iterator, WifiAddressHash> m_apListIt;
240};
241
242} // namespace ns3
243
244#endif /* WIFI_ASSOC_MANAGER_H */
A base class which provides memory management and object aggregation.
Definition object.h:78
Smart pointer class similar to boost::intrusive_ptr.
The Reduced Neighbor Report element.
a unique identifier for an interface.
Definition type-id.h:48
Abstract base class for the Association Manager, which manages scanning and association for single li...
const SortedList & GetSortedList() const
virtual void NotifyChannelSwitched(uint8_t linkId)=0
Notify that the given link has completed channel switching.
virtual void NotifyApInfo(const StaWifiMac::ApInfo &&apInfo)
STA wifi MAC received a Beacon frame or Probe Response frame while scanning and notifies us the AP in...
Ptr< StaWifiMac > m_mac
pointer to the STA wifi MAC
virtual void DoStartScanning()=0
Start a scanning procedure.
void SetStaWifiMac(Ptr< StaWifiMac > mac)
Set the pointer to the STA wifi MAC.
std::optional< std::reference_wrapper< const MultiLinkElement > > OptMleConstRef
typedef for an optional const reference to a MultiLinkElement object
std::list< StaWifiMac::ApInfo::SetupLinksInfo > & GetSetupLinks(const StaWifiMac::ApInfo &apInfo)
Get a reference to the list of the links to setup with the given AP.
std::optional< std::reference_wrapper< const ReducedNeighborReport > > OptRnrConstRef
typedef for an optional const reference to a ReducedNeighborReport object
void ScanningTimeout()
Extract the best AP to associate with from the sorted list and return it, if any, to the STA wifi MAC...
virtual bool CanBeInserted(const StaWifiMac::ApInfo &apInfo) const =0
Allow subclasses to choose whether the given ApInfo shall be considered and hence inserted in the sor...
SortedList m_apList
sorted list of candidate APs
static std::optional< WifiAssocManager::RnrLinkInfo > GetNextAffiliatedAp(const ReducedNeighborReport &rnr, std::size_t nbrApInfoId)
Search the given RNR element for APs affiliated to the same AP MLD as the reporting AP.
WifiScanParams m_scanParams
scanning parameters
virtual bool CanBeReturned(const StaWifiMac::ApInfo &apInfo) const =0
Allow subclasses to choose whether the given ApInfo shall be returned or discarded when the STA wifi ...
void StartScanning(WifiScanParams &&scanParams)
Request the Association Manager to start a scanning procedure according to the given scanning paramet...
std::set< StaWifiMac::ApInfo, ApInfoCompare > SortedList
typedef for the sorted list of ApInfo objects
std::set< uint8_t > m_allowedLinks
"Only Beacon and Probe Response frames received on a link belonging to the this set are processed
virtual bool Compare(const StaWifiMac::ApInfo &lhs, const StaWifiMac::ApInfo &rhs) const =0
Compare two ApInfo objects for the purpose of keeping a sorted list of ApInfo objects.
static std::list< WifiAssocManager::RnrLinkInfo > GetAllAffiliatedAps(const ReducedNeighborReport &rnr)
Find all the APs affiliated to the same AP MLD as the reporting AP that sent the given RNR element.
static TypeId GetTypeId()
Get the type ID.
const WifiScanParams & GetScanParams() const
void DoDispose() override
Destructor implementation.
std::unordered_map< Mac48Address, SortedList::const_iterator, WifiAddressHash > m_apListIt
hash table to help locate ApInfo objects in the sorted list based on the BSSID
bool CanSetupMultiLink(OptMleConstRef &mle, OptRnrConstRef &rnr)
Check whether 11be Multi-Link setup can be established with the current best AP.
WifiAssocManager()
Constructor (protected as this is an abstract base class)
bool MatchScanParams(const StaWifiMac::ApInfo &apInfo) const
Check whether the given AP information match the current scanning parameters.
Every class exported by the ns3 library is enclosed in the ns3 namespace.
Struct to hold information regarding observed AP through active/passive scanning.
Struct providing a function call operator to compare two ApInfo objects.
const WifiAssocManager & m_manager
Association Manager.
ApInfoCompare(const WifiAssocManager &manager)
Constructor.
bool operator()(const StaWifiMac::ApInfo &lhs, const StaWifiMac::ApInfo &rhs) const
Function call operator.
Structure holding scan parameters.