blob: 11800c819fcf9f2e24bb2a642a14051c0ac21f7f [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/**
Alexander Afanasyevdfa52c42014-04-24 21:10:11 -07003 * Copyright (c) 2013-2014, Regents of the University of California.
4 * All rights reserved.
5 *
6 * This file is part of ndn-cxx library (NDN C++ library with eXperimental eXtensions).
7 * See AUTHORS.md for complete list of ndn-cxx authors and contributors.
8 *
9 * This file licensed under New BSD License. See COPYING for detailed information about
10 * ndn-cxx library copyright, permissions, and redistribution restrictions.
11 *
12 * Based on code originally written by Jeff Thompson <jefft0@remap.ucla.edu>
Jeff Thompsonaa4e6db2013-07-15 17:25:23 -070013 */
14
Jeff Thompsonb9e3c8e2013-08-02 11:42:51 -070015#ifndef NDN_FACE_HPP
Jeff Thompsona0d18c92013-08-06 13:55:32 -070016#define NDN_FACE_HPP
Jeff Thompsonaa4e6db2013-07-15 17:25:23 -070017
Alexander Afanasyev0222fba2014-02-09 23:16:02 -080018#include "common.hpp"
19#include "interest.hpp"
20#include "data.hpp"
Alexander Afanasyev984ad192014-05-02 19:11:15 -070021#include "security/identity-certificate.hpp"
Alexander Afanasyev0222fba2014-02-09 23:16:02 -080022
Alexander Afanasyeve2e0d752014-01-03 13:30:30 -080023#include "transport/transport.hpp"
24#include "transport/unix-transport.hpp"
Alexander Afanasyev20d2c582014-01-26 15:32:51 -080025#include "transport/tcp-transport.hpp"
Jeff Thompsonbeb8b7d2013-07-16 15:49:21 -070026
Alexander Afanasyevaa0e7da2014-03-17 14:37:33 -070027#include "util/scheduler.hpp"
Alexander Afanasyev0222fba2014-02-09 23:16:02 -080028#include "detail/registered-prefix.hpp"
29#include "detail/pending-interest.hpp"
30
Jeff Thompsonaa4e6db2013-07-15 17:25:23 -070031namespace ndn {
32
Alexander Afanasyevee8bb1e2014-05-02 17:39:54 -070033namespace nfd {
34class Controller;
35}
Alexander Afanasyevee8bb1e2014-05-02 17:39:54 -070036
Jeff Thompsonfe08e5a2013-08-13 11:15:59 -070037/**
Alexander Afanasyev984ad192014-05-02 19:11:15 -070038 * @brief Callback called when expressed Interest gets satisfied with Data packet
Alexander Afanasyev0222fba2014-02-09 23:16:02 -080039 */
40typedef function<void(const Interest&, Data&)> OnData;
41
42/**
Alexander Afanasyev984ad192014-05-02 19:11:15 -070043 * @brief Callback called when expressed Interest times out
Alexander Afanasyev0222fba2014-02-09 23:16:02 -080044 */
45typedef function<void(const Interest&)> OnTimeout;
46
47/**
Alexander Afanasyev984ad192014-05-02 19:11:15 -070048 * @brief Callback called when incoming Interest matches the specified InterestFilter
Alexander Afanasyev0222fba2014-02-09 23:16:02 -080049 */
Alexander Afanasyev90164962014-03-06 08:29:59 +000050typedef function<void (const InterestFilter&, const Interest&)> OnInterest;
Alexander Afanasyev0222fba2014-02-09 23:16:02 -080051
52/**
Alexander Afanasyev984ad192014-05-02 19:11:15 -070053 * @brief Callback called when registerPrefix or setInterestFilter command succeeds
Alexander Afanasyev0222fba2014-02-09 23:16:02 -080054 */
Alexander Afanasyev984ad192014-05-02 19:11:15 -070055typedef function<void(const Name&)> RegisterPrefixSuccessCallback;
Alexander Afanasyev0222fba2014-02-09 23:16:02 -080056
Alexander Afanasyev984ad192014-05-02 19:11:15 -070057/**
58 * @brief Callback called when registerPrefix or setInterestFilter command fails
59 */
60typedef function<void(const Name&, const std::string&)> RegisterPrefixFailureCallback;
61
62/**
63 * @brief Callback called when unregisterPrefix or unsetInterestFilter command succeeds
64 */
65typedef function<void()> UnregisterPrefixSuccessCallback;
66
67/**
68 * @brief Callback called when unregisterPrefix or unsetInterestFilter command fails
69 */
70typedef function<void(const std::string&)> UnregisterPrefixFailureCallback;
Alexander Afanasyev0222fba2014-02-09 23:16:02 -080071
72
73/**
74 * @brief Abstraction to communicate with local or remote NDN forwarder
Jeff Thompsonfe08e5a2013-08-13 11:15:59 -070075 */
Alexander Afanasyev8460afb2014-02-15 20:31:42 -080076class Face : noncopyable
77{
Jeff Thompsonaa4e6db2013-07-15 17:25:23 -070078public:
Alexander Afanasyevfdbfc6d2014-04-14 15:12:11 -070079 class Error : public std::runtime_error
80 {
81 public:
82 explicit
83 Error(const std::string& what)
84 : std::runtime_error(what)
85 {
86 }
87 };
Alexander Afanasyevb790d952014-01-24 12:07:53 -080088
89 /**
Alexander Afanasyev691c3ce2014-04-23 14:28:04 -070090 * @brief Create a new Face using the default transport (UnixTransport)
91 *
Steve DiBenedettoc07b3a22014-03-19 12:32:52 -060092 * @throws ConfigFile::Error on configuration file parse failure
93 * @throws Face::Error on unsupported protocol
Alexander Afanasyevb790d952014-01-24 12:07:53 -080094 */
Alexander Afanasyevf7ca3202014-02-14 22:28:31 -080095 Face();
Alexander Afanasyeve2e0d752014-01-03 13:30:30 -080096
97 /**
Alexander Afanasyev691c3ce2014-04-23 14:28:04 -070098 * @brief Create a new Face using the default transport (UnixTransport)
99 *
100 * @deprecated This constructor is deprecated. Use `Face(boost::asio::io_service&)`
101 * instead.
102 *
103 * @param ioService A shared pointer to boost::io_service object that should control all
104 * IO operations
Steve DiBenedettoc07b3a22014-03-19 12:32:52 -0600105 * @throws ConfigFile::Error on configuration file parse failure
106 * @throws Face::Error on unsupported protocol
Jeff Thompsonfe08e5a2013-08-13 11:15:59 -0700107 */
Alexander Afanasyevf7ca3202014-02-14 22:28:31 -0800108 explicit
Alexander Afanasyev7682ccb2014-02-20 10:29:35 -0800109 Face(const shared_ptr<boost::asio::io_service>& ioService);
110
Jeff Thompsonfe08e5a2013-08-13 11:15:59 -0700111 /**
Alexander Afanasyev691c3ce2014-04-23 14:28:04 -0700112 * @brief Create a new Face using the default transport (UnixTransport)
113 *
114 * @par Usage examples:
115 *
116 * Face face1;
117 * Face face2(face1.getIoService());
118 *
119 * // Now the following ensures that events on both faces are processed
120 * face1.processEvents();
121 * // or face1.getIoService().run();
122 *
123 * @par or
124 *
125 * boost::asio::io_service ioService;
126 * Face face1(ioService);
127 * Face face2(ioService);
128 * ...
129 *
130 * ioService.run();
131 *
132 * @param ioService A reference to boost::io_service object that should control all
133 * IO operations.
134 * @throws ConfigFile::Error on configuration file parse failure
135 * @throws Face::Error on unsupported protocol
136 */
137 explicit
138 Face(boost::asio::io_service& ioService);
139
140 /**
141 * @brief Create a new Face using TcpTransport
142 *
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700143 * @param host The host of the NDN forwarder
144 * @param port (optional) The port or service name of the NDN forwarder (**default**: "6363")
145 *
Steve DiBenedettoc07b3a22014-03-19 12:32:52 -0600146 * @throws Face::Error on unsupported protocol
Jeff Thompsonfe08e5a2013-08-13 11:15:59 -0700147 */
Alexander Afanasyev7682ccb2014-02-20 10:29:35 -0800148 Face(const std::string& host, const std::string& port = "6363");
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800149
150 /**
Alexander Afanasyev691c3ce2014-04-23 14:28:04 -0700151 * @brief Create a new Face using the given Transport
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700152 *
153 * @param transport A shared_ptr to a Transport object used for communication
154 *
Steve DiBenedettoc07b3a22014-03-19 12:32:52 -0600155 * @throws Face::Error on unsupported protocol
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800156 */
Alexander Afanasyevf7ca3202014-02-14 22:28:31 -0800157 explicit
158 Face(const shared_ptr<Transport>& transport);
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800159
160 /**
Alexander Afanasyev691c3ce2014-04-23 14:28:04 -0700161 * @brief Create a new Face using the given Transport and IO service object
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800162 *
Alexander Afanasyev691c3ce2014-04-23 14:28:04 -0700163 * @sa Face(boost::asio::io_service&)
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800164 *
Steve DiBenedettoc07b3a22014-03-19 12:32:52 -0600165 * @throws Face::Error on unsupported protocol
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800166 */
167 Face(const shared_ptr<Transport>& transport,
Alexander Afanasyev691c3ce2014-04-23 14:28:04 -0700168 boost::asio::io_service& ioService);
Alexander Afanasyev7682ccb2014-02-20 10:29:35 -0800169
Alexander Afanasyevee8bb1e2014-05-02 17:39:54 -0700170
171 ~Face();
Alexander Afanasyevfdbfc6d2014-04-14 15:12:11 -0700172
Jeff Thompson4fe45512013-08-23 14:06:38 -0700173 /**
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800174 * @brief Express Interest
175 *
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700176 * @param interest An Interest to be expressed
177 * @param onData Callback to be called when a matching data packet is received
178 * @param onTimeout (optional) A function object to call if the interest times out
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800179 *
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700180 * @return The pending interest ID which can be used with removePendingInterest
Jeff Thompson4fe45512013-08-23 14:06:38 -0700181 */
Alexander Afanasyevb790d952014-01-24 12:07:53 -0800182 const PendingInterestId*
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800183 expressInterest(const Interest& interest,
184 const OnData& onData, const OnTimeout& onTimeout = OnTimeout());
Jeff Thompson4fe45512013-08-23 14:06:38 -0700185
186 /**
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800187 * @brief Express Interest using name and Interest template
188 *
189 * @param name Name of the Interest
190 * @param tmpl Interest template to fill parameters
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700191 * @param onData Callback to be called when a matching data packet is received
192 * @param onTimeout (optional) A function object to call if the interest times out
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800193 *
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700194 * @return Opaque pending interest ID which can be used with removePendingInterest
Jeff Thompson7aec0252013-08-22 17:29:57 -0700195 */
Alexander Afanasyevb790d952014-01-24 12:07:53 -0800196 const PendingInterestId*
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800197 expressInterest(const Name& name,
Alexander Afanasyev7682ccb2014-02-20 10:29:35 -0800198 const Interest& tmpl,
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800199 const OnData& onData, const OnTimeout& onTimeout = OnTimeout());
Alexander Afanasyevfdbfc6d2014-04-14 15:12:11 -0700200
Jeff Thompson11095142013-10-01 16:20:28 -0700201 /**
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700202 * @brief Cancel previously expressed Interest
Alexander Afanasyev691c3ce2014-04-23 14:28:04 -0700203 *
Jeff Thompson11095142013-10-01 16:20:28 -0700204 * @param pendingInterestId The ID returned from expressInterest.
205 */
206 void
Alexander Afanasyev7682ccb2014-02-20 10:29:35 -0800207 removePendingInterest(const PendingInterestId* pendingInterestId);
Alexander Afanasyevfdbfc6d2014-04-14 15:12:11 -0700208
Jeff Thompson432c8be2013-08-09 16:16:08 -0700209 /**
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700210 * @brief Set InterestFilter to dispatch incoming matching interest to onInterest
211 * callback and register the filtered prefix with the connected NDN forwarder
212 *
213 * This version of setInterestFilter combines setInterestFilter and registerPrefix
214 * operations and is intended to be used when only one filter for the same prefix needed
215 * to be set. When multiple names sharing the same prefix should be dispatched to
216 * different callbacks, use one registerPrefix call, followed (in onSuccess callback) by
217 * a series of setInterestFilter calls.
Alexander Afanasyev691c3ce2014-04-23 14:28:04 -0700218 *
Alexander Afanasyev90164962014-03-06 08:29:59 +0000219 * @param interestFilter Interest filter (prefix part will be registered with the forwarder)
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700220 * @param onInterest A callback to be called when a matching interest is received
221 * @param onSuccess A callback to be called when prefixRegister command succeeds
222 * @param onFailure A callback to be called when prefixRegister command fails
223 * @param certificate (optional) A certificate under which the prefix registration
224 * command interest is signed. When omitted, a default certificate
225 * of the default identity is used to sign the registration command
Alexander Afanasyev691c3ce2014-04-23 14:28:04 -0700226 *
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700227 * @return Opaque registered prefix ID which can be used with unsetInterestFilter or
228 * removeRegisteredPrefix
Jeff Thompson86507bc2013-08-23 20:51:38 -0700229 */
Alexander Afanasyevb790d952014-01-24 12:07:53 -0800230 const RegisteredPrefixId*
Alexander Afanasyev90164962014-03-06 08:29:59 +0000231 setInterestFilter(const InterestFilter& interestFilter,
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800232 const OnInterest& onInterest,
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700233 const RegisterPrefixSuccessCallback& onSuccess,
234 const RegisterPrefixFailureCallback& onFailure,
235 const IdentityCertificate& certificate = IdentityCertificate());
Jeff Thompson11095142013-10-01 16:20:28 -0700236
237 /**
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700238 * @deprecated Use the other overload
Yingdi Yue66bf2a2014-04-28 17:07:36 -0700239 */
240 const RegisteredPrefixId*
Alexander Afanasyev90164962014-03-06 08:29:59 +0000241 setInterestFilter(const InterestFilter& interestFilter,
Yingdi Yue66bf2a2014-04-28 17:07:36 -0700242 const OnInterest& onInterest,
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700243 const RegisterPrefixFailureCallback& onFailure,
244 const IdentityCertificate& certificate = IdentityCertificate());
Yingdi Yue66bf2a2014-04-28 17:07:36 -0700245
246 /**
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700247 * @brief Set InterestFilter to dispatch incoming matching interest to onInterest
248 * callback and register the filtered prefix with the connected NDN forwarder
249 *
250 * This version of setInterestFilter combines setInterestFilter and registerPrefix
251 * operations and is intended to be used when only one filter for the same prefix needed
252 * to be set. When multiple names sharing the same prefix should be dispatched to
253 * different callbacks, use one registerPrefix call, followed (in onSuccess callback) by
254 * a series of setInterestFilter calls.
Yingdi Yue66bf2a2014-04-28 17:07:36 -0700255 *
Alexander Afanasyev90164962014-03-06 08:29:59 +0000256 * @param interestFilter Interest filter (prefix part will be registered with the forwarder)
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700257 * @param onInterest A callback to be called when a matching interest is received
258 * @param onSuccess A callback to be called when prefixRegister command succeeds
259 * @param onFailure A callback to be called when prefixRegister command fails
260 * @param identity A signing identity. A command interest is signed under the default
261 * certificate of this identity
Yingdi Yue66bf2a2014-04-28 17:07:36 -0700262 *
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700263 * @return Opaque registered prefix ID which can be used with removeRegisteredPrefix
Yingdi Yue66bf2a2014-04-28 17:07:36 -0700264 */
265 const RegisteredPrefixId*
Alexander Afanasyev90164962014-03-06 08:29:59 +0000266 setInterestFilter(const InterestFilter& interestFilter,
Yingdi Yue66bf2a2014-04-28 17:07:36 -0700267 const OnInterest& onInterest,
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700268 const RegisterPrefixSuccessCallback& onSuccess,
269 const RegisterPrefixFailureCallback& onFailure,
Yingdi Yue66bf2a2014-04-28 17:07:36 -0700270 const Name& identity);
271
272 /**
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700273 * @deprecated Use the other overload
274 */
275 const RegisteredPrefixId*
276 setInterestFilter(const InterestFilter& interestFilter,
277 const OnInterest& onInterest,
278 const RegisterPrefixFailureCallback& onFailure,
279 const Name& identity);
280
281 /**
282 * @brief Set InterestFilter to dispatch incoming matching interest to onInterest callback
283 *
284 * @param interestFilter Interest
285 * @param onInterest A callback to be called when a matching interest is received
286 *
287 * This method modifies library's FIB only, and does not register the prefix with the
288 * forwarder. It will always succeed. To register prefix with the forwarder, use
289 * registerPrefix, or use the setInterestFilter overload taking two callbacks.
290 *
291 * @return Opaque interest filter ID which can be used with unsetInterestFilter
292 */
293 const InterestFilterId*
294 setInterestFilter(const InterestFilter& interestFilter,
295 const OnInterest& onInterest);
296
297
298 /**
299 * @brief Register prefix with the connected NDN forwarder
300 *
301 * This method only modifies forwarder's RIB (or FIB) and does not associate any
302 * onInterest callbacks. Use setInterestFilter method to dispatch incoming Interests to
303 * the right callbacks.
304 *
305 * @param prefix A prefix to register with the connected NDN forwarder
306 * @param onSuccess A callback to be called when prefixRegister command succeeds
307 * @param onFailure A callback to be called when prefixRegister command fails
308 * @param certificate (optional) A certificate under which the prefix registration
309 * command interest is signed. When omitted, a default certificate
310 * of the default identity is used to sign the registration command
311 *
312 * @return The registered prefix ID which can be used with unregisterPrefix
313 */
314 const RegisteredPrefixId*
315 registerPrefix(const Name& prefix,
316 const RegisterPrefixSuccessCallback& onSuccess,
317 const RegisterPrefixFailureCallback& onFailure,
318 const IdentityCertificate& certificate = IdentityCertificate());
319
320 /**
321 * @brief Register prefix with the connected NDN forwarder and call onInterest when a matching
322 * interest is received.
323 *
324 * This method only modifies forwarder's RIB (or FIB) and does not associate any
325 * onInterest callbacks. Use setInterestFilter method to dispatch incoming Interests to
326 * the right callbacks.
327 *
328 * @param prefix A prefix to register with the connected NDN forwarder
329 * @param onSuccess A callback to be called when prefixRegister command succeeds
330 * @param onFailure A callback to be called when prefixRegister command fails
331 * @param identity A signing identity. A command interest is signed under the default
332 * certificate of this identity
333 *
334 * @return The registered prefix ID which can be used with unregisterPrefix
335 */
336 const RegisteredPrefixId*
337 registerPrefix(const Name& prefix,
338 const RegisterPrefixSuccessCallback& onSuccess,
339 const RegisterPrefixFailureCallback& onFailure,
340 const Name& identity);
341
342
343 /**
Alexander Afanasyev691c3ce2014-04-23 14:28:04 -0700344 * @brief Remove the registered prefix entry with the registeredPrefixId from the
345 * pending interest table.
346 *
347 * This does not affect another registered prefix with a different registeredPrefixId,
348 * even it if has the same prefix name. If there is no entry with the
349 * registeredPrefixId, do nothing.
350 *
Alexander Afanasyevee8bb1e2014-05-02 17:39:54 -0700351 * unsetInterestFilter will use the same credentials as original
352 * setInterestFilter/registerPrefix command
353 *
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700354 * @param registeredPrefixId The ID returned from registerPrefix
Jeff Thompson11095142013-10-01 16:20:28 -0700355 */
356 void
Alexander Afanasyev7682ccb2014-02-20 10:29:35 -0800357 unsetInterestFilter(const RegisteredPrefixId* registeredPrefixId);
Alexander Afanasyeva557d5a2013-12-28 21:59:03 -0800358
Alexander Afanasyevee8bb1e2014-05-02 17:39:54 -0700359 /**
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700360 * @brief Remove previously set InterestFilter from library's FIB
361 *
362 * This method always succeeds and will **NOT** send any request to the connected
363 * forwarder.
364 *
365 * @param interestFilterId The ID returned from setInterestFilter.
366 */
367 void
368 unsetInterestFilter(const InterestFilterId* interestFilterId);
369
370 /**
371 * @brief Deregister prefix from RIB (or FIB)
372 *
373 * unregisterPrefix will use the same credentials as original
374 * setInterestFilter/registerPrefix command
375 *
376 * If registeredPrefixId was obtained using setInterestFilter, the corresponding
377 * InterestFilter will be unset too.
378 *
379 * @param registeredPrefixId The ID returned from registerPrefix.
380 */
381 void
382 unregisterPrefix(const RegisteredPrefixId* registeredPrefixId,
383 const UnregisterPrefixSuccessCallback& onSuccess,
384 const UnregisterPrefixFailureCallback& onFailure);
385
386 /**
Alexander Afanasyevee8bb1e2014-05-02 17:39:54 -0700387 * @brief (FOR DEBUG PURPOSES ONLY) Request direct NFD FIB management
388 */
Yingdi Yue66bf2a2014-04-28 17:07:36 -0700389 void
Alexander Afanasyevee8bb1e2014-05-02 17:39:54 -0700390 setDirectFibManagement(bool isDirectFibManagementRequested = false);
Yingdi Yue66bf2a2014-04-28 17:07:36 -0700391
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800392 /**
Alexander Afanasyeva557d5a2013-12-28 21:59:03 -0800393 * @brief Publish data packet
394 *
Alexander Afanasyev691c3ce2014-04-23 14:28:04 -0700395 * This method can be called to satisfy the incoming Interest or to put Data packet into
396 * the cache of the local NDN forwarder
Alexander Afanasyeva557d5a2013-12-28 21:59:03 -0800397 */
398 void
Alexander Afanasyev7682ccb2014-02-20 10:29:35 -0800399 put(const Data& data);
Alexander Afanasyevfdbfc6d2014-04-14 15:12:11 -0700400
Jeff Thompson86507bc2013-08-23 20:51:38 -0700401 /**
Alexander Afanasyev691c3ce2014-04-23 14:28:04 -0700402 * @brief Process any data to receive or call timeout callbacks.
Alexander Afanasyeva557d5a2013-12-28 21:59:03 -0800403 *
404 * This call will block forever (default timeout == 0) to process IO on the face.
405 * To exit, one expected to call face.shutdown() from one of the callback methods.
406 *
Alexander Afanasyev691c3ce2014-04-23 14:28:04 -0700407 * If positive timeout is specified, then processEvents will exit after this timeout, if
408 * not stopped earlier with face.shutdown() or when all active events finish. The call
409 * can be called repeatedly, if desired.
Alexander Afanasyeva557d5a2013-12-28 21:59:03 -0800410 *
Alexander Afanasyev691c3ce2014-04-23 14:28:04 -0700411 * If negative timeout is specified, then processEvents will not block and process only
412 * pending events.
Alexander Afanasyevf75a0aa2014-01-09 14:29:22 -0800413 *
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700414 * @param timeout maximum time to block the thread
Alexander Afanasyev691c3ce2014-04-23 14:28:04 -0700415 * @param keepThread Keep thread in a blocked state (in event processing), even when
416 * there are no outstanding events (e.g., no Interest/Data is expected)
417 *
418 * @throw This may throw an exception for reading data or in the callback for processing
419 * the data. If you call this from an main event loop, you may want to catch and
420 * log/disregard all exceptions.
Jeff Thompson432c8be2013-08-09 16:16:08 -0700421 */
Alexander Afanasyevfdbfc6d2014-04-14 15:12:11 -0700422 void
Alexander Afanasyevaa0e7da2014-03-17 14:37:33 -0700423 processEvents(const time::milliseconds& timeout = time::milliseconds::zero(),
424 bool keepThread = false);
Jeff Thompson432c8be2013-08-09 16:16:08 -0700425
Alexander Afanasyev691c3ce2014-04-23 14:28:04 -0700426 /**
427 * @brief Shutdown face operations
428 *
429 * This method cancels all pending operations and closes connection to NDN Forwarder.
430 *
431 * Note that this method does not stop IO service and if the same IO service is shared
432 * between multiple Faces or with other IO objects (e.g., Scheduler).
433 */
Alexander Afanasyevfdbfc6d2014-04-14 15:12:11 -0700434 void
Jeff Thompson0050abe2013-09-17 12:50:25 -0700435 shutdown();
Yingdi Yu0d920812014-01-30 14:50:57 -0800436
Alexander Afanasyev691c3ce2014-04-23 14:28:04 -0700437 /**
438 * @brief Get shared_ptr of the IO service object
439 *
440 * @deprecated Use getIoService instead
441 */
Alexander Afanasyevfdbfc6d2014-04-14 15:12:11 -0700442 shared_ptr<boost::asio::io_service>
Alexander Afanasyev691c3ce2014-04-23 14:28:04 -0700443 ioService()
444 {
445 return m_ioService;
446 }
447
448 /**
449 * @brief Get reference to IO service object
450 */
451 boost::asio::io_service&
452 getIoService()
453 {
454 return *m_ioService;
455 }
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800456
457private:
Steve DiBenedettoc07b3a22014-03-19 12:32:52 -0600458
459 /**
460 * @throws Face::Error on unsupported protocol
461 */
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800462 void
Alexander Afanasyev7682ccb2014-02-20 10:29:35 -0800463 construct(const shared_ptr<Transport>& transport,
Alexander Afanasyev505646e2014-02-24 20:13:37 -0800464 const shared_ptr<boost::asio::io_service>& ioService);
Steve DiBenedettoc07b3a22014-03-19 12:32:52 -0600465
466 bool
467 isSupportedNfdProtocol(const std::string& protocol);
468
469 bool
470 isSupportedNrdProtocol(const std::string& protocol);
471
Alexander Afanasyev691c3ce2014-04-23 14:28:04 -0700472 class ProcessEventsTimeout
473 {
474 };
475
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800476 typedef std::list<shared_ptr<PendingInterest> > PendingInterestTable;
Alexander Afanasyev90164962014-03-06 08:29:59 +0000477 typedef std::list<shared_ptr<InterestFilterRecord> > InterestFilterTable;
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800478 typedef std::list<shared_ptr<RegisteredPrefix> > RegisteredPrefixTable;
Alexander Afanasyevfdbfc6d2014-04-14 15:12:11 -0700479
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800480 void
Alexander Afanasyev6d48bc12014-02-18 00:10:51 -0800481 asyncExpressInterest(const shared_ptr<const Interest>& interest,
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800482 const OnData& onData, const OnTimeout& onTimeout);
483
484 void
Alexander Afanasyev6d48bc12014-02-18 00:10:51 -0800485 asyncRemovePendingInterest(const PendingInterestId* pendingInterestId);
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800486
487 void
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700488 afterPrefixRegistered(const shared_ptr<RegisteredPrefix>& registeredPrefix,
489 const RegisterPrefixSuccessCallback& onSuccess);
Alexander Afanasyev90164962014-03-06 08:29:59 +0000490
491 void
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700492 asyncSetInterestFilter(const shared_ptr<InterestFilterRecord>& interestFilterRecord);
Alexander Afanasyev12dfbad2014-02-11 14:42:46 -0800493
494 void
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700495 asyncUnsetInterestFilter(const InterestFilterId* interestFilterId);
496
497 void
498 asyncUnregisterPrefix(const RegisteredPrefixId* registeredPrefixId,
499 const UnregisterPrefixSuccessCallback& onSuccess,
500 const UnregisterPrefixFailureCallback& onFailure);
501
502 void
503 finalizeUnregisterPrefix(RegisteredPrefixTable::iterator item,
504 const UnregisterPrefixSuccessCallback& onSuccess);
Alexander Afanasyevfdbfc6d2014-04-14 15:12:11 -0700505
506 void
Alexander Afanasyev6d48bc12014-02-18 00:10:51 -0800507 onReceiveElement(const Block& wire);
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800508
Alexander Afanasyev7dced462014-03-19 15:12:32 -0700509 void
510 asyncShutdown();
Alexander Afanasyevfdbfc6d2014-04-14 15:12:11 -0700511
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800512 static void
513 fireProcessEventsTimeout(const boost::system::error_code& error);
514
Alexander Afanasyev42c81852014-02-25 21:37:26 -0800515 void
516 satisfyPendingInterests(Data& data);
517
518 void
519 processInterestFilters(Interest& interest);
Alexander Afanasyevfdbfc6d2014-04-14 15:12:11 -0700520
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800521 void
522 checkPitExpire();
Yingdi Yuf9fa52f2014-02-06 12:27:32 -0800523
Alexander Afanasyevee8bb1e2014-05-02 17:39:54 -0700524 template<class SignatureGenerator>
525 const RegisteredPrefixId*
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700526 registerPrefixImpl(const Name& prefix,
527 const shared_ptr<InterestFilterRecord>& filter,
528 const RegisterPrefixSuccessCallback& onSuccess,
529 const RegisterPrefixFailureCallback& onFailure,
530 const SignatureGenerator& signatureGenerator);
Alexander Afanasyevee8bb1e2014-05-02 17:39:54 -0700531
Jeff Thompsonb982b6d2013-07-15 18:15:45 -0700532private:
Alexander Afanasyevf39c5372014-02-17 19:42:56 -0800533 shared_ptr<boost::asio::io_service> m_ioService;
Alexander Afanasyev691c3ce2014-04-23 14:28:04 -0700534 shared_ptr<boost::asio::io_service::work> m_ioServiceWork; // if thread needs to be preserved
Alexander Afanasyevaa0e7da2014-03-17 14:37:33 -0700535 shared_ptr<monotonic_deadline_timer> m_pitTimeoutCheckTimer;
Alexander Afanasyevf39c5372014-02-17 19:42:56 -0800536 bool m_pitTimeoutCheckTimerActive;
Alexander Afanasyevaa0e7da2014-03-17 14:37:33 -0700537 shared_ptr<monotonic_deadline_timer> m_processEventsTimeoutTimer;
Alexander Afanasyevfdbfc6d2014-04-14 15:12:11 -0700538
Alexander Afanasyevf39c5372014-02-17 19:42:56 -0800539 shared_ptr<Transport> m_transport;
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800540
Alexander Afanasyevf39c5372014-02-17 19:42:56 -0800541 PendingInterestTable m_pendingInterestTable;
Alexander Afanasyev90164962014-03-06 08:29:59 +0000542 InterestFilterTable m_interestFilterTable;
Alexander Afanasyevf39c5372014-02-17 19:42:56 -0800543 RegisteredPrefixTable m_registeredPrefixTable;
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800544
Alexander Afanasyevee8bb1e2014-05-02 17:39:54 -0700545 nfd::Controller* m_nfdController;
546 bool m_isDirectNfdFibManagementRequested;
Steve DiBenedettoc07b3a22014-03-19 12:32:52 -0600547
548 ConfigFile m_config;
Jeff Thompsonaa4e6db2013-07-15 17:25:23 -0700549};
550
Steve DiBenedettoc07b3a22014-03-19 12:32:52 -0600551inline bool
552Face::isSupportedNfdProtocol(const std::string& protocol)
553{
554 return protocol == "nfd-0.1";
555}
556
557inline bool
558Face::isSupportedNrdProtocol(const std::string& protocol)
559{
560 return protocol == "nrd-0.1";
561}
562
Alexander Afanasyevee8bb1e2014-05-02 17:39:54 -0700563inline void
564Face::setDirectFibManagement(bool isDirectFibManagementRequested/* = false*/)
Steve DiBenedettoc07b3a22014-03-19 12:32:52 -0600565{
Alexander Afanasyevee8bb1e2014-05-02 17:39:54 -0700566 m_isDirectNfdFibManagementRequested = isDirectFibManagementRequested;
Steve DiBenedettoc07b3a22014-03-19 12:32:52 -0600567}
568
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800569} // namespace ndn
Jeff Thompsonaa4e6db2013-07-15 17:25:23 -0700570
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800571#endif // NDN_FACE_HPP