blob: b915e8327eaa8be9d46213db9a6afe2112cb8e03 [file] [log] [blame]
Alexander Afanasyevc169a812014-05-20 20:37:29 -04001/* -*- Mode:C++; c-file-style:"gnu"; indent-tabs-mode:nil; -*- */
Jeff Thompsonaa4e6db2013-07-15 17:25:23 -07002/**
Alexander Afanasyevc169a812014-05-20 20:37:29 -04003 * Copyright (c) 2013-2014 Regents of the University of California.
Alexander Afanasyevdfa52c42014-04-24 21:10:11 -07004 *
5 * This file is part of ndn-cxx library (NDN C++ library with eXperimental eXtensions).
Alexander Afanasyevdfa52c42014-04-24 21:10:11 -07006 *
Alexander Afanasyevc169a812014-05-20 20:37:29 -04007 * ndn-cxx library is free software: you can redistribute it and/or modify it under the
8 * terms of the GNU Lesser General Public License as published by the Free Software
9 * Foundation, either version 3 of the License, or (at your option) any later version.
10 *
11 * ndn-cxx library is distributed in the hope that it will be useful, but WITHOUT ANY
12 * WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
13 * PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
14 *
15 * You should have received copies of the GNU General Public License and GNU Lesser
16 * General Public License along with ndn-cxx, e.g., in COPYING.md file. If not, see
17 * <http://www.gnu.org/licenses/>.
18 *
19 * See AUTHORS.md for complete list of ndn-cxx authors and contributors.
Alexander Afanasyevdfa52c42014-04-24 21:10:11 -070020 *
21 * Based on code originally written by Jeff Thompson <jefft0@remap.ucla.edu>
Jeff Thompsonaa4e6db2013-07-15 17:25:23 -070022 */
23
Jeff Thompsonb9e3c8e2013-08-02 11:42:51 -070024#ifndef NDN_FACE_HPP
Jeff Thompsona0d18c92013-08-06 13:55:32 -070025#define NDN_FACE_HPP
Jeff Thompsonaa4e6db2013-07-15 17:25:23 -070026
Alexander Afanasyev0222fba2014-02-09 23:16:02 -080027#include "common.hpp"
Alexander Afanasyev258ec2b2014-05-14 16:15:37 -070028
29#include "name.hpp"
Alexander Afanasyev0222fba2014-02-09 23:16:02 -080030#include "interest.hpp"
Alexander Afanasyev258ec2b2014-05-14 16:15:37 -070031#include "interest-filter.hpp"
Alexander Afanasyev0222fba2014-02-09 23:16:02 -080032#include "data.hpp"
Alexander Afanasyev984ad192014-05-02 19:11:15 -070033#include "security/identity-certificate.hpp"
Alexander Afanasyev0222fba2014-02-09 23:16:02 -080034
Alexander Afanasyev258ec2b2014-05-14 16:15:37 -070035namespace boost {
36namespace asio {
37class io_service;
38}
39}
Alexander Afanasyev0222fba2014-02-09 23:16:02 -080040
Jeff Thompsonaa4e6db2013-07-15 17:25:23 -070041namespace ndn {
42
Alexander Afanasyev258ec2b2014-05-14 16:15:37 -070043class Transport;
44
45class PendingInterestId;
46class RegisteredPrefixId;
47class InterestFilterId;
48
Alexander Afanasyevee8bb1e2014-05-02 17:39:54 -070049namespace nfd {
50class Controller;
51}
Alexander Afanasyevee8bb1e2014-05-02 17:39:54 -070052
Jeff Thompsonfe08e5a2013-08-13 11:15:59 -070053/**
Alexander Afanasyev984ad192014-05-02 19:11:15 -070054 * @brief Callback called when expressed Interest gets satisfied with Data packet
Alexander Afanasyev0222fba2014-02-09 23:16:02 -080055 */
56typedef function<void(const Interest&, Data&)> OnData;
57
58/**
Alexander Afanasyev984ad192014-05-02 19:11:15 -070059 * @brief Callback called when expressed Interest times out
Alexander Afanasyev0222fba2014-02-09 23:16:02 -080060 */
61typedef function<void(const Interest&)> OnTimeout;
62
63/**
Alexander Afanasyev984ad192014-05-02 19:11:15 -070064 * @brief Callback called when incoming Interest matches the specified InterestFilter
Alexander Afanasyev0222fba2014-02-09 23:16:02 -080065 */
Alexander Afanasyev90164962014-03-06 08:29:59 +000066typedef function<void (const InterestFilter&, const Interest&)> OnInterest;
Alexander Afanasyev0222fba2014-02-09 23:16:02 -080067
68/**
Alexander Afanasyev984ad192014-05-02 19:11:15 -070069 * @brief Callback called when registerPrefix or setInterestFilter command succeeds
Alexander Afanasyev0222fba2014-02-09 23:16:02 -080070 */
Alexander Afanasyev984ad192014-05-02 19:11:15 -070071typedef function<void(const Name&)> RegisterPrefixSuccessCallback;
Alexander Afanasyev0222fba2014-02-09 23:16:02 -080072
Alexander Afanasyev984ad192014-05-02 19:11:15 -070073/**
74 * @brief Callback called when registerPrefix or setInterestFilter command fails
75 */
76typedef function<void(const Name&, const std::string&)> RegisterPrefixFailureCallback;
77
78/**
79 * @brief Callback called when unregisterPrefix or unsetInterestFilter command succeeds
80 */
81typedef function<void()> UnregisterPrefixSuccessCallback;
82
83/**
84 * @brief Callback called when unregisterPrefix or unsetInterestFilter command fails
85 */
86typedef function<void(const std::string&)> UnregisterPrefixFailureCallback;
Alexander Afanasyev0222fba2014-02-09 23:16:02 -080087
88
89/**
90 * @brief Abstraction to communicate with local or remote NDN forwarder
Jeff Thompsonfe08e5a2013-08-13 11:15:59 -070091 */
Alexander Afanasyev8460afb2014-02-15 20:31:42 -080092class Face : noncopyable
93{
Jeff Thompsonaa4e6db2013-07-15 17:25:23 -070094public:
Alexander Afanasyevfdbfc6d2014-04-14 15:12:11 -070095 class Error : public std::runtime_error
96 {
97 public:
98 explicit
99 Error(const std::string& what)
100 : std::runtime_error(what)
101 {
102 }
103 };
Alexander Afanasyevb790d952014-01-24 12:07:53 -0800104
105 /**
Alexander Afanasyev691c3ce2014-04-23 14:28:04 -0700106 * @brief Create a new Face using the default transport (UnixTransport)
107 *
Steve DiBenedettoc07b3a22014-03-19 12:32:52 -0600108 * @throws ConfigFile::Error on configuration file parse failure
109 * @throws Face::Error on unsupported protocol
Alexander Afanasyevb790d952014-01-24 12:07:53 -0800110 */
Alexander Afanasyevf7ca3202014-02-14 22:28:31 -0800111 Face();
Alexander Afanasyeve2e0d752014-01-03 13:30:30 -0800112
113 /**
Alexander Afanasyev691c3ce2014-04-23 14:28:04 -0700114 * @brief Create a new Face using the default transport (UnixTransport)
115 *
116 * @deprecated This constructor is deprecated. Use `Face(boost::asio::io_service&)`
117 * instead.
118 *
119 * @param ioService A shared pointer to boost::io_service object that should control all
120 * IO operations
Steve DiBenedettoc07b3a22014-03-19 12:32:52 -0600121 * @throws ConfigFile::Error on configuration file parse failure
122 * @throws Face::Error on unsupported protocol
Jeff Thompsonfe08e5a2013-08-13 11:15:59 -0700123 */
Alexander Afanasyev9c578182014-05-14 17:28:28 -0700124 DEPRECATED(
Alexander Afanasyevf7ca3202014-02-14 22:28:31 -0800125 explicit
Alexander Afanasyev9c578182014-05-14 17:28:28 -0700126 Face(const shared_ptr<boost::asio::io_service>& ioService));
Alexander Afanasyev7682ccb2014-02-20 10:29:35 -0800127
Jeff Thompsonfe08e5a2013-08-13 11:15:59 -0700128 /**
Alexander Afanasyev691c3ce2014-04-23 14:28:04 -0700129 * @brief Create a new Face using the default transport (UnixTransport)
130 *
131 * @par Usage examples:
132 *
133 * Face face1;
134 * Face face2(face1.getIoService());
135 *
136 * // Now the following ensures that events on both faces are processed
137 * face1.processEvents();
138 * // or face1.getIoService().run();
139 *
140 * @par or
141 *
142 * boost::asio::io_service ioService;
143 * Face face1(ioService);
144 * Face face2(ioService);
145 * ...
146 *
147 * ioService.run();
148 *
149 * @param ioService A reference to boost::io_service object that should control all
150 * IO operations.
151 * @throws ConfigFile::Error on configuration file parse failure
152 * @throws Face::Error on unsupported protocol
153 */
154 explicit
155 Face(boost::asio::io_service& ioService);
156
157 /**
158 * @brief Create a new Face using TcpTransport
159 *
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700160 * @param host The host of the NDN forwarder
161 * @param port (optional) The port or service name of the NDN forwarder (**default**: "6363")
162 *
Steve DiBenedettoc07b3a22014-03-19 12:32:52 -0600163 * @throws Face::Error on unsupported protocol
Jeff Thompsonfe08e5a2013-08-13 11:15:59 -0700164 */
Alexander Afanasyev7682ccb2014-02-20 10:29:35 -0800165 Face(const std::string& host, const std::string& port = "6363");
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800166
167 /**
Alexander Afanasyev691c3ce2014-04-23 14:28:04 -0700168 * @brief Create a new Face using the given Transport
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700169 *
170 * @param transport A shared_ptr to a Transport object used for communication
171 *
Steve DiBenedettoc07b3a22014-03-19 12:32:52 -0600172 * @throws Face::Error on unsupported protocol
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800173 */
Alexander Afanasyevf7ca3202014-02-14 22:28:31 -0800174 explicit
175 Face(const shared_ptr<Transport>& transport);
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800176
177 /**
Alexander Afanasyev691c3ce2014-04-23 14:28:04 -0700178 * @brief Create a new Face using the given Transport and IO service object
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800179 *
Alexander Afanasyev691c3ce2014-04-23 14:28:04 -0700180 * @sa Face(boost::asio::io_service&)
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800181 *
Steve DiBenedettoc07b3a22014-03-19 12:32:52 -0600182 * @throws Face::Error on unsupported protocol
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800183 */
184 Face(const shared_ptr<Transport>& transport,
Alexander Afanasyev691c3ce2014-04-23 14:28:04 -0700185 boost::asio::io_service& ioService);
Alexander Afanasyev7682ccb2014-02-20 10:29:35 -0800186
Jeff Thompson4fe45512013-08-23 14:06:38 -0700187 /**
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800188 * @brief Express Interest
189 *
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700190 * @param interest An Interest to be expressed
191 * @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 The pending interest ID which can be used with removePendingInterest
Jeff Thompson4fe45512013-08-23 14:06:38 -0700195 */
Alexander Afanasyevb790d952014-01-24 12:07:53 -0800196 const PendingInterestId*
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800197 expressInterest(const Interest& interest,
198 const OnData& onData, const OnTimeout& onTimeout = OnTimeout());
Jeff Thompson4fe45512013-08-23 14:06:38 -0700199
200 /**
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800201 * @brief Express Interest using name and Interest template
202 *
203 * @param name Name of the Interest
204 * @param tmpl Interest template to fill parameters
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700205 * @param onData Callback to be called when a matching data packet is received
206 * @param onTimeout (optional) A function object to call if the interest times out
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800207 *
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700208 * @return Opaque pending interest ID which can be used with removePendingInterest
Jeff Thompson7aec0252013-08-22 17:29:57 -0700209 */
Alexander Afanasyevb790d952014-01-24 12:07:53 -0800210 const PendingInterestId*
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800211 expressInterest(const Name& name,
Alexander Afanasyev7682ccb2014-02-20 10:29:35 -0800212 const Interest& tmpl,
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800213 const OnData& onData, const OnTimeout& onTimeout = OnTimeout());
Alexander Afanasyevfdbfc6d2014-04-14 15:12:11 -0700214
Jeff Thompson11095142013-10-01 16:20:28 -0700215 /**
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700216 * @brief Cancel previously expressed Interest
Alexander Afanasyev691c3ce2014-04-23 14:28:04 -0700217 *
Jeff Thompson11095142013-10-01 16:20:28 -0700218 * @param pendingInterestId The ID returned from expressInterest.
219 */
220 void
Alexander Afanasyev7682ccb2014-02-20 10:29:35 -0800221 removePendingInterest(const PendingInterestId* pendingInterestId);
Alexander Afanasyevfdbfc6d2014-04-14 15:12:11 -0700222
Jeff Thompson432c8be2013-08-09 16:16:08 -0700223 /**
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700224 * @brief Set InterestFilter to dispatch incoming matching interest to onInterest
225 * callback and register the filtered prefix with the connected NDN forwarder
226 *
227 * This version of setInterestFilter combines setInterestFilter and registerPrefix
228 * operations and is intended to be used when only one filter for the same prefix needed
229 * to be set. When multiple names sharing the same prefix should be dispatched to
230 * different callbacks, use one registerPrefix call, followed (in onSuccess callback) by
231 * a series of setInterestFilter calls.
Alexander Afanasyev691c3ce2014-04-23 14:28:04 -0700232 *
Alexander Afanasyev90164962014-03-06 08:29:59 +0000233 * @param interestFilter Interest filter (prefix part will be registered with the forwarder)
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700234 * @param onInterest A callback to be called when a matching interest is received
235 * @param onSuccess A callback to be called when prefixRegister command succeeds
236 * @param onFailure A callback to be called when prefixRegister command fails
237 * @param certificate (optional) A certificate under which the prefix registration
238 * command interest is signed. When omitted, a default certificate
239 * of the default identity is used to sign the registration command
Alexander Afanasyev691c3ce2014-04-23 14:28:04 -0700240 *
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700241 * @return Opaque registered prefix ID which can be used with unsetInterestFilter or
242 * removeRegisteredPrefix
Jeff Thompson86507bc2013-08-23 20:51:38 -0700243 */
Alexander Afanasyevb790d952014-01-24 12:07:53 -0800244 const RegisteredPrefixId*
Alexander Afanasyev90164962014-03-06 08:29:59 +0000245 setInterestFilter(const InterestFilter& interestFilter,
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800246 const OnInterest& onInterest,
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700247 const RegisterPrefixSuccessCallback& onSuccess,
248 const RegisterPrefixFailureCallback& onFailure,
249 const IdentityCertificate& certificate = IdentityCertificate());
Jeff Thompson11095142013-10-01 16:20:28 -0700250
251 /**
Alexander Afanasyev1b01c312014-05-26 16:58:10 +0300252 * @brief Set InterestFilter to dispatch incoming matching interest to onInterest
253 * callback and register the filtered prefix with the connected NDN forwarder
254 *
255 * This version of setInterestFilter combines setInterestFilter and registerPrefix
256 * operations and is intended to be used when only one filter for the same prefix needed
257 * to be set. When multiple names sharing the same prefix should be dispatched to
258 * different callbacks, use one registerPrefix call, followed (in onSuccess callback) by
259 * a series of setInterestFilter calls.
260 *
261 * @param interestFilter Interest filter (prefix part will be registered with the forwarder)
262 * @param onInterest A callback to be called when a matching interest is received
263 * @param onFailure A callback to be called when prefixRegister command fails
264 * @param certificate (optional) A certificate under which the prefix registration
265 * command interest is signed. When omitted, a default certificate
266 * of the default identity is used to sign the registration command
267 *
268 * @return Opaque registered prefix ID which can be used with unsetInterestFilter or
269 * removeRegisteredPrefix
Yingdi Yue66bf2a2014-04-28 17:07:36 -0700270 */
271 const RegisteredPrefixId*
Alexander Afanasyev90164962014-03-06 08:29:59 +0000272 setInterestFilter(const InterestFilter& interestFilter,
Yingdi Yue66bf2a2014-04-28 17:07:36 -0700273 const OnInterest& onInterest,
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700274 const RegisterPrefixFailureCallback& onFailure,
Alexander Afanasyev1b01c312014-05-26 16:58:10 +0300275 const IdentityCertificate& certificate = IdentityCertificate());
Yingdi Yue66bf2a2014-04-28 17:07:36 -0700276
277 /**
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700278 * @brief Set InterestFilter to dispatch incoming matching interest to onInterest
279 * callback and register the filtered prefix with the connected NDN forwarder
280 *
281 * This version of setInterestFilter combines setInterestFilter and registerPrefix
282 * operations and is intended to be used when only one filter for the same prefix needed
283 * to be set. When multiple names sharing the same prefix should be dispatched to
284 * different callbacks, use one registerPrefix call, followed (in onSuccess callback) by
285 * a series of setInterestFilter calls.
Yingdi Yue66bf2a2014-04-28 17:07:36 -0700286 *
Alexander Afanasyev90164962014-03-06 08:29:59 +0000287 * @param interestFilter Interest filter (prefix part will be registered with the forwarder)
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700288 * @param onInterest A callback to be called when a matching interest is received
289 * @param onSuccess A callback to be called when prefixRegister command succeeds
290 * @param onFailure A callback to be called when prefixRegister command fails
291 * @param identity A signing identity. A command interest is signed under the default
292 * certificate of this identity
Yingdi Yue66bf2a2014-04-28 17:07:36 -0700293 *
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700294 * @return Opaque registered prefix ID which can be used with removeRegisteredPrefix
Yingdi Yue66bf2a2014-04-28 17:07:36 -0700295 */
296 const RegisteredPrefixId*
Alexander Afanasyev90164962014-03-06 08:29:59 +0000297 setInterestFilter(const InterestFilter& interestFilter,
Yingdi Yue66bf2a2014-04-28 17:07:36 -0700298 const OnInterest& onInterest,
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700299 const RegisterPrefixSuccessCallback& onSuccess,
300 const RegisterPrefixFailureCallback& onFailure,
Yingdi Yue66bf2a2014-04-28 17:07:36 -0700301 const Name& identity);
302
303 /**
Alexander Afanasyev1b01c312014-05-26 16:58:10 +0300304 * @brief Set InterestFilter to dispatch incoming matching interest to onInterest
305 * callback and register the filtered prefix with the connected NDN forwarder
306 *
307 * This version of setInterestFilter combines setInterestFilter and registerPrefix
308 * operations and is intended to be used when only one filter for the same prefix needed
309 * to be set. When multiple names sharing the same prefix should be dispatched to
310 * different callbacks, use one registerPrefix call, followed (in onSuccess callback) by
311 * a series of setInterestFilter calls.
312 *
313 * @param interestFilter Interest filter (prefix part will be registered with the forwarder)
314 * @param onInterest A callback to be called when a matching interest is received
315 * @param onFailure A callback to be called when prefixRegister command fails
316 * @param identity A signing identity. A command interest is signed under the default
317 * certificate of this identity
318 *
319 * @return Opaque registered prefix ID which can be used with removeRegisteredPrefix
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700320 */
321 const RegisteredPrefixId*
322 setInterestFilter(const InterestFilter& interestFilter,
323 const OnInterest& onInterest,
324 const RegisterPrefixFailureCallback& onFailure,
Alexander Afanasyev1b01c312014-05-26 16:58:10 +0300325 const Name& identity);
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700326
327 /**
328 * @brief Set InterestFilter to dispatch incoming matching interest to onInterest callback
329 *
330 * @param interestFilter Interest
331 * @param onInterest A callback to be called when a matching interest is received
332 *
333 * This method modifies library's FIB only, and does not register the prefix with the
334 * forwarder. It will always succeed. To register prefix with the forwarder, use
335 * registerPrefix, or use the setInterestFilter overload taking two callbacks.
336 *
337 * @return Opaque interest filter ID which can be used with unsetInterestFilter
338 */
339 const InterestFilterId*
340 setInterestFilter(const InterestFilter& interestFilter,
341 const OnInterest& onInterest);
342
343
344 /**
345 * @brief Register prefix with the connected NDN forwarder
346 *
347 * This method only modifies forwarder's RIB (or FIB) and does not associate any
348 * onInterest callbacks. Use setInterestFilter method to dispatch incoming Interests to
349 * the right callbacks.
350 *
351 * @param prefix A prefix to register with the connected NDN forwarder
352 * @param onSuccess A callback to be called when prefixRegister command succeeds
353 * @param onFailure A callback to be called when prefixRegister command fails
354 * @param certificate (optional) A certificate under which the prefix registration
355 * command interest is signed. When omitted, a default certificate
356 * of the default identity is used to sign the registration command
357 *
358 * @return The registered prefix ID which can be used with unregisterPrefix
359 */
360 const RegisteredPrefixId*
361 registerPrefix(const Name& prefix,
362 const RegisterPrefixSuccessCallback& onSuccess,
363 const RegisterPrefixFailureCallback& onFailure,
364 const IdentityCertificate& certificate = IdentityCertificate());
365
366 /**
367 * @brief Register prefix with the connected NDN forwarder and call onInterest when a matching
368 * interest is received.
369 *
370 * This method only modifies forwarder's RIB (or FIB) and does not associate any
371 * onInterest callbacks. Use setInterestFilter method to dispatch incoming Interests to
372 * the right callbacks.
373 *
374 * @param prefix A prefix to register with the connected NDN forwarder
375 * @param onSuccess A callback to be called when prefixRegister command succeeds
376 * @param onFailure A callback to be called when prefixRegister command fails
377 * @param identity A signing identity. A command interest is signed under the default
378 * certificate of this identity
379 *
380 * @return The registered prefix ID which can be used with unregisterPrefix
381 */
382 const RegisteredPrefixId*
383 registerPrefix(const Name& prefix,
384 const RegisterPrefixSuccessCallback& onSuccess,
385 const RegisterPrefixFailureCallback& onFailure,
386 const Name& identity);
387
388
389 /**
Alexander Afanasyev1b01c312014-05-26 16:58:10 +0300390 * @brief Remove the registered prefix entry with the registeredPrefixId
Alexander Afanasyev691c3ce2014-04-23 14:28:04 -0700391 *
392 * This does not affect another registered prefix with a different registeredPrefixId,
393 * even it if has the same prefix name. If there is no entry with the
394 * registeredPrefixId, do nothing.
395 *
Alexander Afanasyevee8bb1e2014-05-02 17:39:54 -0700396 * unsetInterestFilter will use the same credentials as original
397 * setInterestFilter/registerPrefix command
398 *
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700399 * @param registeredPrefixId The ID returned from registerPrefix
Jeff Thompson11095142013-10-01 16:20:28 -0700400 */
401 void
Alexander Afanasyev7682ccb2014-02-20 10:29:35 -0800402 unsetInterestFilter(const RegisteredPrefixId* registeredPrefixId);
Alexander Afanasyeva557d5a2013-12-28 21:59:03 -0800403
Alexander Afanasyevee8bb1e2014-05-02 17:39:54 -0700404 /**
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700405 * @brief Remove previously set InterestFilter from library's FIB
406 *
407 * This method always succeeds and will **NOT** send any request to the connected
408 * forwarder.
409 *
410 * @param interestFilterId The ID returned from setInterestFilter.
411 */
412 void
413 unsetInterestFilter(const InterestFilterId* interestFilterId);
414
415 /**
416 * @brief Deregister prefix from RIB (or FIB)
417 *
418 * unregisterPrefix will use the same credentials as original
419 * setInterestFilter/registerPrefix command
420 *
421 * If registeredPrefixId was obtained using setInterestFilter, the corresponding
422 * InterestFilter will be unset too.
423 *
Alexander Afanasyev770827c2014-05-13 17:42:55 -0700424 * @param registeredPrefixId The ID returned from registerPrefix
425 * @param onSuccess Callback to be called when operation succeeds
426 * @param onFailure Callback to be called when operation fails
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700427 */
428 void
429 unregisterPrefix(const RegisteredPrefixId* registeredPrefixId,
430 const UnregisterPrefixSuccessCallback& onSuccess,
431 const UnregisterPrefixFailureCallback& onFailure);
432
433 /**
Alexander Afanasyevee8bb1e2014-05-02 17:39:54 -0700434 * @brief (FOR DEBUG PURPOSES ONLY) Request direct NFD FIB management
435 */
Yingdi Yue66bf2a2014-04-28 17:07:36 -0700436 void
Alexander Afanasyevee8bb1e2014-05-02 17:39:54 -0700437 setDirectFibManagement(bool isDirectFibManagementRequested = false);
Yingdi Yue66bf2a2014-04-28 17:07:36 -0700438
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800439 /**
Alexander Afanasyeva557d5a2013-12-28 21:59:03 -0800440 * @brief Publish data packet
441 *
Alexander Afanasyev691c3ce2014-04-23 14:28:04 -0700442 * This method can be called to satisfy the incoming Interest or to put Data packet into
Alexander Afanasyev6a05b4b2014-07-18 17:23:00 -0700443 * the cache of the local NDN forwarder.
444 *
445 * @param data Data packet to publish. It is highly recommended to use Data packet that
446 * was created using make_shared<Data>(...). Otherwise, put() will make an
447 * extra copy of the Data packet to ensure validity of published Data until
448 * asynchronous put() operation finishes.
Alexander Afanasyeva557d5a2013-12-28 21:59:03 -0800449 */
450 void
Alexander Afanasyev7682ccb2014-02-20 10:29:35 -0800451 put(const Data& data);
Alexander Afanasyevfdbfc6d2014-04-14 15:12:11 -0700452
Jeff Thompson86507bc2013-08-23 20:51:38 -0700453 /**
Alexander Afanasyev691c3ce2014-04-23 14:28:04 -0700454 * @brief Process any data to receive or call timeout callbacks.
Alexander Afanasyeva557d5a2013-12-28 21:59:03 -0800455 *
456 * This call will block forever (default timeout == 0) to process IO on the face.
457 * To exit, one expected to call face.shutdown() from one of the callback methods.
458 *
Alexander Afanasyev691c3ce2014-04-23 14:28:04 -0700459 * If positive timeout is specified, then processEvents will exit after this timeout, if
460 * not stopped earlier with face.shutdown() or when all active events finish. The call
461 * can be called repeatedly, if desired.
Alexander Afanasyeva557d5a2013-12-28 21:59:03 -0800462 *
Alexander Afanasyev691c3ce2014-04-23 14:28:04 -0700463 * If negative timeout is specified, then processEvents will not block and process only
464 * pending events.
Alexander Afanasyevf75a0aa2014-01-09 14:29:22 -0800465 *
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700466 * @param timeout maximum time to block the thread
Alexander Afanasyev691c3ce2014-04-23 14:28:04 -0700467 * @param keepThread Keep thread in a blocked state (in event processing), even when
468 * there are no outstanding events (e.g., no Interest/Data is expected)
469 *
470 * @throw This may throw an exception for reading data or in the callback for processing
471 * the data. If you call this from an main event loop, you may want to catch and
472 * log/disregard all exceptions.
Jeff Thompson432c8be2013-08-09 16:16:08 -0700473 */
Alexander Afanasyevfdbfc6d2014-04-14 15:12:11 -0700474 void
Alexander Afanasyevaa0e7da2014-03-17 14:37:33 -0700475 processEvents(const time::milliseconds& timeout = time::milliseconds::zero(),
476 bool keepThread = false);
Jeff Thompson432c8be2013-08-09 16:16:08 -0700477
Alexander Afanasyev691c3ce2014-04-23 14:28:04 -0700478 /**
479 * @brief Shutdown face operations
480 *
481 * This method cancels all pending operations and closes connection to NDN Forwarder.
482 *
483 * Note that this method does not stop IO service and if the same IO service is shared
484 * between multiple Faces or with other IO objects (e.g., Scheduler).
485 */
Alexander Afanasyevfdbfc6d2014-04-14 15:12:11 -0700486 void
Jeff Thompson0050abe2013-09-17 12:50:25 -0700487 shutdown();
Yingdi Yu0d920812014-01-30 14:50:57 -0800488
Alexander Afanasyev691c3ce2014-04-23 14:28:04 -0700489 /**
490 * @brief Get shared_ptr of the IO service object
491 *
492 * @deprecated Use getIoService instead
493 */
Alexander Afanasyev9c578182014-05-14 17:28:28 -0700494 DEPRECATED(
Alexander Afanasyevfdbfc6d2014-04-14 15:12:11 -0700495 shared_ptr<boost::asio::io_service>
Alexander Afanasyev9c578182014-05-14 17:28:28 -0700496 ioService())
Alexander Afanasyev691c3ce2014-04-23 14:28:04 -0700497 {
498 return m_ioService;
499 }
500
501 /**
502 * @brief Get reference to IO service object
503 */
504 boost::asio::io_service&
505 getIoService()
506 {
507 return *m_ioService;
508 }
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800509
510private:
Steve DiBenedettoc07b3a22014-03-19 12:32:52 -0600511 /**
512 * @throws Face::Error on unsupported protocol
513 */
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800514 void
Alexander Afanasyev7682ccb2014-02-20 10:29:35 -0800515 construct(const shared_ptr<Transport>& transport,
Alexander Afanasyev505646e2014-02-24 20:13:37 -0800516 const shared_ptr<boost::asio::io_service>& ioService);
Steve DiBenedettoc07b3a22014-03-19 12:32:52 -0600517
518 bool
519 isSupportedNfdProtocol(const std::string& protocol);
520
521 bool
522 isSupportedNrdProtocol(const std::string& protocol);
523
Alexander Afanasyev691c3ce2014-04-23 14:28:04 -0700524 class ProcessEventsTimeout
525 {
526 };
527
Alexander Afanasyevfdbfc6d2014-04-14 15:12:11 -0700528 void
Alexander Afanasyev6d48bc12014-02-18 00:10:51 -0800529 onReceiveElement(const Block& wire);
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800530
Alexander Afanasyev7dced462014-03-19 15:12:32 -0700531 void
532 asyncShutdown();
Alexander Afanasyevfdbfc6d2014-04-14 15:12:11 -0700533
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800534 static void
535 fireProcessEventsTimeout(const boost::system::error_code& error);
536
Jeff Thompsonb982b6d2013-07-15 18:15:45 -0700537private:
Alexander Afanasyevf39c5372014-02-17 19:42:56 -0800538 shared_ptr<boost::asio::io_service> m_ioService;
Alexander Afanasyevfdbfc6d2014-04-14 15:12:11 -0700539
Alexander Afanasyevf39c5372014-02-17 19:42:56 -0800540 shared_ptr<Transport> m_transport;
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800541
Alexander Afanasyev258ec2b2014-05-14 16:15:37 -0700542 shared_ptr<nfd::Controller> m_nfdController;
Alexander Afanasyevee8bb1e2014-05-02 17:39:54 -0700543 bool m_isDirectNfdFibManagementRequested;
Steve DiBenedettoc07b3a22014-03-19 12:32:52 -0600544
Alexander Afanasyev258ec2b2014-05-14 16:15:37 -0700545 class Impl;
546 shared_ptr<Impl> m_impl;
Jeff Thompsonaa4e6db2013-07-15 17:25:23 -0700547};
548
Steve DiBenedettoc07b3a22014-03-19 12:32:52 -0600549inline bool
550Face::isSupportedNfdProtocol(const std::string& protocol)
551{
552 return protocol == "nfd-0.1";
553}
554
555inline bool
556Face::isSupportedNrdProtocol(const std::string& protocol)
557{
558 return protocol == "nrd-0.1";
559}
560
Alexander Afanasyevee8bb1e2014-05-02 17:39:54 -0700561inline void
562Face::setDirectFibManagement(bool isDirectFibManagementRequested/* = false*/)
Steve DiBenedettoc07b3a22014-03-19 12:32:52 -0600563{
Alexander Afanasyevee8bb1e2014-05-02 17:39:54 -0700564 m_isDirectNfdFibManagementRequested = isDirectFibManagementRequested;
Steve DiBenedettoc07b3a22014-03-19 12:32:52 -0600565}
566
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800567} // namespace ndn
Jeff Thompsonaa4e6db2013-07-15 17:25:23 -0700568
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800569#endif // NDN_FACE_HPP