blob: cd0d041193688a9d0e9540e6e3bb2866c3f58918 [file] [log] [blame]
Alexander Afanasyev2b4c9472012-08-09 15:00:38 -07001/* -*- Mode:C++; c-file-style:"gnu"; indent-tabs-mode:nil -*- */
2/*
3 * Copyright (c) 2011 University of California, Los Angeles
4 *
5 * This program is free software; you can redistribute it and/or modify
6 * it under the terms of the GNU General Public License version 2 as
7 * published by the Free Software Foundation;
8 *
9 * This program is distributed in the hope that it will be useful,
10 * but WITHOUT ANY WARRANTY; without even the implied warranty of
11 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
12 * GNU General Public License for more details.
13 *
14 * You should have received a copy of the GNU General Public License
15 * along with this program; if not, write to the Free Software
16 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
17 *
18 * Author: Alexander Afanasyev <alexander.afanasyev@ucla.edu>
Alexander Afanasyev2b4c9472012-08-09 15:00:38 -070019 */
Alexander Afanasyev31cb4692012-08-17 13:08:20 -070020
Alexander Afanasyev2b4c9472012-08-09 15:00:38 -070021#ifndef NDN_FORWARDING_STRATEGY_H
22#define NDN_FORWARDING_STRATEGY_H
23
24#include "ns3/packet.h"
25#include "ns3/callback.h"
26#include "ns3/object.h"
27#include "ns3/traced-callback.h"
28
29namespace ns3 {
30namespace ndn {
31
32class Face;
33class InterestHeader;
34class ContentObjectHeader;
35class Pit;
36namespace pit { class Entry; }
37class FibFaceMetric;
38class Fib;
39class ContentStore;
40
41/**
42 * \ingroup ndn
43 * \brief Abstract base class for Ndn forwarding strategies
44 */
45class ForwardingStrategy :
46 public Object
47{
48public:
49 static TypeId GetTypeId (void);
50
51 /**
Alexander Afanasyev042b4a72012-11-09 17:47:48 -080052 * @brief Helper function to retrieve logging name for the forwarding strategy
53 */
54 static std::string GetLogName ();
55
56 /**
Alexander Afanasyev2b4c9472012-08-09 15:00:38 -070057 * @brief Default constructor
58 */
59 ForwardingStrategy ();
60 virtual ~ForwardingStrategy ();
61
62 /**
63 * \brief Actual processing of incoming Ndn interests. Note, interests do not have payload
64 *
65 * Processing Interest packets
66 * @param face incoming face
67 * @param header deserialized Interest header
Alexander Afanasyev31cb4692012-08-17 13:08:20 -070068 * @param origPacket original packet
Alexander Afanasyev2b4c9472012-08-09 15:00:38 -070069 */
70 virtual void
Alexander Afanasyev31cb4692012-08-17 13:08:20 -070071 OnInterest (Ptr<Face> face,
72 Ptr<const InterestHeader> header,
73 Ptr<const Packet> origPacket);
Alexander Afanasyev2b4c9472012-08-09 15:00:38 -070074
75 /**
76 * \brief Actual processing of incoming Ndn content objects
77 *
78 * Processing ContentObject packets
79 * @param face incoming face
80 * @param header deserialized ContentObject header
81 * @param payload data packet payload
Alexander Afanasyev31cb4692012-08-17 13:08:20 -070082 * @param origPacket original packet
Alexander Afanasyev2b4c9472012-08-09 15:00:38 -070083 */
84 virtual void
Alexander Afanasyev31cb4692012-08-17 13:08:20 -070085 OnData (Ptr<Face> face,
86 Ptr<const ContentObjectHeader> header,
87 Ptr<Packet> payload,
88 Ptr<const Packet> origPacket);
Alexander Afanasyev2b4c9472012-08-09 15:00:38 -070089
Alexander Afanasyevea9b3e62012-08-13 19:02:54 -070090 /**
91 * @brief Event fired just before PIT entry is removed by timeout
92 * @param pitEntry PIT entry to be removed
93 */
Alexander Afanasyev2b4c9472012-08-09 15:00:38 -070094 virtual void
Alexander Afanasyevea9b3e62012-08-13 19:02:54 -070095 WillEraseTimedOutPendingInterest (Ptr<pit::Entry> pitEntry);
Alexander Afanasyev2b4c9472012-08-09 15:00:38 -070096
Alexander Afanasyevea9b3e62012-08-13 19:02:54 -070097 /**
Alexander Afanasyevf5c07742012-10-31 13:13:05 -070098 * @brief Event fired every time face is added to NDN stack
99 * @param face face to be removed
100 */
101 virtual void
102 AddFace (Ptr<Face> face);
103
104 /**
Alexander Afanasyevea9b3e62012-08-13 19:02:54 -0700105 * @brief Event fired every time face is removed from NDN stack
106 * @param face face to be removed
107 *
108 * For example, when an application terminates, AppFace is removed and this method called by NDN stack.
109 */
Alexander Afanasyev2b4c9472012-08-09 15:00:38 -0700110 virtual void
111 RemoveFace (Ptr<Face> face);
112
113protected:
Alexander Afanasyev6466fff2012-10-24 22:51:57 -0700114 /**
115 * @brief An event that is fired every time a new PIT entry is created
116 *
117 * Note that if NDN node is receiving a similar interest (interest for the same name),
118 * then either DidReceiveDuplicateInterest, DidSuppressSimilarInterest, or DidForwardSimilarInterest
119 * will be called
120 *
121 * Suppression of similar Interests is controlled using ShouldSuppressIncomingInterest virtual method
122 *
123 * @param inFace incoming face
124 * @param header deserialized Interest header
125 * @param origPacket original packet
126 * @param pitEntry created PIT entry (incoming and outgoing face sets are empty)
127 *
128 * @see DidReceiveDuplicateInterest, DidSuppressSimilarInterest, DidForwardSimilarInterest, ShouldSuppressIncomingInterest
129 */
130 virtual void
131 DidCreatePitEntry (Ptr<Face> inFace,
132 Ptr<const InterestHeader> header,
133 Ptr<const Packet> origPacket,
134 Ptr<pit::Entry> pitEntry);
135
136 /**
137 * @brief An event that is fired every time a new PIT entry cannot be created (e.g., PIT container imposes a limit)
138 *
139 * Note that this call can be called only for non-similar Interest (i.e., there is an attempt to create a new PIT entry).
140 * For any non-similar Interests, either FailedToCreatePitEntry or DidCreatePitEntry is called.
141 *
142 * @param inFace incoming face
143 * @param header deserialized Interest header
144 * @param origPacket original packet
145 */
146 virtual void
147 FailedToCreatePitEntry (Ptr<Face> inFace,
148 Ptr<const InterestHeader> header,
149 Ptr<const Packet> origPacket);
150
151 /**
152 * @brief An event that is fired every time a duplicated Interest is received
153 *
154 * This even is the last action that is performed before the Interest processing is halted
155 *
156 * @param inFace incoming face
157 * @param header deserialized Interest header
158 * @param origPacket original packet
159 * @param pitEntry an existing PIT entry, corresponding to the duplicated Interest
160 *
161 * @see DidReceiveDuplicateInterest, DidSuppressSimilarInterest, DidForwardSimilarInterest, ShouldSuppressIncomingInterest
162 */
Alexander Afanasyev2b4c9472012-08-09 15:00:38 -0700163 virtual void
Alexander Afanasyev31cb4692012-08-17 13:08:20 -0700164 DidReceiveDuplicateInterest (Ptr<Face> inFace,
165 Ptr<const InterestHeader> header,
166 Ptr<const Packet> origPacket,
Alexander Afanasyev2b4c9472012-08-09 15:00:38 -0700167 Ptr<pit::Entry> pitEntry);
168
Alexander Afanasyev6466fff2012-10-24 22:51:57 -0700169 /**
170 * @brief An event that is fired every time when a similar Interest is received and suppressed (collapsed)
171 *
172 * This even is the last action that is performed before the Interest processing is halted
173 *
174 * @param inFace incoming face
175 * @param header deserialized Interest header
176 * @param origPacket original packet
177 * @param pitEntry an existing PIT entry, corresponding to the duplicated Interest
178 *
179 * @see DidReceiveDuplicateInterest, DidForwardSimilarInterest, ShouldSuppressIncomingInterest
180 */
181 virtual void
182 DidSuppressSimilarInterest (Ptr<Face> inFace,
183 Ptr<const InterestHeader> header,
184 Ptr<const Packet> origPacket,
185 Ptr<pit::Entry> pitEntry);
186
187 /**
188 * @brief An event that is fired every time when a similar Interest is received and further forwarded (not suppressed/collapsed)
189 *
190 * This even is fired just before handling the Interest to PropagateInterest method
191 *
192 * @param inFace incoming face
193 * @param header deserialized Interest header
194 * @param origPacket original packet
195 * @param pitEntry an existing PIT entry, corresponding to the duplicated Interest
196 *
197 * @see DidReceiveDuplicateInterest, DidSuppressSimilarInterest, ShouldSuppressIncomingInterest
198 */
199 virtual void
200 DidForwardSimilarInterest (Ptr<Face> inFace,
201 Ptr<const InterestHeader> header,
202 Ptr<const Packet> origPacket,
203 Ptr<pit::Entry> pitEntry);
204
205 /**
206 * @brief An even that is fired when Interest cannot be forwarded
207 *
208 * Note that the event will not fire if retransmission detection is enabled (by default)
209 * and retransmitted Interest cannot by forwarded. For more details, refer to the implementation.
210 *
211 * @param inFace incoming face
212 * @param header deserialized Interest header
213 * @param origPacket original packet
214 * @param pitEntry an existing PIT entry, corresponding to the duplicated Interest
215 *
216 * @see DetectRetransmittedInterest
217 */
Alexander Afanasyev2b4c9472012-08-09 15:00:38 -0700218 virtual void
Alexander Afanasyev31cb4692012-08-17 13:08:20 -0700219 DidExhaustForwardingOptions (Ptr<Face> inFace,
220 Ptr<const InterestHeader> header,
221 Ptr<const Packet> origPacket,
Alexander Afanasyev2b4c9472012-08-09 15:00:38 -0700222 Ptr<pit::Entry> pitEntry);
223
Alexander Afanasyevdb15acb2012-11-09 14:16:27 -0800224 /**
225 * @brief Method that implements logic to distinguish between new and retransmitted interest
226 *
227 * This method is called only when DetectRetransmissions attribute is set true (by default).
228 *
229 * Currently, the retransmission detection logic relies on the fact that list of incoming faces
230 * already has inFace (i.e., a similar interest is received on the same face more than once).
231 *
232 * @param inFace incoming face
233 * @param header deserialized Interest header
234 * @param origPacket original packet
235 * @param pitEntry an existing PIT entry, corresponding to the duplicated Interest
236 * @return true if Interest should be considered as retransmitted
237 */
Alexander Afanasyev2b4c9472012-08-09 15:00:38 -0700238 virtual bool
Alexander Afanasyev31cb4692012-08-17 13:08:20 -0700239 DetectRetransmittedInterest (Ptr<Face> inFace,
240 Ptr<const InterestHeader> header,
241 Ptr<const Packet> origPacket,
Alexander Afanasyev2b4c9472012-08-09 15:00:38 -0700242 Ptr<pit::Entry> pitEntry);
243
Alexander Afanasyevdb15acb2012-11-09 14:16:27 -0800244 /**
245 * @brief Even fired just before Interest will be satisfied
246 *
247 * Note that when Interest is satisfied from the cache, incoming face will be 0
248 *
249 * @param inFace incoming face
250 * @param pitEntry an existing PIT entry, corresponding to the duplicated Interest
251 */
Alexander Afanasyev2b4c9472012-08-09 15:00:38 -0700252 virtual void
Alexander Afanasyev31cb4692012-08-17 13:08:20 -0700253 WillSatisfyPendingInterest (Ptr<Face> inFace,
Alexander Afanasyev2b4c9472012-08-09 15:00:38 -0700254 Ptr<pit::Entry> pitEntry);
255
Alexander Afanasyevdb15acb2012-11-09 14:16:27 -0800256 /**
257 * @brief Actual procedure to satisfy Interest
258 *
259 * Note that when Interest is satisfied from the cache, incoming face will be 0
260 *
261 * @param inFace incoming face
262 * @param header deserialized ContentObject header
263 * @param payload ContentObject payload
264 * @param origPacket original packet
265 * @param pitEntry an existing PIT entry, corresponding to the duplicated Interest
266 */
Alexander Afanasyev2b4c9472012-08-09 15:00:38 -0700267 virtual void
Alexander Afanasyev31cb4692012-08-17 13:08:20 -0700268 SatisfyPendingInterest (Ptr<Face> inFace, // 0 allowed (from cache)
Alexander Afanasyev2b4c9472012-08-09 15:00:38 -0700269 Ptr<const ContentObjectHeader> header,
270 Ptr<const Packet> payload,
Alexander Afanasyev31cb4692012-08-17 13:08:20 -0700271 Ptr<const Packet> origPacket,
Alexander Afanasyev2b4c9472012-08-09 15:00:38 -0700272 Ptr<pit::Entry> pitEntry);
273
Alexander Afanasyevdb15acb2012-11-09 14:16:27 -0800274 /**
275 * @brief Event which is fired just after data was send out on the face
276 *
277 * @param outFace outgoing face
278 * @param header deserialized ContentObject header
279 * @param payload ContentObject payload
280 * @param origPacket original packet
281 * @param pitEntry an existing PIT entry, corresponding to the duplicated Interest
282 */
Alexander Afanasyev2b4c9472012-08-09 15:00:38 -0700283 virtual void
Alexander Afanasyevdb15acb2012-11-09 14:16:27 -0800284 DidSendOutData (Ptr<Face> outFace,
Alexander Afanasyev2b4c9472012-08-09 15:00:38 -0700285 Ptr<const ContentObjectHeader> header,
286 Ptr<const Packet> payload,
Alexander Afanasyev31cb4692012-08-17 13:08:20 -0700287 Ptr<const Packet> origPacket,
288 Ptr<pit::Entry> pitEntry);
Alexander Afanasyevdb15acb2012-11-09 14:16:27 -0800289
290 /**
291 * @brief Event which is fired every time an unsolicited DATA packet (no active PIT entry) is received
292 *
293 * The current implementation allows ignoring unsolicited DATA (by default), or cache it by setting
294 * attribute CacheUnsolicitedData true
295 *
296 * @param inFace incoming face
297 * @param header deserialized ContentObject header
298 * @param payload ContentObject payload
299 * @param origPacket original packet
300 */
Alexander Afanasyev2b4c9472012-08-09 15:00:38 -0700301 virtual void
Alexander Afanasyev31cb4692012-08-17 13:08:20 -0700302 DidReceiveUnsolicitedData (Ptr<Face> inFace,
Alexander Afanasyev2b4c9472012-08-09 15:00:38 -0700303 Ptr<const ContentObjectHeader> header,
Alexander Afanasyev31cb4692012-08-17 13:08:20 -0700304 Ptr<const Packet> payload,
305 Ptr<const Packet> origPacket);
Alexander Afanasyevdb15acb2012-11-09 14:16:27 -0800306
307 /**
308 * @brief Method implementing logic to suppress (collapse) similar Interests
309 *
310 * In the base class implementation this method checks list of incoming/outgoing faces of the PIT entry
311 * (for new Intersets, both lists are empty before this call)
312 *
313 * For more details, refer to the source code.
314 *
315 * @param inFace incoming face
316 * @param header deserialized ContentObject header
317 * @param payload ContentObject payload
318 * @param origPacket original packet
319 */
Alexander Afanasyev2b4c9472012-08-09 15:00:38 -0700320 virtual bool
Alexander Afanasyev31cb4692012-08-17 13:08:20 -0700321 ShouldSuppressIncomingInterest (Ptr<Face> inFace,
322 Ptr<const InterestHeader> header,
323 Ptr<const Packet> origPacket,
Alexander Afanasyev2b4c9472012-08-09 15:00:38 -0700324 Ptr<pit::Entry> pitEntry);
325
326 /**
Alexander Afanasyevdb15acb2012-11-09 14:16:27 -0800327 * @brief Method to check whether Interest can be send out on the particular face or not
Alexander Afanasyev2b4c9472012-08-09 15:00:38 -0700328 *
Alexander Afanasyevdb15acb2012-11-09 14:16:27 -0800329 * In the base class, this method perfoms two checks:
330 * 1. If inFace is equal to outFace (when equal, Interest forwarding is prohibited)
331 * 2. Whether Interest should be suppressed (list of outgoing faces include outFace),
332 * considering (if enabled) retransmission logic
333 *
334 * @param inFace incoming face of the Interest
335 * @param outFace proposed outgoing face of the Interest
336 * @param header parsed Interest header
337 * @param origPacket original Interest packet
338 * @param pitEntry reference to PIT entry (reference to corresponding FIB entry inside)
339 *
340 * @see DetectRetransmittedInterest
341 */
342 virtual bool
343 CanSendOutInterest (Ptr<Face> inFace,
344 Ptr<Face> outFace,
345 Ptr<const InterestHeader> header,
346 Ptr<const Packet> origPacket,
347 Ptr<pit::Entry> pitEntry);
348
349 /**
350 * @brief Method implementing actual interest forwarding, taking into account CanSendOutInterest decision
351 *
352 * If event returns false, then there is some kind of a problem exists
353 *
354 * @param inFace incoming face of the Interest
355 * @param outFace proposed outgoing face of the Interest
356 * @param header parsed Interest header
357 * @param origPacket original Interest packet
358 * @param pitEntry reference to PIT entry (reference to corresponding FIB entry inside)
359 *
360 * @see CanSendOutInterest
Alexander Afanasyev2b4c9472012-08-09 15:00:38 -0700361 */
362 virtual bool
Alexander Afanasyev5db92172012-08-21 16:52:07 -0700363 TrySendOutInterest (Ptr<Face> inFace,
364 Ptr<Face> outFace,
365 Ptr<const InterestHeader> header,
366 Ptr<const Packet> origPacket,
367 Ptr<pit::Entry> pitEntry);
Alexander Afanasyev2b4c9472012-08-09 15:00:38 -0700368
369 /**
Alexander Afanasyevdb15acb2012-11-09 14:16:27 -0800370 * @brief Event fired just after forwarding the Interest
371 *
372 * @param outFace outgoing face of the Interest
373 * @param header parsed Interest header
374 * @param origPacket original Interest packet
375 * @param pitEntry reference to PIT entry (reference to corresponding FIB entry inside)
Alexander Afanasyev2b4c9472012-08-09 15:00:38 -0700376 */
377 virtual void
Alexander Afanasyev31cb4692012-08-17 13:08:20 -0700378 DidSendOutInterest (Ptr<Face> outFace,
379 Ptr<const InterestHeader> header,
380 Ptr<const Packet> origPacket,
Alexander Afanasyev2b4c9472012-08-09 15:00:38 -0700381 Ptr<pit::Entry> pitEntry);
382
Alexander Afanasyev6466fff2012-10-24 22:51:57 -0700383 /**
384 * @brief Wrapper method, which performs general tasks and calls DoPropagateInterest method
385 *
386 * General tasks so far are adding face to the list of incoming face, updating
387 * PIT entry lifetime, calling DoPropagateInterest, and retransmissions (enabled by default).
388 *
389 * @param inFace incoming face
390 * @param header Interest header
391 * @param origPacket original Interest packet
392 * @param pitEntry reference to PIT entry (reference to corresponding FIB entry inside)
393 *
394 * @see DoPropagateInterest
395 */
Alexander Afanasyev2b4c9472012-08-09 15:00:38 -0700396 virtual void
Alexander Afanasyev31cb4692012-08-17 13:08:20 -0700397 PropagateInterest (Ptr<Face> inFace,
398 Ptr<const InterestHeader> header,
399 Ptr<const Packet> origPacket,
Alexander Afanasyev2b4c9472012-08-09 15:00:38 -0700400 Ptr<pit::Entry> pitEntry);
401
402 /**
Alexander Afanasyev6466fff2012-10-24 22:51:57 -0700403 * @brief Virtual method to perform Interest propagation according to the forwarding strategy logic
Alexander Afanasyev2b4c9472012-08-09 15:00:38 -0700404 *
Alexander Afanasyev6466fff2012-10-24 22:51:57 -0700405 * In most cases, this is the call that needs to be implemented/re-implemented in order
406 * to perform forwarding of Interests according to the desired logic.
407 *
408 * There is also PropagateInterest method (generally, do not require to be overriden)
409 * which performs general tasks (adding face to the list of incoming face, updating
410 * PIT entry lifetime, calling DoPropagateInterest, as well as perform retransmissions (enabled by default).
411 *
412 * @param inFace incoming face
413 * @param header Interest header
414 * @param origPacket original Interest packet
415 * @param pitEntry reference to PIT entry (reference to corresponding FIB entry inside)
Alexander Afanasyev2b4c9472012-08-09 15:00:38 -0700416 *
417 * @return true if interest was successfully propagated, false if all options have failed
Alexander Afanasyev6466fff2012-10-24 22:51:57 -0700418 *
419 * @see PropagateInterest
Alexander Afanasyev2b4c9472012-08-09 15:00:38 -0700420 */
421 virtual bool
Alexander Afanasyev31cb4692012-08-17 13:08:20 -0700422 DoPropagateInterest (Ptr<Face> inFace,
423 Ptr<const InterestHeader> header,
424 Ptr<const Packet> origPacket,
Alexander Afanasyev2b4c9472012-08-09 15:00:38 -0700425 Ptr<pit::Entry> pitEntry) = 0;
426
427protected:
428 // inherited from Object class
429 virtual void NotifyNewAggregate (); ///< @brief Even when object is aggregated to another Object
430 virtual void DoDispose (); ///< @brief Do cleanup
431
432protected:
433 Ptr<Pit> m_pit; ///< \brief Reference to PIT to which this forwarding strategy is associated
434 Ptr<Fib> m_fib; ///< \brief FIB
435 Ptr<ContentStore> m_contentStore; ///< \brief Content store (for caching purposes only)
436
437 bool m_cacheUnsolicitedData;
438 bool m_detectRetransmissions;
439
440 TracedCallback<Ptr<const InterestHeader>,
441 Ptr<const Face> > m_outInterests; ///< @brief Transmitted interests trace
442
443 TracedCallback<Ptr<const InterestHeader>,
444 Ptr<const Face> > m_inInterests; ///< @brief trace of incoming Interests
445
446 TracedCallback<Ptr<const InterestHeader>,
447 Ptr<const Face> > m_dropInterests; ///< @brief trace of dropped Interests
448
449 ////////////////////////////////////////////////////////////////////
450 ////////////////////////////////////////////////////////////////////
451 ////////////////////////////////////////////////////////////////////
452
453 TracedCallback<Ptr<const ContentObjectHeader>, Ptr<const Packet>,
454 bool /*from cache*/,
455 Ptr<const Face> > m_outData; ///< @brief trace of outgoing Data
456
457 TracedCallback<Ptr<const ContentObjectHeader>, Ptr<const Packet>,
458 Ptr<const Face> > m_inData; ///< @brief trace of incoming Data
459
460 TracedCallback<Ptr<const ContentObjectHeader>, Ptr<const Packet>,
461 Ptr<const Face> > m_dropData; ///< @brief trace of dropped Data
462};
463
464} // namespace ndn
465} // namespace ns3
466
467#endif /* NDN_FORWARDING_STRATEGY_H */