blob: 4cb4c6763879ee868d9febcb445e3c27fdb5512c [file] [log] [blame]
Jeff Thompson25b4e612013-10-10 16:03:24 -07001/* -*- Mode:C++; c-file-style:"gnu"; indent-tabs-mode:nil -*- */
Jeff Thompsonaa4e6db2013-07-15 17:25:23 -07002/**
Jeff Thompson7687dc02013-09-13 11:54:07 -07003 * Copyright (C) 2013 Regents of the University of California.
Jeff Thompsonaa4e6db2013-07-15 17:25:23 -07004 * See COPYING for copyright and distribution information.
5 */
6
Jeff Thompsonb9e3c8e2013-08-02 11:42:51 -07007#ifndef NDN_FACE_HPP
Jeff Thompsona0d18c92013-08-06 13:55:32 -07008#define NDN_FACE_HPP
Jeff Thompsonaa4e6db2013-07-15 17:25:23 -07009
Alexander Afanasyev0222fba2014-02-09 23:16:02 -080010#include "common.hpp"
11#include "interest.hpp"
12#include "data.hpp"
13
Alexander Afanasyeve2e0d752014-01-03 13:30:30 -080014#include "transport/transport.hpp"
15#include "transport/unix-transport.hpp"
Alexander Afanasyev20d2c582014-01-26 15:32:51 -080016#include "transport/tcp-transport.hpp"
Jeff Thompsonbeb8b7d2013-07-16 15:49:21 -070017
Alexander Afanasyev0222fba2014-02-09 23:16:02 -080018#include "management/controller.hpp"
19
Alexander Afanasyevaa0e7da2014-03-17 14:37:33 -070020#include "util/scheduler.hpp"
Alexander Afanasyev0222fba2014-02-09 23:16:02 -080021#include "detail/registered-prefix.hpp"
22#include "detail/pending-interest.hpp"
23
Jeff Thompsonaa4e6db2013-07-15 17:25:23 -070024namespace ndn {
25
Alexander Afanasyev0222fba2014-02-09 23:16:02 -080026struct PendingInterestId;
27struct RegisteredPrefixId;
28
Jeff Thompsonfe08e5a2013-08-13 11:15:59 -070029/**
Alexander Afanasyev0222fba2014-02-09 23:16:02 -080030 * An OnData function object is used to pass a callback to expressInterest.
31 */
32typedef function<void(const Interest&, Data&)> OnData;
33
34/**
35 * An OnTimeout function object is used to pass a callback to expressInterest.
36 */
37typedef function<void(const Interest&)> OnTimeout;
38
39/**
40 * An OnInterest function object is used to pass a callback to registerPrefix.
41 */
42typedef function<void (const Name&, const Interest&)> OnInterest;
43
44/**
45 * An OnRegisterFailed function object is used to report when registerPrefix fails.
46 */
47typedef function<void(const Name&, const std::string&)> OnSetInterestFilterFailed;
48
49
50
51/**
52 * @brief Abstraction to communicate with local or remote NDN forwarder
Jeff Thompsonfe08e5a2013-08-13 11:15:59 -070053 */
Alexander Afanasyev8460afb2014-02-15 20:31:42 -080054class Face : noncopyable
55{
Jeff Thompsonaa4e6db2013-07-15 17:25:23 -070056public:
Alexander Afanasyev7682ccb2014-02-20 10:29:35 -080057 struct Error : public std::runtime_error { Error(const std::string& what) : std::runtime_error(what) {} };
Alexander Afanasyevb790d952014-01-24 12:07:53 -080058
59 /**
Alexander Afanasyev0222fba2014-02-09 23:16:02 -080060 * @brief Create a new Face for communication with an NDN Forwarder using the default UnixTransport.
Alexander Afanasyevb790d952014-01-24 12:07:53 -080061 */
Alexander Afanasyevf7ca3202014-02-14 22:28:31 -080062 Face();
Alexander Afanasyeve2e0d752014-01-03 13:30:30 -080063
64 /**
Alexander Afanasyev0222fba2014-02-09 23:16:02 -080065 * @brief Create a new Face for communication with an NDN Forwarder using the default UnixTransport.
Alexander Afanasyevb790d952014-01-24 12:07:53 -080066 * @param ioService A shared pointer to boost::io_service object that should control all IO operations
Jeff Thompsonfe08e5a2013-08-13 11:15:59 -070067 */
Alexander Afanasyevf7ca3202014-02-14 22:28:31 -080068 explicit
Alexander Afanasyev7682ccb2014-02-20 10:29:35 -080069 Face(const shared_ptr<boost::asio::io_service>& ioService);
70
Jeff Thompsonfe08e5a2013-08-13 11:15:59 -070071 /**
Jeff Thompson86507bc2013-08-23 20:51:38 -070072 * Create a new Face for communication with an NDN hub at host:port using the default TcpTransport.
Jeff Thompsonfe08e5a2013-08-13 11:15:59 -070073 * @param host The host of the NDN hub.
Alexander Afanasyev20d2c582014-01-26 15:32:51 -080074 * @param port The port or service name of the NDN hub. If omitted. use 6363.
Jeff Thompsonfe08e5a2013-08-13 11:15:59 -070075 */
Alexander Afanasyev7682ccb2014-02-20 10:29:35 -080076 Face(const std::string& host, const std::string& port = "6363");
Alexander Afanasyev0222fba2014-02-09 23:16:02 -080077
78 /**
79 * Create a new Face for communication with an NDN hub with the given Transport object and connectionInfo.
80 * @param transport A shared_ptr to a Transport object used for communication.
81 * @param transport A shared_ptr to a Transport::ConnectionInfo to be used to connect to the transport.
82 */
Alexander Afanasyevf7ca3202014-02-14 22:28:31 -080083 explicit
84 Face(const shared_ptr<Transport>& transport);
Alexander Afanasyev0222fba2014-02-09 23:16:02 -080085
86 /**
87 * @brief Alternative (special use case) version of the constructor, can be used to aggregate
88 * several Faces within one processing thread
89 *
90 * <code>
91 * Face face1(...);
92 * Face face2(..., face1.getAsyncService());
93 *
94 * // Now the following ensures that events on both faces are processed
95 * face1.processEvents();
96 * </code>
97 */
98 Face(const shared_ptr<Transport>& transport,
Alexander Afanasyev7682ccb2014-02-20 10:29:35 -080099 const shared_ptr<boost::asio::io_service>& ioService);
100
101 /**
Alexander Afanasyev505646e2014-02-24 20:13:37 -0800102 * @brief Set controller used for prefix registration
Alexander Afanasyev7682ccb2014-02-20 10:29:35 -0800103 */
Alexander Afanasyev505646e2014-02-24 20:13:37 -0800104 void
105 setController(const shared_ptr<Controller>& controller);
Alexander Afanasyev20d2c582014-01-26 15:32:51 -0800106
Jeff Thompson4fe45512013-08-23 14:06:38 -0700107 /**
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800108 * @brief Express Interest
109 *
110 * @param interest A reference to the Interest. This copies the Interest.
111 * @param onData A function object to call when a matching data packet is received.
112 * @param onTimeout A function object to call if the interest times out.
113 * If onTimeout is an empty OnTimeout(), this does not use it.
114 *
Jeff Thompson11095142013-10-01 16:20:28 -0700115 * @return The pending interest ID which can be used with removePendingInterest.
Jeff Thompson4fe45512013-08-23 14:06:38 -0700116 */
Alexander Afanasyevb790d952014-01-24 12:07:53 -0800117 const PendingInterestId*
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800118 expressInterest(const Interest& interest,
119 const OnData& onData, const OnTimeout& onTimeout = OnTimeout());
Jeff Thompson4fe45512013-08-23 14:06:38 -0700120
121 /**
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800122 * @brief Express Interest using name and Interest template
123 *
124 * @param name Name of the Interest
125 * @param tmpl Interest template to fill parameters
126 * @param onData A callback to call when a matching data packet is received.
127 * @param onTimeout A callback to call if the interest times out.
128 * If onTimeout is an empty OnTimeout(), this does not use it.
129 *
Jeff Thompson11095142013-10-01 16:20:28 -0700130 * @return The pending interest ID which can be used with removePendingInterest.
Jeff Thompson7aec0252013-08-22 17:29:57 -0700131 */
Alexander Afanasyevb790d952014-01-24 12:07:53 -0800132 const PendingInterestId*
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800133 expressInterest(const Name& name,
Alexander Afanasyev7682ccb2014-02-20 10:29:35 -0800134 const Interest& tmpl,
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800135 const OnData& onData, const OnTimeout& onTimeout = OnTimeout());
136
Jeff Thompson11095142013-10-01 16:20:28 -0700137 /**
138 * Remove the pending interest entry with the pendingInterestId from the pending interest table.
139 * This does not affect another pending interest with a different pendingInterestId, even it if has the same interest name.
140 * If there is no entry with the pendingInterestId, do nothing.
141 * @param pendingInterestId The ID returned from expressInterest.
142 */
143 void
Alexander Afanasyev7682ccb2014-02-20 10:29:35 -0800144 removePendingInterest(const PendingInterestId* pendingInterestId);
Jeff Thompsoncdf7e252013-07-31 12:41:47 -0700145
Jeff Thompson432c8be2013-08-09 16:16:08 -0700146 /**
Jeff Thompson86507bc2013-08-23 20:51:38 -0700147 * Register prefix with the connected NDN hub and call onInterest when a matching interest is received.
148 * @param prefix A reference to a Name for the prefix to register. This copies the Name.
149 * @param onInterest A function object to call when a matching interest is received. This copies the function object, so you may need to
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800150 * use ref() as appropriate.
Jeff Thompson590ec232013-09-18 15:55:56 -0700151 * @param onRegisterFailed A function object to call if failed to retrieve the connected hub’s ID or failed to register the prefix.
152 * This calls onRegisterFailed(prefix) where prefix is the prefix given to registerPrefix.
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800153 * @param flags The flags for finer control of which interests are forward to the application.
Jeff Thompson11095142013-10-01 16:20:28 -0700154 * @return The registered prefix ID which can be used with removeRegisteredPrefix.
Jeff Thompson86507bc2013-08-23 20:51:38 -0700155 */
Alexander Afanasyevb790d952014-01-24 12:07:53 -0800156 const RegisteredPrefixId*
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800157 setInterestFilter(const Name& prefix,
158 const OnInterest& onInterest,
159 const OnSetInterestFilterFailed& onSetInterestFilterFailed);
Jeff Thompson11095142013-10-01 16:20:28 -0700160
161 /**
162 * Remove the registered prefix entry with the registeredPrefixId from the pending interest table.
163 * This does not affect another registered prefix with a different registeredPrefixId, even it if has the same prefix name.
164 * If there is no entry with the registeredPrefixId, do nothing.
165 * @param registeredPrefixId The ID returned from registerPrefix.
166 */
167 void
Alexander Afanasyev7682ccb2014-02-20 10:29:35 -0800168 unsetInterestFilter(const RegisteredPrefixId* registeredPrefixId);
Alexander Afanasyeva557d5a2013-12-28 21:59:03 -0800169
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800170 /**
Alexander Afanasyeva557d5a2013-12-28 21:59:03 -0800171 * @brief Publish data packet
172 *
173 * This method can be called to satisfy the incoming Interest or to put Data packet into the cache
174 * of the local NDN forwarder
175 */
176 void
Alexander Afanasyev7682ccb2014-02-20 10:29:35 -0800177 put(const Data& data);
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800178
Jeff Thompson86507bc2013-08-23 20:51:38 -0700179 /**
Jeff Thompsonbf50a1a2013-08-20 18:01:01 -0700180 * Process any data to receive or call timeout callbacks.
Alexander Afanasyeva557d5a2013-12-28 21:59:03 -0800181 *
182 * This call will block forever (default timeout == 0) to process IO on the face.
183 * To exit, one expected to call face.shutdown() from one of the callback methods.
184 *
Alexander Afanasyevf75a0aa2014-01-09 14:29:22 -0800185 * If positive timeout is specified, then processEvents will exit after this timeout,
186 * if not stopped earlier with face.shutdown() or when all active events finish.
Alexander Afanasyeva557d5a2013-12-28 21:59:03 -0800187 * The call can be called repeatedly, if desired.
188 *
Alexander Afanasyevf75a0aa2014-01-09 14:29:22 -0800189 * If negative timeout is specified, then processEvents will not block and process only pending
190 * events.
191 *
Jeff Thompson432c8be2013-08-09 16:16:08 -0700192 * @throw This may throw an exception for reading data or in the callback for processing the data. If you
193 * call this from an main event loop, you may want to catch and log/disregard all exceptions.
194 */
Jeff Thompson0050abe2013-09-17 12:50:25 -0700195 void
Alexander Afanasyevaa0e7da2014-03-17 14:37:33 -0700196 processEvents(const time::milliseconds& timeout = time::milliseconds::zero(),
197 bool keepThread = false);
Jeff Thompson432c8be2013-08-09 16:16:08 -0700198
Jeff Thompson0050abe2013-09-17 12:50:25 -0700199 void
200 shutdown();
Yingdi Yu0d920812014-01-30 14:50:57 -0800201
202 shared_ptr<boost::asio::io_service>
Alexander Afanasyevf39c5372014-02-17 19:42:56 -0800203 ioService() { return m_ioService; }
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800204
205private:
206 void
Alexander Afanasyev7682ccb2014-02-20 10:29:35 -0800207 construct(const shared_ptr<Transport>& transport,
Alexander Afanasyev505646e2014-02-24 20:13:37 -0800208 const shared_ptr<boost::asio::io_service>& ioService);
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800209
210 struct ProcessEventsTimeout {};
211 typedef std::list<shared_ptr<PendingInterest> > PendingInterestTable;
212 typedef std::list<shared_ptr<RegisteredPrefix> > RegisteredPrefixTable;
213
214 void
Alexander Afanasyev6d48bc12014-02-18 00:10:51 -0800215 asyncExpressInterest(const shared_ptr<const Interest>& interest,
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800216 const OnData& onData, const OnTimeout& onTimeout);
217
218 void
Alexander Afanasyev6d48bc12014-02-18 00:10:51 -0800219 asyncRemovePendingInterest(const PendingInterestId* pendingInterestId);
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800220
221 void
Alexander Afanasyev6d48bc12014-02-18 00:10:51 -0800222 asyncUnsetInterestFilter(const RegisteredPrefixId* registeredPrefixId);
Alexander Afanasyev12dfbad2014-02-11 14:42:46 -0800223
224 void
Alexander Afanasyev52afb3f2014-03-07 09:05:35 +0000225 finalizeUnsetInterestFilter(RegisteredPrefixTable::iterator item);
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800226
227 void
Alexander Afanasyev6d48bc12014-02-18 00:10:51 -0800228 onReceiveElement(const Block& wire);
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800229
230
231 static void
232 fireProcessEventsTimeout(const boost::system::error_code& error);
233
Alexander Afanasyev42c81852014-02-25 21:37:26 -0800234 void
235 satisfyPendingInterests(Data& data);
236
237 void
238 processInterestFilters(Interest& interest);
239
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800240 void
241 checkPitExpire();
Yingdi Yuf9fa52f2014-02-06 12:27:32 -0800242
Jeff Thompsonb982b6d2013-07-15 18:15:45 -0700243private:
Alexander Afanasyevf39c5372014-02-17 19:42:56 -0800244 shared_ptr<boost::asio::io_service> m_ioService;
245 shared_ptr<boost::asio::io_service::work> m_ioServiceWork; // needed if thread needs to be preserved
Alexander Afanasyevaa0e7da2014-03-17 14:37:33 -0700246 shared_ptr<monotonic_deadline_timer> m_pitTimeoutCheckTimer;
Alexander Afanasyevf39c5372014-02-17 19:42:56 -0800247 bool m_pitTimeoutCheckTimerActive;
Alexander Afanasyevaa0e7da2014-03-17 14:37:33 -0700248 shared_ptr<monotonic_deadline_timer> m_processEventsTimeoutTimer;
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800249
Alexander Afanasyevf39c5372014-02-17 19:42:56 -0800250 shared_ptr<Transport> m_transport;
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800251
Alexander Afanasyevf39c5372014-02-17 19:42:56 -0800252 PendingInterestTable m_pendingInterestTable;
253 RegisteredPrefixTable m_registeredPrefixTable;
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800254
255 shared_ptr<Controller> m_fwController;
Jeff Thompsonaa4e6db2013-07-15 17:25:23 -0700256};
257
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800258} // namespace ndn
Jeff Thompsonaa4e6db2013-07-15 17:25:23 -0700259
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800260#endif // NDN_FACE_HPP