blob: 42f4fd1efeefab0ede3c8db69c649f78f31f87ac [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 */
Jeff Thompsonbf50a1a2013-08-20 18:01:01 -070053class Face {
Jeff Thompsonaa4e6db2013-07-15 17:25:23 -070054public:
Alexander Afanasyev0222fba2014-02-09 23:16:02 -080055 struct Error : public std::runtime_error { Error(const std::string &what) : std::runtime_error(what) {} };
Alexander Afanasyevb790d952014-01-24 12:07:53 -080056
57 /**
Alexander Afanasyev0222fba2014-02-09 23:16:02 -080058 * @brief Create a new Face for communication with an NDN Forwarder using the default UnixTransport.
Alexander Afanasyevb790d952014-01-24 12:07:53 -080059 */
Alexander Afanasyev0222fba2014-02-09 23:16:02 -080060 Face(bool nfdMode = false);
Alexander Afanasyeve2e0d752014-01-03 13:30:30 -080061
62 /**
Alexander Afanasyev0222fba2014-02-09 23:16:02 -080063 * @brief Create a new Face for communication with an NDN Forwarder using the default UnixTransport.
Alexander Afanasyevb790d952014-01-24 12:07:53 -080064 * @param ioService A shared pointer to boost::io_service object that should control all IO operations
Jeff Thompsonfe08e5a2013-08-13 11:15:59 -070065 */
Alexander Afanasyev0222fba2014-02-09 23:16:02 -080066 Face(const ptr_lib::shared_ptr<boost::asio::io_service> &ioService, bool nfdMode = false);
Jeff Thompsonb982b6d2013-07-15 18:15:45 -070067
Jeff Thompsonfe08e5a2013-08-13 11:15:59 -070068 /**
Jeff Thompson86507bc2013-08-23 20:51:38 -070069 * Create a new Face for communication with an NDN hub at host:port using the default TcpTransport.
Jeff Thompsonfe08e5a2013-08-13 11:15:59 -070070 * @param host The host of the NDN hub.
Alexander Afanasyev20d2c582014-01-26 15:32:51 -080071 * @param port The port or service name of the NDN hub. If omitted. use 6363.
Jeff Thompsonfe08e5a2013-08-13 11:15:59 -070072 */
Alexander Afanasyev0222fba2014-02-09 23:16:02 -080073 Face(const std::string &host, const std::string &port = "6363", bool nfdMode = false);
74
75 /**
76 * Create a new Face for communication with an NDN hub with the given Transport object and connectionInfo.
77 * @param transport A shared_ptr to a Transport object used for communication.
78 * @param transport A shared_ptr to a Transport::ConnectionInfo to be used to connect to the transport.
79 */
80 Face(const shared_ptr<Transport>& transport, bool nfdMode = false);
81
82 /**
83 * @brief Alternative (special use case) version of the constructor, can be used to aggregate
84 * several Faces within one processing thread
85 *
86 * <code>
87 * Face face1(...);
88 * Face face2(..., face1.getAsyncService());
89 *
90 * // Now the following ensures that events on both faces are processed
91 * face1.processEvents();
92 * </code>
93 */
94 Face(const shared_ptr<Transport>& transport,
95 const shared_ptr<boost::asio::io_service> &ioService,
96 bool nfdMode = false);
Alexander Afanasyev20d2c582014-01-26 15:32:51 -080097
Jeff Thompson4fe45512013-08-23 14:06:38 -070098 /**
Alexander Afanasyev0222fba2014-02-09 23:16:02 -080099 * @brief Express Interest
100 *
101 * @param interest A reference to the Interest. This copies the Interest.
102 * @param onData A function object to call when a matching data packet is received.
103 * @param onTimeout A function object to call if the interest times out.
104 * If onTimeout is an empty OnTimeout(), this does not use it.
105 *
Jeff Thompson11095142013-10-01 16:20:28 -0700106 * @return The pending interest ID which can be used with removePendingInterest.
Jeff Thompson4fe45512013-08-23 14:06:38 -0700107 */
Alexander Afanasyevb790d952014-01-24 12:07:53 -0800108 const PendingInterestId*
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800109 expressInterest(const Interest& interest,
110 const OnData& onData, const OnTimeout& onTimeout = OnTimeout());
Jeff Thompson4fe45512013-08-23 14:06:38 -0700111
112 /**
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800113 * @brief Express Interest using name and Interest template
114 *
115 * @param name Name of the Interest
116 * @param tmpl Interest template to fill parameters
117 * @param onData A callback to call when a matching data packet is received.
118 * @param onTimeout A callback to call if the interest times out.
119 * If onTimeout is an empty OnTimeout(), this does not use it.
120 *
Jeff Thompson11095142013-10-01 16:20:28 -0700121 * @return The pending interest ID which can be used with removePendingInterest.
Jeff Thompson7aec0252013-08-22 17:29:57 -0700122 */
Alexander Afanasyevb790d952014-01-24 12:07:53 -0800123 const PendingInterestId*
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800124 expressInterest(const Name& name,
125 const Interest &tmpl,
126 const OnData& onData, const OnTimeout& onTimeout = OnTimeout());
127
Jeff Thompson11095142013-10-01 16:20:28 -0700128 /**
129 * Remove the pending interest entry with the pendingInterestId from the pending interest table.
130 * This does not affect another pending interest with a different pendingInterestId, even it if has the same interest name.
131 * If there is no entry with the pendingInterestId, do nothing.
132 * @param pendingInterestId The ID returned from expressInterest.
133 */
134 void
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800135 removePendingInterest(const PendingInterestId *pendingInterestId);
Jeff Thompsoncdf7e252013-07-31 12:41:47 -0700136
Jeff Thompson432c8be2013-08-09 16:16:08 -0700137 /**
Jeff Thompson86507bc2013-08-23 20:51:38 -0700138 * Register prefix with the connected NDN hub and call onInterest when a matching interest is received.
139 * @param prefix A reference to a Name for the prefix to register. This copies the Name.
140 * @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 -0800141 * use ref() as appropriate.
Jeff Thompson590ec232013-09-18 15:55:56 -0700142 * @param onRegisterFailed A function object to call if failed to retrieve the connected hub’s ID or failed to register the prefix.
143 * This calls onRegisterFailed(prefix) where prefix is the prefix given to registerPrefix.
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800144 * @param flags The flags for finer control of which interests are forward to the application.
Jeff Thompson11095142013-10-01 16:20:28 -0700145 * @return The registered prefix ID which can be used with removeRegisteredPrefix.
Jeff Thompson86507bc2013-08-23 20:51:38 -0700146 */
Alexander Afanasyevb790d952014-01-24 12:07:53 -0800147 const RegisteredPrefixId*
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800148 setInterestFilter(const Name& prefix,
149 const OnInterest& onInterest,
150 const OnSetInterestFilterFailed& onSetInterestFilterFailed);
Jeff Thompson11095142013-10-01 16:20:28 -0700151
152 /**
153 * Remove the registered prefix entry with the registeredPrefixId from the pending interest table.
154 * This does not affect another registered prefix with a different registeredPrefixId, even it if has the same prefix name.
155 * If there is no entry with the registeredPrefixId, do nothing.
156 * @param registeredPrefixId The ID returned from registerPrefix.
157 */
158 void
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800159 unsetInterestFilter(const RegisteredPrefixId *registeredPrefixId);
Alexander Afanasyeva557d5a2013-12-28 21:59:03 -0800160
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800161 /**
Alexander Afanasyeva557d5a2013-12-28 21:59:03 -0800162 * @brief Publish data packet
163 *
164 * This method can be called to satisfy the incoming Interest or to put Data packet into the cache
165 * of the local NDN forwarder
166 */
167 void
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800168 put(const Data &data);
169
Jeff Thompson86507bc2013-08-23 20:51:38 -0700170 /**
Jeff Thompsonbf50a1a2013-08-20 18:01:01 -0700171 * Process any data to receive or call timeout callbacks.
Alexander Afanasyeva557d5a2013-12-28 21:59:03 -0800172 *
173 * This call will block forever (default timeout == 0) to process IO on the face.
174 * To exit, one expected to call face.shutdown() from one of the callback methods.
175 *
Alexander Afanasyevf75a0aa2014-01-09 14:29:22 -0800176 * If positive timeout is specified, then processEvents will exit after this timeout,
177 * if not stopped earlier with face.shutdown() or when all active events finish.
Alexander Afanasyeva557d5a2013-12-28 21:59:03 -0800178 * The call can be called repeatedly, if desired.
179 *
Alexander Afanasyevf75a0aa2014-01-09 14:29:22 -0800180 * If negative timeout is specified, then processEvents will not block and process only pending
181 * events.
182 *
Jeff Thompson432c8be2013-08-09 16:16:08 -0700183 * @throw This may throw an exception for reading data or in the callback for processing the data. If you
184 * call this from an main event loop, you may want to catch and log/disregard all exceptions.
185 */
Jeff Thompson0050abe2013-09-17 12:50:25 -0700186 void
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800187 processEvents(Milliseconds timeout = 0, bool keepThread = false);
Jeff Thompson432c8be2013-08-09 16:16:08 -0700188
Jeff Thompson0050abe2013-09-17 12:50:25 -0700189 void
190 shutdown();
Yingdi Yu0d920812014-01-30 14:50:57 -0800191
192 shared_ptr<boost::asio::io_service>
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800193 ioService() { return ioService_; }
194
195private:
196 void
197 construct(const shared_ptr<Transport>& transport, const shared_ptr<boost::asio::io_service> &ioService, bool nfdMode);
198
199 struct ProcessEventsTimeout {};
200 typedef std::list<shared_ptr<PendingInterest> > PendingInterestTable;
201 typedef std::list<shared_ptr<RegisteredPrefix> > RegisteredPrefixTable;
202
203 void
204 asyncExpressInterest(const shared_ptr<const Interest> &interest,
205 const OnData& onData, const OnTimeout& onTimeout);
206
207 void
208 asyncRemovePendingInterest(const PendingInterestId *pendingInterestId);
209
210 void
211 asyncUnsetInterestFilter(const RegisteredPrefixId *registeredPrefixId);
Alexander Afanasyev12dfbad2014-02-11 14:42:46 -0800212
213 void
214 finalizeUnsertInterestFilter(RegisteredPrefixTable::iterator item);
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800215
216 void
217 onReceiveElement(const Block &wire);
218
219
220 static void
221 fireProcessEventsTimeout(const boost::system::error_code& error);
222
223 /**
224 * Find the entry from the pit_ where the name conforms to the entry's interest selectors, and
225 * the entry interest name is the longest that matches name.
226 * @param name The name to find the interest for (from the incoming data packet).
227 * @return The index in pit_ of the pit entry, or -1 if not found.
228 */
229 PendingInterestTable::iterator
230 getEntryIndexForExpressedInterest(const Name& name);
231
232 /**
233 * Find the first entry from the registeredPrefixTable_ where the entry prefix is the longest that matches name.
234 * @param name The name to find the PrefixEntry for (from the incoming interest packet).
235 * @return A pointer to the entry, or 0 if not found.
236 */
237 RegisteredPrefixTable::iterator
238 getEntryForRegisteredPrefix(const Name& name);
239
240
241 void
242 checkPitExpire();
Jeff Thompson517ffa82013-08-05 16:04:34 -0700243
Jeff Thompsonb982b6d2013-07-15 18:15:45 -0700244private:
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800245 shared_ptr<boost::asio::io_service> ioService_;
246 shared_ptr<boost::asio::io_service::work> ioServiceWork_; // needed if thread needs to be preserved
247 shared_ptr<boost::asio::deadline_timer> pitTimeoutCheckTimer_;
248 bool pitTimeoutCheckTimerActive_;
249 shared_ptr<boost::asio::deadline_timer> processEventsTimeoutTimer_;
250
251 shared_ptr<Transport> transport_;
252
253 PendingInterestTable pendingInterestTable_;
254 RegisteredPrefixTable registeredPrefixTable_;
255
256 shared_ptr<Controller> m_fwController;
Jeff Thompsonaa4e6db2013-07-15 17:25:23 -0700257};
258
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800259} // namespace ndn
Jeff Thompsonaa4e6db2013-07-15 17:25:23 -0700260
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800261#endif // NDN_FACE_HPP