blob: 6aac1e08892c0154a43eccc81585d3e9b989301e [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 Afanasyev0222fba2014-02-09 23:16:02 -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
68 Face(const ptr_lib::shared_ptr<boost::asio::io_service> &ioService);
Jeff Thompsonb982b6d2013-07-15 18:15:45 -070069
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 Afanasyevf7ca3202014-02-14 22:28:31 -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 Afanasyevf7ca3202014-02-14 22:28:31 -080098 const shared_ptr<boost::asio::io_service> &ioService);
Alexander Afanasyev20d2c582014-01-26 15:32:51 -080099
Jeff Thompson4fe45512013-08-23 14:06:38 -0700100 /**
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800101 * @brief Express Interest
102 *
103 * @param interest A reference to the Interest. This copies the Interest.
104 * @param onData A function object to call when a matching data packet is received.
105 * @param onTimeout A function object to call if the interest times out.
106 * If onTimeout is an empty OnTimeout(), this does not use it.
107 *
Jeff Thompson11095142013-10-01 16:20:28 -0700108 * @return The pending interest ID which can be used with removePendingInterest.
Jeff Thompson4fe45512013-08-23 14:06:38 -0700109 */
Alexander Afanasyevb790d952014-01-24 12:07:53 -0800110 const PendingInterestId*
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800111 expressInterest(const Interest& interest,
112 const OnData& onData, const OnTimeout& onTimeout = OnTimeout());
Jeff Thompson4fe45512013-08-23 14:06:38 -0700113
114 /**
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800115 * @brief Express Interest using name and Interest template
116 *
117 * @param name Name of the Interest
118 * @param tmpl Interest template to fill parameters
119 * @param onData A callback to call when a matching data packet is received.
120 * @param onTimeout A callback to call if the interest times out.
121 * If onTimeout is an empty OnTimeout(), this does not use it.
122 *
Jeff Thompson11095142013-10-01 16:20:28 -0700123 * @return The pending interest ID which can be used with removePendingInterest.
Jeff Thompson7aec0252013-08-22 17:29:57 -0700124 */
Alexander Afanasyevb790d952014-01-24 12:07:53 -0800125 const PendingInterestId*
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800126 expressInterest(const Name& name,
127 const Interest &tmpl,
128 const OnData& onData, const OnTimeout& onTimeout = OnTimeout());
129
Jeff Thompson11095142013-10-01 16:20:28 -0700130 /**
131 * Remove the pending interest entry with the pendingInterestId from the pending interest table.
132 * This does not affect another pending interest with a different pendingInterestId, even it if has the same interest name.
133 * If there is no entry with the pendingInterestId, do nothing.
134 * @param pendingInterestId The ID returned from expressInterest.
135 */
136 void
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800137 removePendingInterest(const PendingInterestId *pendingInterestId);
Jeff Thompsoncdf7e252013-07-31 12:41:47 -0700138
Jeff Thompson432c8be2013-08-09 16:16:08 -0700139 /**
Jeff Thompson86507bc2013-08-23 20:51:38 -0700140 * Register prefix with the connected NDN hub and call onInterest when a matching interest is received.
141 * @param prefix A reference to a Name for the prefix to register. This copies the Name.
142 * @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 -0800143 * use ref() as appropriate.
Jeff Thompson590ec232013-09-18 15:55:56 -0700144 * @param onRegisterFailed A function object to call if failed to retrieve the connected hub’s ID or failed to register the prefix.
145 * This calls onRegisterFailed(prefix) where prefix is the prefix given to registerPrefix.
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800146 * @param flags The flags for finer control of which interests are forward to the application.
Jeff Thompson11095142013-10-01 16:20:28 -0700147 * @return The registered prefix ID which can be used with removeRegisteredPrefix.
Jeff Thompson86507bc2013-08-23 20:51:38 -0700148 */
Alexander Afanasyevb790d952014-01-24 12:07:53 -0800149 const RegisteredPrefixId*
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800150 setInterestFilter(const Name& prefix,
151 const OnInterest& onInterest,
152 const OnSetInterestFilterFailed& onSetInterestFilterFailed);
Jeff Thompson11095142013-10-01 16:20:28 -0700153
154 /**
155 * Remove the registered prefix entry with the registeredPrefixId from the pending interest table.
156 * This does not affect another registered prefix with a different registeredPrefixId, even it if has the same prefix name.
157 * If there is no entry with the registeredPrefixId, do nothing.
158 * @param registeredPrefixId The ID returned from registerPrefix.
159 */
160 void
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800161 unsetInterestFilter(const RegisteredPrefixId *registeredPrefixId);
Alexander Afanasyeva557d5a2013-12-28 21:59:03 -0800162
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800163 /**
Alexander Afanasyeva557d5a2013-12-28 21:59:03 -0800164 * @brief Publish data packet
165 *
166 * This method can be called to satisfy the incoming Interest or to put Data packet into the cache
167 * of the local NDN forwarder
168 */
169 void
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800170 put(const Data &data);
171
Jeff Thompson86507bc2013-08-23 20:51:38 -0700172 /**
Jeff Thompsonbf50a1a2013-08-20 18:01:01 -0700173 * Process any data to receive or call timeout callbacks.
Alexander Afanasyeva557d5a2013-12-28 21:59:03 -0800174 *
175 * This call will block forever (default timeout == 0) to process IO on the face.
176 * To exit, one expected to call face.shutdown() from one of the callback methods.
177 *
Alexander Afanasyevf75a0aa2014-01-09 14:29:22 -0800178 * If positive timeout is specified, then processEvents will exit after this timeout,
179 * if not stopped earlier with face.shutdown() or when all active events finish.
Alexander Afanasyeva557d5a2013-12-28 21:59:03 -0800180 * The call can be called repeatedly, if desired.
181 *
Alexander Afanasyevf75a0aa2014-01-09 14:29:22 -0800182 * If negative timeout is specified, then processEvents will not block and process only pending
183 * events.
184 *
Jeff Thompson432c8be2013-08-09 16:16:08 -0700185 * @throw This may throw an exception for reading data or in the callback for processing the data. If you
186 * call this from an main event loop, you may want to catch and log/disregard all exceptions.
187 */
Jeff Thompson0050abe2013-09-17 12:50:25 -0700188 void
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800189 processEvents(Milliseconds timeout = 0, bool keepThread = false);
Jeff Thompson432c8be2013-08-09 16:16:08 -0700190
Jeff Thompson0050abe2013-09-17 12:50:25 -0700191 void
192 shutdown();
Yingdi Yu0d920812014-01-30 14:50:57 -0800193
194 shared_ptr<boost::asio::io_service>
Alexander Afanasyevf39c5372014-02-17 19:42:56 -0800195 ioService() { return m_ioService; }
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800196
197private:
198 void
Alexander Afanasyevf7ca3202014-02-14 22:28:31 -0800199 construct(const shared_ptr<Transport>& transport, const shared_ptr<boost::asio::io_service>& ioService);
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800200
201 struct ProcessEventsTimeout {};
202 typedef std::list<shared_ptr<PendingInterest> > PendingInterestTable;
203 typedef std::list<shared_ptr<RegisteredPrefix> > RegisteredPrefixTable;
204
205 void
206 asyncExpressInterest(const shared_ptr<const Interest> &interest,
207 const OnData& onData, const OnTimeout& onTimeout);
208
209 void
210 asyncRemovePendingInterest(const PendingInterestId *pendingInterestId);
211
212 void
213 asyncUnsetInterestFilter(const RegisteredPrefixId *registeredPrefixId);
Alexander Afanasyev12dfbad2014-02-11 14:42:46 -0800214
215 void
216 finalizeUnsertInterestFilter(RegisteredPrefixTable::iterator item);
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800217
218 void
219 onReceiveElement(const Block &wire);
220
221
222 static void
223 fireProcessEventsTimeout(const boost::system::error_code& error);
224
225 /**
226 * Find the entry from the pit_ where the name conforms to the entry's interest selectors, and
227 * the entry interest name is the longest that matches name.
228 * @param name The name to find the interest for (from the incoming data packet).
229 * @return The index in pit_ of the pit entry, or -1 if not found.
230 */
231 PendingInterestTable::iterator
232 getEntryIndexForExpressedInterest(const Name& name);
233
234 /**
Alexander Afanasyevf39c5372014-02-17 19:42:56 -0800235 * Find the first entry from the m_registeredPrefixTable where the entry prefix is the longest that matches name.
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800236 * @param name The name to find the PrefixEntry for (from the incoming interest packet).
237 * @return A pointer to the entry, or 0 if not found.
238 */
239 RegisteredPrefixTable::iterator
240 getEntryForRegisteredPrefix(const Name& name);
241
242
243 void
244 checkPitExpire();
Jeff Thompson517ffa82013-08-05 16:04:34 -0700245
Jeff Thompsonb982b6d2013-07-15 18:15:45 -0700246private:
Alexander Afanasyevf39c5372014-02-17 19:42:56 -0800247 shared_ptr<boost::asio::io_service> m_ioService;
248 shared_ptr<boost::asio::io_service::work> m_ioServiceWork; // needed if thread needs to be preserved
249 shared_ptr<boost::asio::deadline_timer> m_pitTimeoutCheckTimer;
250 bool m_pitTimeoutCheckTimerActive;
251 shared_ptr<boost::asio::deadline_timer> m_processEventsTimeoutTimer;
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800252
Alexander Afanasyevf39c5372014-02-17 19:42:56 -0800253 shared_ptr<Transport> m_transport;
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800254
Alexander Afanasyevf39c5372014-02-17 19:42:56 -0800255 PendingInterestTable m_pendingInterestTable;
256 RegisteredPrefixTable m_registeredPrefixTable;
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800257
258 shared_ptr<Controller> m_fwController;
Jeff Thompsonaa4e6db2013-07-15 17:25:23 -0700259};
260
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800261} // namespace ndn
Jeff Thompsonaa4e6db2013-07-15 17:25:23 -0700262
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800263#endif // NDN_FACE_HPP