blob: fcd9bd02034a46bbf0579f95f41e03350235bf05 [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
20#include "detail/registered-prefix.hpp"
21#include "detail/pending-interest.hpp"
22
Jeff Thompsonaa4e6db2013-07-15 17:25:23 -070023namespace ndn {
24
Alexander Afanasyev0222fba2014-02-09 23:16:02 -080025struct PendingInterestId;
26struct RegisteredPrefixId;
27
Jeff Thompsonfe08e5a2013-08-13 11:15:59 -070028/**
Alexander Afanasyev0222fba2014-02-09 23:16:02 -080029 * An OnData function object is used to pass a callback to expressInterest.
30 */
31typedef function<void(const Interest&, Data&)> OnData;
32
33/**
34 * An OnTimeout function object is used to pass a callback to expressInterest.
35 */
36typedef function<void(const Interest&)> OnTimeout;
37
38/**
39 * An OnInterest function object is used to pass a callback to registerPrefix.
40 */
41typedef function<void (const Name&, const Interest&)> OnInterest;
42
43/**
44 * An OnRegisterFailed function object is used to report when registerPrefix fails.
45 */
46typedef function<void(const Name&, const std::string&)> OnSetInterestFilterFailed;
47
48
49
50/**
51 * @brief Abstraction to communicate with local or remote NDN forwarder
Jeff Thompsonfe08e5a2013-08-13 11:15:59 -070052 */
Alexander Afanasyev8460afb2014-02-15 20:31:42 -080053class Face : noncopyable
54{
Jeff Thompsonaa4e6db2013-07-15 17:25:23 -070055public:
Alexander Afanasyev7682ccb2014-02-20 10:29:35 -080056 struct Error : public std::runtime_error { Error(const std::string& what) : std::runtime_error(what) {} };
Alexander Afanasyevb790d952014-01-24 12:07:53 -080057
58 /**
Alexander Afanasyev0222fba2014-02-09 23:16:02 -080059 * @brief Create a new Face for communication with an NDN Forwarder using the default UnixTransport.
Alexander Afanasyevb790d952014-01-24 12:07:53 -080060 */
Alexander Afanasyevf7ca3202014-02-14 22:28:31 -080061 Face();
Alexander Afanasyeve2e0d752014-01-03 13:30:30 -080062
63 /**
Alexander Afanasyev0222fba2014-02-09 23:16:02 -080064 * @brief Create a new Face for communication with an NDN Forwarder using the default UnixTransport.
Alexander Afanasyevb790d952014-01-24 12:07:53 -080065 * @param ioService A shared pointer to boost::io_service object that should control all IO operations
Jeff Thompsonfe08e5a2013-08-13 11:15:59 -070066 */
Alexander Afanasyevf7ca3202014-02-14 22:28:31 -080067 explicit
Alexander Afanasyev7682ccb2014-02-20 10:29:35 -080068 Face(const shared_ptr<boost::asio::io_service>& ioService);
69
Jeff Thompsonfe08e5a2013-08-13 11:15:59 -070070 /**
Jeff Thompson86507bc2013-08-23 20:51:38 -070071 * Create a new Face for communication with an NDN hub at host:port using the default TcpTransport.
Jeff Thompsonfe08e5a2013-08-13 11:15:59 -070072 * @param host The host of the NDN hub.
Alexander Afanasyev20d2c582014-01-26 15:32:51 -080073 * @param port The port or service name of the NDN hub. If omitted. use 6363.
Jeff Thompsonfe08e5a2013-08-13 11:15:59 -070074 */
Alexander Afanasyev7682ccb2014-02-20 10:29:35 -080075 Face(const std::string& host, const std::string& port = "6363");
Alexander Afanasyev0222fba2014-02-09 23:16:02 -080076
77 /**
78 * Create a new Face for communication with an NDN hub with the given Transport object and connectionInfo.
79 * @param transport A shared_ptr to a Transport object used for communication.
80 * @param transport A shared_ptr to a Transport::ConnectionInfo to be used to connect to the transport.
81 */
Alexander Afanasyevf7ca3202014-02-14 22:28:31 -080082 explicit
83 Face(const shared_ptr<Transport>& transport);
Alexander Afanasyev0222fba2014-02-09 23:16:02 -080084
85 /**
86 * @brief Alternative (special use case) version of the constructor, can be used to aggregate
87 * several Faces within one processing thread
88 *
89 * <code>
90 * Face face1(...);
91 * Face face2(..., face1.getAsyncService());
92 *
93 * // Now the following ensures that events on both faces are processed
94 * face1.processEvents();
95 * </code>
96 */
97 Face(const shared_ptr<Transport>& transport,
Alexander Afanasyev7682ccb2014-02-20 10:29:35 -080098 const shared_ptr<boost::asio::io_service>& ioService);
99
100 /**
Alexander Afanasyev505646e2014-02-24 20:13:37 -0800101 * @brief Set controller used for prefix registration
Alexander Afanasyev7682ccb2014-02-20 10:29:35 -0800102 */
Alexander Afanasyev505646e2014-02-24 20:13:37 -0800103 void
104 setController(const shared_ptr<Controller>& controller);
Alexander Afanasyev20d2c582014-01-26 15:32:51 -0800105
Jeff Thompson4fe45512013-08-23 14:06:38 -0700106 /**
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800107 * @brief Express Interest
108 *
109 * @param interest A reference to the Interest. This copies the Interest.
110 * @param onData A function object to call when a matching data packet is received.
111 * @param onTimeout A function object to call if the interest times out.
112 * If onTimeout is an empty OnTimeout(), this does not use it.
113 *
Jeff Thompson11095142013-10-01 16:20:28 -0700114 * @return The pending interest ID which can be used with removePendingInterest.
Jeff Thompson4fe45512013-08-23 14:06:38 -0700115 */
Alexander Afanasyevb790d952014-01-24 12:07:53 -0800116 const PendingInterestId*
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800117 expressInterest(const Interest& interest,
118 const OnData& onData, const OnTimeout& onTimeout = OnTimeout());
Jeff Thompson4fe45512013-08-23 14:06:38 -0700119
120 /**
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800121 * @brief Express Interest using name and Interest template
122 *
123 * @param name Name of the Interest
124 * @param tmpl Interest template to fill parameters
125 * @param onData A callback to call when a matching data packet is received.
126 * @param onTimeout A callback to call if the interest times out.
127 * If onTimeout is an empty OnTimeout(), this does not use it.
128 *
Jeff Thompson11095142013-10-01 16:20:28 -0700129 * @return The pending interest ID which can be used with removePendingInterest.
Jeff Thompson7aec0252013-08-22 17:29:57 -0700130 */
Alexander Afanasyevb790d952014-01-24 12:07:53 -0800131 const PendingInterestId*
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800132 expressInterest(const Name& name,
Alexander Afanasyev7682ccb2014-02-20 10:29:35 -0800133 const Interest& tmpl,
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800134 const OnData& onData, const OnTimeout& onTimeout = OnTimeout());
135
Jeff Thompson11095142013-10-01 16:20:28 -0700136 /**
137 * Remove the pending interest entry with the pendingInterestId from the pending interest table.
138 * This does not affect another pending interest with a different pendingInterestId, even it if has the same interest name.
139 * If there is no entry with the pendingInterestId, do nothing.
140 * @param pendingInterestId The ID returned from expressInterest.
141 */
142 void
Alexander Afanasyev7682ccb2014-02-20 10:29:35 -0800143 removePendingInterest(const PendingInterestId* pendingInterestId);
Jeff Thompsoncdf7e252013-07-31 12:41:47 -0700144
Jeff Thompson432c8be2013-08-09 16:16:08 -0700145 /**
Jeff Thompson86507bc2013-08-23 20:51:38 -0700146 * Register prefix with the connected NDN hub and call onInterest when a matching interest is received.
147 * @param prefix A reference to a Name for the prefix to register. This copies the Name.
148 * @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 -0800149 * use ref() as appropriate.
Jeff Thompson590ec232013-09-18 15:55:56 -0700150 * @param onRegisterFailed A function object to call if failed to retrieve the connected hub’s ID or failed to register the prefix.
151 * This calls onRegisterFailed(prefix) where prefix is the prefix given to registerPrefix.
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800152 * @param flags The flags for finer control of which interests are forward to the application.
Jeff Thompson11095142013-10-01 16:20:28 -0700153 * @return The registered prefix ID which can be used with removeRegisteredPrefix.
Jeff Thompson86507bc2013-08-23 20:51:38 -0700154 */
Alexander Afanasyevb790d952014-01-24 12:07:53 -0800155 const RegisteredPrefixId*
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800156 setInterestFilter(const Name& prefix,
157 const OnInterest& onInterest,
158 const OnSetInterestFilterFailed& onSetInterestFilterFailed);
Jeff Thompson11095142013-10-01 16:20:28 -0700159
160 /**
161 * Remove the registered prefix entry with the registeredPrefixId from the pending interest table.
162 * This does not affect another registered prefix with a different registeredPrefixId, even it if has the same prefix name.
163 * If there is no entry with the registeredPrefixId, do nothing.
164 * @param registeredPrefixId The ID returned from registerPrefix.
165 */
166 void
Alexander Afanasyev7682ccb2014-02-20 10:29:35 -0800167 unsetInterestFilter(const RegisteredPrefixId* registeredPrefixId);
Alexander Afanasyeva557d5a2013-12-28 21:59:03 -0800168
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800169 /**
Alexander Afanasyeva557d5a2013-12-28 21:59:03 -0800170 * @brief Publish data packet
171 *
172 * This method can be called to satisfy the incoming Interest or to put Data packet into the cache
173 * of the local NDN forwarder
174 */
175 void
Alexander Afanasyev7682ccb2014-02-20 10:29:35 -0800176 put(const Data& data);
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800177
Jeff Thompson86507bc2013-08-23 20:51:38 -0700178 /**
Jeff Thompsonbf50a1a2013-08-20 18:01:01 -0700179 * Process any data to receive or call timeout callbacks.
Alexander Afanasyeva557d5a2013-12-28 21:59:03 -0800180 *
181 * This call will block forever (default timeout == 0) to process IO on the face.
182 * To exit, one expected to call face.shutdown() from one of the callback methods.
183 *
Alexander Afanasyevf75a0aa2014-01-09 14:29:22 -0800184 * If positive timeout is specified, then processEvents will exit after this timeout,
185 * if not stopped earlier with face.shutdown() or when all active events finish.
Alexander Afanasyeva557d5a2013-12-28 21:59:03 -0800186 * The call can be called repeatedly, if desired.
187 *
Alexander Afanasyevf75a0aa2014-01-09 14:29:22 -0800188 * If negative timeout is specified, then processEvents will not block and process only pending
189 * events.
190 *
Jeff Thompson432c8be2013-08-09 16:16:08 -0700191 * @throw This may throw an exception for reading data or in the callback for processing the data. If you
192 * call this from an main event loop, you may want to catch and log/disregard all exceptions.
193 */
Jeff Thompson0050abe2013-09-17 12:50:25 -0700194 void
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800195 processEvents(Milliseconds timeout = 0, bool keepThread = false);
Jeff Thompson432c8be2013-08-09 16:16:08 -0700196
Jeff Thompson0050abe2013-09-17 12:50:25 -0700197 void
198 shutdown();
Yingdi Yu0d920812014-01-30 14:50:57 -0800199
200 shared_ptr<boost::asio::io_service>
Alexander Afanasyevf39c5372014-02-17 19:42:56 -0800201 ioService() { return m_ioService; }
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800202
203private:
204 void
Alexander Afanasyev7682ccb2014-02-20 10:29:35 -0800205 construct(const shared_ptr<Transport>& transport,
Alexander Afanasyev505646e2014-02-24 20:13:37 -0800206 const shared_ptr<boost::asio::io_service>& ioService);
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800207
208 struct ProcessEventsTimeout {};
209 typedef std::list<shared_ptr<PendingInterest> > PendingInterestTable;
210 typedef std::list<shared_ptr<RegisteredPrefix> > RegisteredPrefixTable;
211
212 void
Alexander Afanasyev6d48bc12014-02-18 00:10:51 -0800213 asyncExpressInterest(const shared_ptr<const Interest>& interest,
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800214 const OnData& onData, const OnTimeout& onTimeout);
215
216 void
Alexander Afanasyev6d48bc12014-02-18 00:10:51 -0800217 asyncRemovePendingInterest(const PendingInterestId* pendingInterestId);
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800218
219 void
Alexander Afanasyev6d48bc12014-02-18 00:10:51 -0800220 asyncUnsetInterestFilter(const RegisteredPrefixId* registeredPrefixId);
Alexander Afanasyev12dfbad2014-02-11 14:42:46 -0800221
222 void
Alexander Afanasyev52afb3f2014-03-07 09:05:35 +0000223 finalizeUnsetInterestFilter(RegisteredPrefixTable::iterator item);
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800224
225 void
Alexander Afanasyev6d48bc12014-02-18 00:10:51 -0800226 onReceiveElement(const Block& wire);
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800227
228
229 static void
230 fireProcessEventsTimeout(const boost::system::error_code& error);
231
Alexander Afanasyev42c81852014-02-25 21:37:26 -0800232 void
233 satisfyPendingInterests(Data& data);
234
235 void
236 processInterestFilters(Interest& interest);
237
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800238 void
239 checkPitExpire();
Yingdi Yuf9fa52f2014-02-06 12:27:32 -0800240
Jeff Thompsonb982b6d2013-07-15 18:15:45 -0700241private:
Alexander Afanasyevf39c5372014-02-17 19:42:56 -0800242 shared_ptr<boost::asio::io_service> m_ioService;
243 shared_ptr<boost::asio::io_service::work> m_ioServiceWork; // needed if thread needs to be preserved
244 shared_ptr<boost::asio::deadline_timer> m_pitTimeoutCheckTimer;
245 bool m_pitTimeoutCheckTimerActive;
246 shared_ptr<boost::asio::deadline_timer> m_processEventsTimeoutTimer;
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800247
Alexander Afanasyevf39c5372014-02-17 19:42:56 -0800248 shared_ptr<Transport> m_transport;
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800249
Alexander Afanasyevf39c5372014-02-17 19:42:56 -0800250 PendingInterestTable m_pendingInterestTable;
251 RegisteredPrefixTable m_registeredPrefixTable;
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800252
253 shared_ptr<Controller> m_fwController;
Jeff Thompsonaa4e6db2013-07-15 17:25:23 -0700254};
255
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800256} // namespace ndn
Jeff Thompsonaa4e6db2013-07-15 17:25:23 -0700257
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800258#endif // NDN_FACE_HPP