blob: 9427b0334efea5bdab8ec5bd48173e747bfd8ba2 [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
Alexander Afanasyev49bb1fb2014-07-21 12:54:01 -0700195 *
196 * @throws Error when Interest size exceeds maximum limit (MAX_NDN_PACKET_SIZE)
Jeff Thompson4fe45512013-08-23 14:06:38 -0700197 */
Alexander Afanasyevb790d952014-01-24 12:07:53 -0800198 const PendingInterestId*
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800199 expressInterest(const Interest& interest,
200 const OnData& onData, const OnTimeout& onTimeout = OnTimeout());
Jeff Thompson4fe45512013-08-23 14:06:38 -0700201
202 /**
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800203 * @brief Express Interest using name and Interest template
204 *
205 * @param name Name of the Interest
206 * @param tmpl Interest template to fill parameters
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700207 * @param onData Callback to be called when a matching data packet is received
208 * @param onTimeout (optional) A function object to call if the interest times out
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800209 *
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700210 * @return Opaque pending interest ID which can be used with removePendingInterest
Alexander Afanasyev49bb1fb2014-07-21 12:54:01 -0700211 *
212 * @throws Error when Interest size exceeds maximum limit (MAX_NDN_PACKET_SIZE)
Jeff Thompson7aec0252013-08-22 17:29:57 -0700213 */
Alexander Afanasyevb790d952014-01-24 12:07:53 -0800214 const PendingInterestId*
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800215 expressInterest(const Name& name,
Alexander Afanasyev7682ccb2014-02-20 10:29:35 -0800216 const Interest& tmpl,
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800217 const OnData& onData, const OnTimeout& onTimeout = OnTimeout());
Alexander Afanasyevfdbfc6d2014-04-14 15:12:11 -0700218
Jeff Thompson11095142013-10-01 16:20:28 -0700219 /**
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700220 * @brief Cancel previously expressed Interest
Alexander Afanasyev691c3ce2014-04-23 14:28:04 -0700221 *
Jeff Thompson11095142013-10-01 16:20:28 -0700222 * @param pendingInterestId The ID returned from expressInterest.
223 */
224 void
Alexander Afanasyev7682ccb2014-02-20 10:29:35 -0800225 removePendingInterest(const PendingInterestId* pendingInterestId);
Alexander Afanasyevfdbfc6d2014-04-14 15:12:11 -0700226
Jeff Thompson432c8be2013-08-09 16:16:08 -0700227 /**
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700228 * @brief Set InterestFilter to dispatch incoming matching interest to onInterest
229 * callback and register the filtered prefix with the connected NDN forwarder
230 *
231 * This version of setInterestFilter combines setInterestFilter and registerPrefix
232 * operations and is intended to be used when only one filter for the same prefix needed
233 * to be set. When multiple names sharing the same prefix should be dispatched to
234 * different callbacks, use one registerPrefix call, followed (in onSuccess callback) by
235 * a series of setInterestFilter calls.
Alexander Afanasyev691c3ce2014-04-23 14:28:04 -0700236 *
Alexander Afanasyev90164962014-03-06 08:29:59 +0000237 * @param interestFilter Interest filter (prefix part will be registered with the forwarder)
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700238 * @param onInterest A callback to be called when a matching interest is received
239 * @param onSuccess A callback to be called when prefixRegister command succeeds
240 * @param onFailure A callback to be called when prefixRegister command fails
241 * @param certificate (optional) A certificate under which the prefix registration
242 * command interest is signed. When omitted, a default certificate
243 * of the default identity is used to sign the registration command
Alexander Afanasyev691c3ce2014-04-23 14:28:04 -0700244 *
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700245 * @return Opaque registered prefix ID which can be used with unsetInterestFilter or
246 * removeRegisteredPrefix
Jeff Thompson86507bc2013-08-23 20:51:38 -0700247 */
Alexander Afanasyevb790d952014-01-24 12:07:53 -0800248 const RegisteredPrefixId*
Alexander Afanasyev90164962014-03-06 08:29:59 +0000249 setInterestFilter(const InterestFilter& interestFilter,
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800250 const OnInterest& onInterest,
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700251 const RegisterPrefixSuccessCallback& onSuccess,
252 const RegisterPrefixFailureCallback& onFailure,
253 const IdentityCertificate& certificate = IdentityCertificate());
Jeff Thompson11095142013-10-01 16:20:28 -0700254
255 /**
Alexander Afanasyev1b01c312014-05-26 16:58:10 +0300256 * @brief Set InterestFilter to dispatch incoming matching interest to onInterest
257 * callback and register the filtered prefix with the connected NDN forwarder
258 *
259 * This version of setInterestFilter combines setInterestFilter and registerPrefix
260 * operations and is intended to be used when only one filter for the same prefix needed
261 * to be set. When multiple names sharing the same prefix should be dispatched to
262 * different callbacks, use one registerPrefix call, followed (in onSuccess callback) by
263 * a series of setInterestFilter calls.
264 *
265 * @param interestFilter Interest filter (prefix part will be registered with the forwarder)
266 * @param onInterest A callback to be called when a matching interest is received
267 * @param onFailure A callback to be called when prefixRegister command fails
268 * @param certificate (optional) A certificate under which the prefix registration
269 * command interest is signed. When omitted, a default certificate
270 * of the default identity is used to sign the registration command
271 *
272 * @return Opaque registered prefix ID which can be used with unsetInterestFilter or
273 * removeRegisteredPrefix
Yingdi Yue66bf2a2014-04-28 17:07:36 -0700274 */
275 const RegisteredPrefixId*
Alexander Afanasyev90164962014-03-06 08:29:59 +0000276 setInterestFilter(const InterestFilter& interestFilter,
Yingdi Yue66bf2a2014-04-28 17:07:36 -0700277 const OnInterest& onInterest,
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700278 const RegisterPrefixFailureCallback& onFailure,
Alexander Afanasyev1b01c312014-05-26 16:58:10 +0300279 const IdentityCertificate& certificate = IdentityCertificate());
Yingdi Yue66bf2a2014-04-28 17:07:36 -0700280
281 /**
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700282 * @brief Set InterestFilter to dispatch incoming matching interest to onInterest
283 * callback and register the filtered prefix with the connected NDN forwarder
284 *
285 * This version of setInterestFilter combines setInterestFilter and registerPrefix
286 * operations and is intended to be used when only one filter for the same prefix needed
287 * to be set. When multiple names sharing the same prefix should be dispatched to
288 * different callbacks, use one registerPrefix call, followed (in onSuccess callback) by
289 * a series of setInterestFilter calls.
Yingdi Yue66bf2a2014-04-28 17:07:36 -0700290 *
Alexander Afanasyev90164962014-03-06 08:29:59 +0000291 * @param interestFilter Interest filter (prefix part will be registered with the forwarder)
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700292 * @param onInterest A callback to be called when a matching interest is received
293 * @param onSuccess A callback to be called when prefixRegister command succeeds
294 * @param onFailure A callback to be called when prefixRegister command fails
295 * @param identity A signing identity. A command interest is signed under the default
296 * certificate of this identity
Yingdi Yue66bf2a2014-04-28 17:07:36 -0700297 *
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700298 * @return Opaque registered prefix ID which can be used with removeRegisteredPrefix
Yingdi Yue66bf2a2014-04-28 17:07:36 -0700299 */
300 const RegisteredPrefixId*
Alexander Afanasyev90164962014-03-06 08:29:59 +0000301 setInterestFilter(const InterestFilter& interestFilter,
Yingdi Yue66bf2a2014-04-28 17:07:36 -0700302 const OnInterest& onInterest,
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700303 const RegisterPrefixSuccessCallback& onSuccess,
304 const RegisterPrefixFailureCallback& onFailure,
Yingdi Yue66bf2a2014-04-28 17:07:36 -0700305 const Name& identity);
306
307 /**
Alexander Afanasyev1b01c312014-05-26 16:58:10 +0300308 * @brief Set InterestFilter to dispatch incoming matching interest to onInterest
309 * callback and register the filtered prefix with the connected NDN forwarder
310 *
311 * This version of setInterestFilter combines setInterestFilter and registerPrefix
312 * operations and is intended to be used when only one filter for the same prefix needed
313 * to be set. When multiple names sharing the same prefix should be dispatched to
314 * different callbacks, use one registerPrefix call, followed (in onSuccess callback) by
315 * a series of setInterestFilter calls.
316 *
317 * @param interestFilter Interest filter (prefix part will be registered with the forwarder)
318 * @param onInterest A callback to be called when a matching interest is received
319 * @param onFailure A callback to be called when prefixRegister command fails
320 * @param identity A signing identity. A command interest is signed under the default
321 * certificate of this identity
322 *
323 * @return Opaque registered prefix ID which can be used with removeRegisteredPrefix
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700324 */
325 const RegisteredPrefixId*
326 setInterestFilter(const InterestFilter& interestFilter,
327 const OnInterest& onInterest,
328 const RegisterPrefixFailureCallback& onFailure,
Alexander Afanasyev1b01c312014-05-26 16:58:10 +0300329 const Name& identity);
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700330
331 /**
332 * @brief Set InterestFilter to dispatch incoming matching interest to onInterest callback
333 *
334 * @param interestFilter Interest
335 * @param onInterest A callback to be called when a matching interest is received
336 *
337 * This method modifies library's FIB only, and does not register the prefix with the
338 * forwarder. It will always succeed. To register prefix with the forwarder, use
339 * registerPrefix, or use the setInterestFilter overload taking two callbacks.
340 *
341 * @return Opaque interest filter ID which can be used with unsetInterestFilter
342 */
343 const InterestFilterId*
344 setInterestFilter(const InterestFilter& interestFilter,
345 const OnInterest& onInterest);
346
347
348 /**
349 * @brief Register prefix with the connected NDN forwarder
350 *
351 * This method only modifies forwarder's RIB (or FIB) and does not associate any
352 * onInterest callbacks. Use setInterestFilter method to dispatch incoming Interests to
353 * the right callbacks.
354 *
355 * @param prefix A prefix to register with the connected NDN forwarder
356 * @param onSuccess A callback to be called when prefixRegister command succeeds
357 * @param onFailure A callback to be called when prefixRegister command fails
358 * @param certificate (optional) A certificate under which the prefix registration
359 * command interest is signed. When omitted, a default certificate
360 * of the default identity is used to sign the registration command
361 *
362 * @return The registered prefix ID which can be used with unregisterPrefix
363 */
364 const RegisteredPrefixId*
365 registerPrefix(const Name& prefix,
366 const RegisterPrefixSuccessCallback& onSuccess,
367 const RegisterPrefixFailureCallback& onFailure,
368 const IdentityCertificate& certificate = IdentityCertificate());
369
370 /**
371 * @brief Register prefix with the connected NDN forwarder and call onInterest when a matching
372 * interest is received.
373 *
374 * This method only modifies forwarder's RIB (or FIB) and does not associate any
375 * onInterest callbacks. Use setInterestFilter method to dispatch incoming Interests to
376 * the right callbacks.
377 *
378 * @param prefix A prefix to register with the connected NDN forwarder
379 * @param onSuccess A callback to be called when prefixRegister command succeeds
380 * @param onFailure A callback to be called when prefixRegister command fails
381 * @param identity A signing identity. A command interest is signed under the default
382 * certificate of this identity
383 *
384 * @return The registered prefix ID which can be used with unregisterPrefix
385 */
386 const RegisteredPrefixId*
387 registerPrefix(const Name& prefix,
388 const RegisterPrefixSuccessCallback& onSuccess,
389 const RegisterPrefixFailureCallback& onFailure,
390 const Name& identity);
391
392
393 /**
Alexander Afanasyev1b01c312014-05-26 16:58:10 +0300394 * @brief Remove the registered prefix entry with the registeredPrefixId
Alexander Afanasyev691c3ce2014-04-23 14:28:04 -0700395 *
396 * This does not affect another registered prefix with a different registeredPrefixId,
397 * even it if has the same prefix name. If there is no entry with the
398 * registeredPrefixId, do nothing.
399 *
Alexander Afanasyevee8bb1e2014-05-02 17:39:54 -0700400 * unsetInterestFilter will use the same credentials as original
401 * setInterestFilter/registerPrefix command
402 *
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700403 * @param registeredPrefixId The ID returned from registerPrefix
Jeff Thompson11095142013-10-01 16:20:28 -0700404 */
405 void
Alexander Afanasyev7682ccb2014-02-20 10:29:35 -0800406 unsetInterestFilter(const RegisteredPrefixId* registeredPrefixId);
Alexander Afanasyeva557d5a2013-12-28 21:59:03 -0800407
Alexander Afanasyevee8bb1e2014-05-02 17:39:54 -0700408 /**
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700409 * @brief Remove previously set InterestFilter from library's FIB
410 *
411 * This method always succeeds and will **NOT** send any request to the connected
412 * forwarder.
413 *
414 * @param interestFilterId The ID returned from setInterestFilter.
415 */
416 void
417 unsetInterestFilter(const InterestFilterId* interestFilterId);
418
419 /**
420 * @brief Deregister prefix from RIB (or FIB)
421 *
422 * unregisterPrefix will use the same credentials as original
423 * setInterestFilter/registerPrefix command
424 *
425 * If registeredPrefixId was obtained using setInterestFilter, the corresponding
426 * InterestFilter will be unset too.
427 *
Alexander Afanasyev770827c2014-05-13 17:42:55 -0700428 * @param registeredPrefixId The ID returned from registerPrefix
429 * @param onSuccess Callback to be called when operation succeeds
430 * @param onFailure Callback to be called when operation fails
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700431 */
432 void
433 unregisterPrefix(const RegisteredPrefixId* registeredPrefixId,
434 const UnregisterPrefixSuccessCallback& onSuccess,
435 const UnregisterPrefixFailureCallback& onFailure);
436
437 /**
Alexander Afanasyevee8bb1e2014-05-02 17:39:54 -0700438 * @brief (FOR DEBUG PURPOSES ONLY) Request direct NFD FIB management
439 */
Yingdi Yue66bf2a2014-04-28 17:07:36 -0700440 void
Alexander Afanasyevee8bb1e2014-05-02 17:39:54 -0700441 setDirectFibManagement(bool isDirectFibManagementRequested = false);
Yingdi Yue66bf2a2014-04-28 17:07:36 -0700442
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800443 /**
Alexander Afanasyeva557d5a2013-12-28 21:59:03 -0800444 * @brief Publish data packet
445 *
Alexander Afanasyev691c3ce2014-04-23 14:28:04 -0700446 * This method can be called to satisfy the incoming Interest or to put Data packet into
Alexander Afanasyev6a05b4b2014-07-18 17:23:00 -0700447 * the cache of the local NDN forwarder.
448 *
449 * @param data Data packet to publish. It is highly recommended to use Data packet that
450 * was created using make_shared<Data>(...). Otherwise, put() will make an
451 * extra copy of the Data packet to ensure validity of published Data until
452 * asynchronous put() operation finishes.
Alexander Afanasyev49bb1fb2014-07-21 12:54:01 -0700453 *
454 * @throws Error when Data size exceeds maximum limit (MAX_NDN_PACKET_SIZE)
Alexander Afanasyeva557d5a2013-12-28 21:59:03 -0800455 */
456 void
Alexander Afanasyev7682ccb2014-02-20 10:29:35 -0800457 put(const Data& data);
Alexander Afanasyevfdbfc6d2014-04-14 15:12:11 -0700458
Jeff Thompson86507bc2013-08-23 20:51:38 -0700459 /**
Alexander Afanasyev691c3ce2014-04-23 14:28:04 -0700460 * @brief Process any data to receive or call timeout callbacks.
Alexander Afanasyeva557d5a2013-12-28 21:59:03 -0800461 *
462 * This call will block forever (default timeout == 0) to process IO on the face.
463 * To exit, one expected to call face.shutdown() from one of the callback methods.
464 *
Alexander Afanasyev691c3ce2014-04-23 14:28:04 -0700465 * If positive timeout is specified, then processEvents will exit after this timeout, if
466 * not stopped earlier with face.shutdown() or when all active events finish. The call
467 * can be called repeatedly, if desired.
Alexander Afanasyeva557d5a2013-12-28 21:59:03 -0800468 *
Alexander Afanasyev691c3ce2014-04-23 14:28:04 -0700469 * If negative timeout is specified, then processEvents will not block and process only
470 * pending events.
Alexander Afanasyevf75a0aa2014-01-09 14:29:22 -0800471 *
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700472 * @param timeout maximum time to block the thread
Alexander Afanasyev691c3ce2014-04-23 14:28:04 -0700473 * @param keepThread Keep thread in a blocked state (in event processing), even when
474 * there are no outstanding events (e.g., no Interest/Data is expected)
475 *
476 * @throw This may throw an exception for reading data or in the callback for processing
477 * the data. If you call this from an main event loop, you may want to catch and
478 * log/disregard all exceptions.
Jeff Thompson432c8be2013-08-09 16:16:08 -0700479 */
Alexander Afanasyevfdbfc6d2014-04-14 15:12:11 -0700480 void
Alexander Afanasyevaa0e7da2014-03-17 14:37:33 -0700481 processEvents(const time::milliseconds& timeout = time::milliseconds::zero(),
482 bool keepThread = false);
Jeff Thompson432c8be2013-08-09 16:16:08 -0700483
Alexander Afanasyev691c3ce2014-04-23 14:28:04 -0700484 /**
485 * @brief Shutdown face operations
486 *
487 * This method cancels all pending operations and closes connection to NDN Forwarder.
488 *
489 * Note that this method does not stop IO service and if the same IO service is shared
490 * between multiple Faces or with other IO objects (e.g., Scheduler).
491 */
Alexander Afanasyevfdbfc6d2014-04-14 15:12:11 -0700492 void
Jeff Thompson0050abe2013-09-17 12:50:25 -0700493 shutdown();
Yingdi Yu0d920812014-01-30 14:50:57 -0800494
Alexander Afanasyev691c3ce2014-04-23 14:28:04 -0700495 /**
496 * @brief Get shared_ptr of the IO service object
497 *
498 * @deprecated Use getIoService instead
499 */
Alexander Afanasyev9c578182014-05-14 17:28:28 -0700500 DEPRECATED(
Alexander Afanasyevfdbfc6d2014-04-14 15:12:11 -0700501 shared_ptr<boost::asio::io_service>
Alexander Afanasyev9c578182014-05-14 17:28:28 -0700502 ioService())
Alexander Afanasyev691c3ce2014-04-23 14:28:04 -0700503 {
504 return m_ioService;
505 }
506
507 /**
508 * @brief Get reference to IO service object
509 */
510 boost::asio::io_service&
511 getIoService()
512 {
513 return *m_ioService;
514 }
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800515
516private:
Steve DiBenedettoc07b3a22014-03-19 12:32:52 -0600517 /**
518 * @throws Face::Error on unsupported protocol
519 */
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800520 void
Alexander Afanasyev7682ccb2014-02-20 10:29:35 -0800521 construct(const shared_ptr<Transport>& transport,
Alexander Afanasyev505646e2014-02-24 20:13:37 -0800522 const shared_ptr<boost::asio::io_service>& ioService);
Steve DiBenedettoc07b3a22014-03-19 12:32:52 -0600523
524 bool
525 isSupportedNfdProtocol(const std::string& protocol);
526
527 bool
528 isSupportedNrdProtocol(const std::string& protocol);
529
Alexander Afanasyev691c3ce2014-04-23 14:28:04 -0700530 class ProcessEventsTimeout
531 {
532 };
533
Alexander Afanasyevfdbfc6d2014-04-14 15:12:11 -0700534 void
Alexander Afanasyev6d48bc12014-02-18 00:10:51 -0800535 onReceiveElement(const Block& wire);
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800536
Alexander Afanasyev7dced462014-03-19 15:12:32 -0700537 void
538 asyncShutdown();
Alexander Afanasyevfdbfc6d2014-04-14 15:12:11 -0700539
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800540 static void
541 fireProcessEventsTimeout(const boost::system::error_code& error);
542
Jeff Thompsonb982b6d2013-07-15 18:15:45 -0700543private:
Alexander Afanasyevf39c5372014-02-17 19:42:56 -0800544 shared_ptr<boost::asio::io_service> m_ioService;
Alexander Afanasyevfdbfc6d2014-04-14 15:12:11 -0700545
Alexander Afanasyevf39c5372014-02-17 19:42:56 -0800546 shared_ptr<Transport> m_transport;
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800547
Alexander Afanasyev258ec2b2014-05-14 16:15:37 -0700548 shared_ptr<nfd::Controller> m_nfdController;
Alexander Afanasyevee8bb1e2014-05-02 17:39:54 -0700549 bool m_isDirectNfdFibManagementRequested;
Steve DiBenedettoc07b3a22014-03-19 12:32:52 -0600550
Alexander Afanasyev258ec2b2014-05-14 16:15:37 -0700551 class Impl;
552 shared_ptr<Impl> m_impl;
Jeff Thompsonaa4e6db2013-07-15 17:25:23 -0700553};
554
Steve DiBenedettoc07b3a22014-03-19 12:32:52 -0600555inline bool
556Face::isSupportedNfdProtocol(const std::string& protocol)
557{
558 return protocol == "nfd-0.1";
559}
560
561inline bool
562Face::isSupportedNrdProtocol(const std::string& protocol)
563{
564 return protocol == "nrd-0.1";
565}
566
Alexander Afanasyevee8bb1e2014-05-02 17:39:54 -0700567inline void
568Face::setDirectFibManagement(bool isDirectFibManagementRequested/* = false*/)
Steve DiBenedettoc07b3a22014-03-19 12:32:52 -0600569{
Alexander Afanasyevee8bb1e2014-05-02 17:39:54 -0700570 m_isDirectNfdFibManagementRequested = isDirectFibManagementRequested;
Steve DiBenedettoc07b3a22014-03-19 12:32:52 -0600571}
572
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800573} // namespace ndn
Jeff Thompsonaa4e6db2013-07-15 17:25:23 -0700574
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800575#endif // NDN_FACE_HPP