blob: a166a7bd3d8977869da2047c59f950934c519cad [file] [log] [blame]
Alexander Afanasyevc74a6022011-08-15 20:01:35 -07001/* -*- Mode:C++; c-file-style:"gnu"; indent-tabs-mode:nil -*- */
Alexander Afanasyev08d984e2011-08-13 19:20:22 -07002/*
Ilya Moiseenko956d0542012-01-02 15:26:40 -08003 * Copyright (c) 2011 University of California, Los Angeles
Alexander Afanasyev08d984e2011-08-13 19:20:22 -07004 *
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 *
Alexander Afanasyev56f79ea2011-08-17 23:54:27 -070018 * Authors: Alexander Afanasyev <alexander.afanasyev@ucla.edu>
Alexander Afanasyev08d984e2011-08-13 19:20:22 -070019 */
Alexander Afanasyev56f79ea2011-08-17 23:54:27 -070020
Alexander Afanasyev4aac5572012-08-09 10:49:55 -070021#ifndef NDN_FACE_H
22#define NDN_FACE_H
Alexander Afanasyev08d984e2011-08-13 19:20:22 -070023
Alexander Afanasyev98256102011-08-14 01:00:02 -070024#include <ostream>
Alexander Afanasyev19426ef2011-11-23 20:55:28 -080025#include <algorithm>
Alexander Afanasyev98256102011-08-14 01:00:02 -070026
Alexander Afanasyev08d984e2011-08-13 19:20:22 -070027#include "ns3/ptr.h"
Alexander Afanasyevcf6dc922012-08-10 16:55:27 -070028#include "ns3/object.h"
Alexander Afanasyev19426ef2011-11-23 20:55:28 -080029#include "ns3/nstime.h"
Alexander Afanasyev7f3e49e2012-04-30 00:17:07 -070030#include "ns3/type-id.h"
Alexander Afanasyevcf6dc922012-08-10 16:55:27 -070031#include "ns3/traced-callback.h"
Alexander Afanasyeva89bc102013-07-16 10:17:31 -070032#include "ns3/ndn-name.h"
Alexander Afanasyev08d984e2011-08-13 19:20:22 -070033
34namespace ns3 {
35
Alexander Afanasyev08d984e2011-08-13 19:20:22 -070036class Packet;
37class Node;
Alexander Afanasyev2b4c9472012-08-09 15:00:38 -070038
39namespace ndn {
40
Alexander Afanasyev5bee19e2013-07-10 14:33:57 -070041class Interest;
Alexander Afanasyev772f51b2013-08-01 18:53:25 -070042class Data;
Alexander Afanasyev5bee19e2013-07-10 14:33:57 -070043
Alexander Afanasyev08d984e2011-08-13 19:20:22 -070044/**
Alexander Afanasyev4aac5572012-08-09 10:49:55 -070045 * \ingroup ndn
46 * \defgroup ndn-face Faces
Alexander Afanasyev56f79ea2011-08-17 23:54:27 -070047 */
48/**
Alexander Afanasyev4aac5572012-08-09 10:49:55 -070049 * \ingroup ndn-face
Alexander Afanasyev2b4c9472012-08-09 15:00:38 -070050 * \brief Virtual class defining NDN face
Alexander Afanasyev08d984e2011-08-13 19:20:22 -070051 *
Alexander Afanasyev2b4c9472012-08-09 15:00:38 -070052 * This class defines basic functionality of NDN face. Face is core
Alexander Afanasyevab1d5602011-08-17 19:17:18 -070053 * component responsible for actual delivery of data packet to and
Alexander Afanasyev2b4c9472012-08-09 15:00:38 -070054 * from NDN stack
Alexander Afanasyev08d984e2011-08-13 19:20:22 -070055 *
Alexander Afanasyevc57a8772013-03-16 11:55:20 -070056 * \see ndn::AppFace, ndn::NetDeviceFace
Alexander Afanasyev08d984e2011-08-13 19:20:22 -070057 */
Alexander Afanasyevcf6dc922012-08-10 16:55:27 -070058class Face :
59 public Object
Alexander Afanasyev08d984e2011-08-13 19:20:22 -070060{
61public:
Alexander Afanasyevbdc0d982011-12-16 01:15:26 -080062 static TypeId
63 GetTypeId ();
Alexander Afanasyevdd9fa4f2013-05-15 16:35:04 -070064
Alexander Afanasyevab1d5602011-08-17 19:17:18 -070065 /**
Alexander Afanasyev5bee19e2013-07-10 14:33:57 -070066 * \brief NDN protocol handlers
Alexander Afanasyevab1d5602011-08-17 19:17:18 -070067 *
68 * \param face Face from which packet has been received
Alexander Afanasyev09c7deb2011-11-23 14:50:10 -080069 * \param packet Original packet
Alexander Afanasyevab1d5602011-08-17 19:17:18 -070070 */
Alexander Afanasyevb989b122013-07-10 17:15:46 -070071 typedef Callback<void, Ptr<Face>, Ptr<Interest> > InterestHandler;
Alexander Afanasyev772f51b2013-08-01 18:53:25 -070072 typedef Callback<void, Ptr<Face>, Ptr<Data> > DataHandler;
Alexander Afanasyev08d984e2011-08-13 19:20:22 -070073
Alexander Afanasyevab1d5602011-08-17 19:17:18 -070074 /**
75 * \brief Default constructor
76 */
Alexander Afanasyev2b4c9472012-08-09 15:00:38 -070077 Face (Ptr<Node> node);
78 virtual ~Face();
Alexander Afanasyev08d984e2011-08-13 19:20:22 -070079
Alexander Afanasyevb4fee8b2012-06-06 12:54:26 -070080 /**
81 * @brief Get node to which this face is associated
82 */
Alexander Afanasyeve9c9d722012-01-19 16:59:30 -080083 Ptr<Node>
84 GetNode () const;
85
Alexander Afanasyevab1d5602011-08-17 19:17:18 -070086 ////////////////////////////////////////////////////////////////////
Alexander Afanasyevdd9fa4f2013-05-15 16:35:04 -070087
Alexander Afanasyev08d984e2011-08-13 19:20:22 -070088 /**
Alexander Afanasyevab1d5602011-08-17 19:17:18 -070089 * \brief Register callback to call when new packet arrives on the face
Alexander Afanasyev08d984e2011-08-13 19:20:22 -070090 *
Alexander Afanasyevab1d5602011-08-17 19:17:18 -070091 * This method should call protocol-dependent registration function
92 */
Alexander Afanasyev09c7deb2011-11-23 14:50:10 -080093 virtual void
Alexander Afanasyev5bee19e2013-07-10 14:33:57 -070094 RegisterProtocolHandlers (const InterestHandler &interestHandler, const DataHandler &dataHandler);
Alexander Afanasyevab1d5602011-08-17 19:17:18 -070095
96 /**
Alexander Afanasyev5bee19e2013-07-10 14:33:57 -070097 * \brief Un-Register callback to call when new packet arrives on the face
Alexander Afanasyevab1d5602011-08-17 19:17:18 -070098 *
Alexander Afanasyev5bee19e2013-07-10 14:33:57 -070099 * This method should call protocol-dependent registration function
Alexander Afanasyevdd9fa4f2013-05-15 16:35:04 -0700100 */
Alexander Afanasyev5bee19e2013-07-10 14:33:57 -0700101 virtual void
102 UnRegisterProtocolHandlers ();
Alexander Afanasyev09c7deb2011-11-23 14:50:10 -0800103
104 /**
Alexander Afanasyev5bee19e2013-07-10 14:33:57 -0700105 * @brief Send out interest through the face
106 * @param interest Interest to send out
107 * @param packet "payload" that is attached to the interest (can carry some packet tags)
Alexander Afanasyev09c7deb2011-11-23 14:50:10 -0800108 *
Alexander Afanasyev5bee19e2013-07-10 14:33:57 -0700109 * @returns true if interest is considered to be send out (enqueued)
Alexander Afanasyevab1d5602011-08-17 19:17:18 -0700110 */
Alexander Afanasyev5bee19e2013-07-10 14:33:57 -0700111 virtual bool
Alexander Afanasyevb989b122013-07-10 17:15:46 -0700112 SendInterest (Ptr<const Interest> interest);
Alexander Afanasyev5bee19e2013-07-10 14:33:57 -0700113
114 /**
115 * @brief Send out Dat packet through the face
116 * @param data Data packet to send out
117 * @param packet Data packet payload, can also carry packet tags
118 *
119 * @returns true if Data packet is considered to be send out (enqueued)
120 */
121 virtual bool
Alexander Afanasyev772f51b2013-08-01 18:53:25 -0700122 SendData (Ptr<const Data> data);
Alexander Afanasyev5bee19e2013-07-10 14:33:57 -0700123
124 /**
125 * \brief Receive interest from application or another node and forward it up to the NDN stack
126 *
127 * By default it is called from inside Receive method, but can be used directly, if appropriate
128 */
129 virtual bool
Alexander Afanasyevb989b122013-07-10 17:15:46 -0700130 ReceiveInterest (Ptr<Interest> interest);
Alexander Afanasyev5bee19e2013-07-10 14:33:57 -0700131
132 /**
133 * \brief Receive Data packet from application or another node and forward it up to the NDN stack
134 *
135 * By default it is called from inside Receive method, but can be used directly, if appropriate
136 */
137 virtual bool
Alexander Afanasyev772f51b2013-08-01 18:53:25 -0700138 ReceiveData (Ptr<Data> data);
Alexander Afanasyev09c7deb2011-11-23 14:50:10 -0800139 ////////////////////////////////////////////////////////////////////
Alexander Afanasyevab1d5602011-08-17 19:17:18 -0700140
Alexander Afanasyev8e0d2812012-01-19 22:38:14 -0800141 /**
Alexander Afanasyev042b4a72012-11-09 17:47:48 -0800142 * \brief Assign routing/forwarding metric with face
Alexander Afanasyev8e0d2812012-01-19 22:38:14 -0800143 *
144 * \param metric configured routing metric (cost) of this face
145 */
Alexander Afanasyevdd9fa4f2013-05-15 16:35:04 -0700146 virtual void
147 SetMetric (uint16_t metric);
Alexander Afanasyev08d984e2011-08-13 19:20:22 -0700148
Alexander Afanasyev8e0d2812012-01-19 22:38:14 -0800149 /**
150 * \brief Get routing/forwarding metric assigned to the face
151 *
152 * \returns configured routing/forwarding metric (cost) of this face
153 */
Alexander Afanasyevdd9fa4f2013-05-15 16:35:04 -0700154 virtual uint16_t
155 GetMetric (void) const;
Alexander Afanasyev08d984e2011-08-13 19:20:22 -0700156
157 /**
Alexander Afanasyevab1d5602011-08-17 19:17:18 -0700158 * These are face states and may be distinct from actual lower-layer
159 * device states, such as found in real implementations (where the
Alexander Afanasyev4aac5572012-08-09 10:49:55 -0700160 * device may be down but ndn face state is still up).
Alexander Afanasyev08d984e2011-08-13 19:20:22 -0700161 */
Alexander Afanasyevdd9fa4f2013-05-15 16:35:04 -0700162
Alexander Afanasyev08d984e2011-08-13 19:20:22 -0700163 /**
Alexander Afanasyev09c7deb2011-11-23 14:50:10 -0800164 * \brief Enable or disable this face
Alexander Afanasyev08d984e2011-08-13 19:20:22 -0700165 */
Alexander Afanasyev5bee19e2013-07-10 14:33:57 -0700166 inline void
Alexander Afanasyev09c7deb2011-11-23 14:50:10 -0800167 SetUp (bool up = true);
Alexander Afanasyev08d984e2011-08-13 19:20:22 -0700168
169 /**
Alexander Afanasyevab1d5602011-08-17 19:17:18 -0700170 * \brief Returns true if this face is enabled, false otherwise.
171 */
Alexander Afanasyev5bee19e2013-07-10 14:33:57 -0700172 inline bool
Alexander Afanasyev09c7deb2011-11-23 14:50:10 -0800173 IsUp () const;
Alexander Afanasyevb4fee8b2012-06-06 12:54:26 -0700174
175 /**
Alexander Afanasyevdd9fa4f2013-05-15 16:35:04 -0700176 * @brief Get face flags
177 *
178 * Face flags may indicate various properties of the face. For example, if the face is an application face,
179 * than the returned flags have Face::APPLICATION bit set.
180 *
181 * @see ndn::Face::Flags for the list of currently defined face flags
182 */
183 inline uint32_t
184 GetFlags () const;
185
186 /**
187 * @brief List of currently defined face flags
188 */
189 enum Flags
190 {
191 APPLICATION = 1 ///< @brief An application face
192 };
Alexander Afanasyev5ab2bcd2013-07-15 18:21:19 -0700193
Alexander Afanasyevdd9fa4f2013-05-15 16:35:04 -0700194 /**
Alexander Afanasyevb4fee8b2012-06-06 12:54:26 -0700195 * @brief Print information about the face into the stream
196 * @param os stream to write information to
197 */
Alexander Afanasyevc5a23e22011-09-07 00:37:36 -0700198 virtual std::ostream&
199 Print (std::ostream &os) const;
200
Alexander Afanasyev56f79ea2011-08-17 23:54:27 -0700201 /**
Alexander Afanasyevc57a8772013-03-16 11:55:20 -0700202 * \brief Set face Id
Alexander Afanasyev56f79ea2011-08-17 23:54:27 -0700203 *
204 * Id is purely informative and should not be used for any other purpose
205 *
206 * \param id id to set
207 */
208 inline void
209 SetId (uint32_t id);
210
211 /**
Alexander Afanasyevc57a8772013-03-16 11:55:20 -0700212 * \brief Get face Id
Alexander Afanasyev56f79ea2011-08-17 23:54:27 -0700213 *
214 * Id is purely informative and should not be used for any other purpose
215 *
216 * \returns id id to set
217 */
218 inline uint32_t
219 GetId () const;
220
Alexander Afanasyev7fd74f92011-08-25 19:40:17 -0700221 /**
222 * \brief Compare two faces. Only two faces on the same node could be compared.
223 *
224 * Internal index is used for comparison.
225 */
Alexander Afanasyev56f79ea2011-08-17 23:54:27 -0700226 bool
Alexander Afanasyev2b4c9472012-08-09 15:00:38 -0700227 operator== (const Face &face) const;
Alexander Afanasyev7fd74f92011-08-25 19:40:17 -0700228
229 /**
230 * \brief Compare two faces. Only two faces on the same node could be compared.
231 *
232 * Internal index is used for comparison.
233 */
Alexander Afanasyev0845c092012-07-13 17:45:33 -0700234 inline bool
Alexander Afanasyev2b4c9472012-08-09 15:00:38 -0700235 operator!= (const Face &face) const;
Alexander Afanasyevdd9fa4f2013-05-15 16:35:04 -0700236
Alexander Afanasyev0845c092012-07-13 17:45:33 -0700237 /**
238 * \brief Compare two faces. Only two faces on the same node could be compared.
239 *
240 * Internal index is used for comparison.
241 */
Alexander Afanasyev7fd74f92011-08-25 19:40:17 -0700242 bool
Alexander Afanasyev2b4c9472012-08-09 15:00:38 -0700243 operator< (const Face &face) const;
Alexander Afanasyev08d984e2011-08-13 19:20:22 -0700244
Alexander Afanasyev09c7deb2011-11-23 14:50:10 -0800245protected:
246 /**
Alexander Afanasyev5bee19e2013-07-10 14:33:57 -0700247 * @brief Send packet down to the stack (towards app or network)
Alexander Afanasyev09c7deb2011-11-23 14:50:10 -0800248 */
Alexander Afanasyev1c0248b2012-07-24 15:59:50 -0700249 virtual bool
Alexander Afanasyev5bee19e2013-07-10 14:33:57 -0700250 Send (Ptr<Packet> packet);
Alexander Afanasyev5ab2bcd2013-07-15 18:21:19 -0700251
Alexander Afanasyev5bee19e2013-07-10 14:33:57 -0700252 /**
253 * @brief Send packet up to the stack (towards forwarding strategy)
254 */
255 virtual bool
256 Receive (Ptr<const Packet> p);
Alexander Afanasyevdd9fa4f2013-05-15 16:35:04 -0700257
Alexander Afanasyev5bee19e2013-07-10 14:33:57 -0700258 /**
259 * @brief Set face flags
260 */
Alexander Afanasyevdd9fa4f2013-05-15 16:35:04 -0700261 void
262 SetFlags (uint32_t flags);
Alexander Afanasyev09c7deb2011-11-23 14:50:10 -0800263
Alexander Afanasyev08d984e2011-08-13 19:20:22 -0700264private:
Alexander Afanasyev2b4c9472012-08-09 15:00:38 -0700265 Face (const Face &); ///< \brief Disabled copy constructor
266 Face& operator= (const Face &); ///< \brief Disabled copy operator
Alexander Afanasyevdd9fa4f2013-05-15 16:35:04 -0700267
Alexander Afanasyevab1d5602011-08-17 19:17:18 -0700268protected:
Alexander Afanasyev56f79ea2011-08-17 23:54:27 -0700269 Ptr<Node> m_node; ///< \brief Smart pointer to Node
Alexander Afanasyevdd9fa4f2013-05-15 16:35:04 -0700270
Alexander Afanasyev56f79ea2011-08-17 23:54:27 -0700271private:
Alexander Afanasyev5bee19e2013-07-10 14:33:57 -0700272 InterestHandler m_upstreamInterestHandler;
273 DataHandler m_upstreamDataHandler;
274 bool m_ifup;
Alexander Afanasyevc57a8772013-03-16 11:55:20 -0700275 uint32_t m_id; ///< \brief id of the interface in NDN stack (per-node uniqueness)
Alexander Afanasyev52a09bd2013-07-29 18:49:01 -0700276 uint16_t m_metric; ///< \brief metric of the face
Alexander Afanasyev5bee19e2013-07-10 14:33:57 -0700277 uint32_t m_flags; ///< @brief faces flags (e.g., APPLICATION)
Alexander Afanasyev08d984e2011-08-13 19:20:22 -0700278};
279
Alexander Afanasyevdd9fa4f2013-05-15 16:35:04 -0700280std::ostream&
281operator<< (std::ostream& os, const Face &face);
282
Alexander Afanasyev5bee19e2013-07-10 14:33:57 -0700283inline bool
284Face::IsUp (void) const
285{
286 return m_ifup;
287}
288
289inline void
290Face::SetUp (bool up/* = true*/)
291{
292 m_ifup = up;
293}
294
Alexander Afanasyevdd9fa4f2013-05-15 16:35:04 -0700295inline uint32_t
296Face::GetFlags () const
297{
298 return m_flags;
299}
Alexander Afanasyev56f79ea2011-08-17 23:54:27 -0700300
Alexander Afanasyev78cf0c92011-09-01 19:57:14 -0700301inline bool
Alexander Afanasyev2b4c9472012-08-09 15:00:38 -0700302operator < (const Ptr<Face> &lhs, const Ptr<Face> &rhs)
Alexander Afanasyev78cf0c92011-09-01 19:57:14 -0700303{
304 return *lhs < *rhs;
305}
306
Alexander Afanasyev56f79ea2011-08-17 23:54:27 -0700307void
Alexander Afanasyev2b4c9472012-08-09 15:00:38 -0700308Face::SetId (uint32_t id)
Alexander Afanasyev56f79ea2011-08-17 23:54:27 -0700309{
310 m_id = id;
311}
312
313uint32_t
Alexander Afanasyev2b4c9472012-08-09 15:00:38 -0700314Face::GetId () const
Alexander Afanasyev56f79ea2011-08-17 23:54:27 -0700315{
316 return m_id;
317}
Alexander Afanasyev98256102011-08-14 01:00:02 -0700318
Alexander Afanasyev0845c092012-07-13 17:45:33 -0700319inline bool
Alexander Afanasyev2b4c9472012-08-09 15:00:38 -0700320Face::operator!= (const Face &face) const
Alexander Afanasyev0845c092012-07-13 17:45:33 -0700321{
322 return !(*this == face);
323}
324
Alexander Afanasyev2b4c9472012-08-09 15:00:38 -0700325} // namespace ndn
Alexander Afanasyev08d984e2011-08-13 19:20:22 -0700326} // namespace ns3
327
Alexander Afanasyev2b4c9472012-08-09 15:00:38 -0700328#endif // NDN_FACE_H