blob: ab526c3bd0836294aca4c309a47fa1a1c2969e64 [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 Afanasyev9d158f02015-02-17 21:30:19 -08003 * Copyright (c) 2013-2015 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.
Jeff Thompsonaa4e6db2013-07-15 17:25:23 -070020 */
21
Jeff Thompsonb9e3c8e2013-08-02 11:42:51 -070022#ifndef NDN_FACE_HPP
Jeff Thompsona0d18c92013-08-06 13:55:32 -070023#define NDN_FACE_HPP
Jeff Thompsonaa4e6db2013-07-15 17:25:23 -070024
Alexander Afanasyev0222fba2014-02-09 23:16:02 -080025#include "common.hpp"
Alexander Afanasyev258ec2b2014-05-14 16:15:37 -070026
27#include "name.hpp"
Alexander Afanasyev0222fba2014-02-09 23:16:02 -080028#include "interest.hpp"
Alexander Afanasyev258ec2b2014-05-14 16:15:37 -070029#include "interest-filter.hpp"
Alexander Afanasyev0222fba2014-02-09 23:16:02 -080030#include "data.hpp"
Joao Pereira0b3cac52015-07-02 14:49:49 -040031#include "security/signing-info.hpp"
32
33#define NDN_FACE_KEEP_DEPRECATED_REGISTRATION_SIGNING
34
35#ifdef NDN_FACE_KEEP_DEPRECATED_REGISTRATION_SIGNING
Alexander Afanasyev984ad192014-05-02 19:11:15 -070036#include "security/identity-certificate.hpp"
Joao Pereira0b3cac52015-07-02 14:49:49 -040037#endif // NDN_FACE_KEEP_DEPRECATED_REGISTRATION_SIGNING
Alexander Afanasyev0222fba2014-02-09 23:16:02 -080038
Alexander Afanasyev258ec2b2014-05-14 16:15:37 -070039namespace boost {
40namespace asio {
41class io_service;
42}
43}
Alexander Afanasyev0222fba2014-02-09 23:16:02 -080044
Jeff Thompsonaa4e6db2013-07-15 17:25:23 -070045namespace ndn {
46
Alexander Afanasyev258ec2b2014-05-14 16:15:37 -070047class Transport;
48
49class PendingInterestId;
50class RegisteredPrefixId;
51class InterestFilterId;
52
Yingdi Yu1b0311c2015-06-10 14:58:47 -070053namespace security {
54class KeyChain;
55}
56using security::KeyChain;
57
Alexander Afanasyevee8bb1e2014-05-02 17:39:54 -070058namespace nfd {
59class Controller;
60}
Alexander Afanasyevee8bb1e2014-05-02 17:39:54 -070061
Jeff Thompsonfe08e5a2013-08-13 11:15:59 -070062/**
Alexander Afanasyev984ad192014-05-02 19:11:15 -070063 * @brief Callback called when expressed Interest gets satisfied with Data packet
Alexander Afanasyev0222fba2014-02-09 23:16:02 -080064 */
65typedef function<void(const Interest&, Data&)> OnData;
66
67/**
Alexander Afanasyev984ad192014-05-02 19:11:15 -070068 * @brief Callback called when expressed Interest times out
Alexander Afanasyev0222fba2014-02-09 23:16:02 -080069 */
70typedef function<void(const Interest&)> OnTimeout;
71
72/**
Alexander Afanasyev984ad192014-05-02 19:11:15 -070073 * @brief Callback called when incoming Interest matches the specified InterestFilter
Alexander Afanasyev0222fba2014-02-09 23:16:02 -080074 */
Alexander Afanasyev90164962014-03-06 08:29:59 +000075typedef function<void (const InterestFilter&, const Interest&)> OnInterest;
Alexander Afanasyev0222fba2014-02-09 23:16:02 -080076
77/**
Alexander Afanasyev984ad192014-05-02 19:11:15 -070078 * @brief Callback called when registerPrefix or setInterestFilter command succeeds
Alexander Afanasyev0222fba2014-02-09 23:16:02 -080079 */
Alexander Afanasyev984ad192014-05-02 19:11:15 -070080typedef function<void(const Name&)> RegisterPrefixSuccessCallback;
Alexander Afanasyev0222fba2014-02-09 23:16:02 -080081
Alexander Afanasyev984ad192014-05-02 19:11:15 -070082/**
83 * @brief Callback called when registerPrefix or setInterestFilter command fails
84 */
85typedef function<void(const Name&, const std::string&)> RegisterPrefixFailureCallback;
86
87/**
88 * @brief Callback called when unregisterPrefix or unsetInterestFilter command succeeds
89 */
90typedef function<void()> UnregisterPrefixSuccessCallback;
91
92/**
93 * @brief Callback called when unregisterPrefix or unsetInterestFilter command fails
94 */
95typedef function<void(const std::string&)> UnregisterPrefixFailureCallback;
Alexander Afanasyev0222fba2014-02-09 23:16:02 -080096
97
98/**
99 * @brief Abstraction to communicate with local or remote NDN forwarder
Jeff Thompsonfe08e5a2013-08-13 11:15:59 -0700100 */
Alexander Afanasyev8460afb2014-02-15 20:31:42 -0800101class Face : noncopyable
102{
Jeff Thompsonaa4e6db2013-07-15 17:25:23 -0700103public:
Alexander Afanasyevfdbfc6d2014-04-14 15:12:11 -0700104 class Error : public std::runtime_error
105 {
106 public:
107 explicit
108 Error(const std::string& what)
109 : std::runtime_error(what)
110 {
111 }
112 };
Alexander Afanasyevb790d952014-01-24 12:07:53 -0800113
Junxiao Shiedd834e2014-10-28 20:28:58 -0700114public: // constructors
Alexander Afanasyevb790d952014-01-24 12:07:53 -0800115 /**
Alexander Afanasyev691c3ce2014-04-23 14:28:04 -0700116 * @brief Create a new Face using the default transport (UnixTransport)
117 *
Steve DiBenedettoc07b3a22014-03-19 12:32:52 -0600118 * @throws ConfigFile::Error on configuration file parse failure
119 * @throws Face::Error on unsupported protocol
Alexander Afanasyevb790d952014-01-24 12:07:53 -0800120 */
Alexander Afanasyevf7ca3202014-02-14 22:28:31 -0800121 Face();
Alexander Afanasyeve2e0d752014-01-03 13:30:30 -0800122
123 /**
Alexander Afanasyev691c3ce2014-04-23 14:28:04 -0700124 * @brief Create a new Face using the default transport (UnixTransport)
125 *
Alexander Afanasyev691c3ce2014-04-23 14:28:04 -0700126 * @par Usage examples:
127 *
128 * Face face1;
129 * Face face2(face1.getIoService());
130 *
131 * // Now the following ensures that events on both faces are processed
132 * face1.processEvents();
133 * // or face1.getIoService().run();
134 *
135 * @par or
136 *
137 * boost::asio::io_service ioService;
138 * Face face1(ioService);
139 * Face face2(ioService);
140 * ...
141 *
142 * ioService.run();
143 *
144 * @param ioService A reference to boost::io_service object that should control all
145 * IO operations.
146 * @throws ConfigFile::Error on configuration file parse failure
147 * @throws Face::Error on unsupported protocol
148 */
149 explicit
150 Face(boost::asio::io_service& ioService);
151
152 /**
153 * @brief Create a new Face using TcpTransport
154 *
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700155 * @param host The host of the NDN forwarder
156 * @param port (optional) The port or service name of the NDN forwarder (**default**: "6363")
157 *
Steve DiBenedettoc07b3a22014-03-19 12:32:52 -0600158 * @throws Face::Error on unsupported protocol
Jeff Thompsonfe08e5a2013-08-13 11:15:59 -0700159 */
Alexander Afanasyev7682ccb2014-02-20 10:29:35 -0800160 Face(const std::string& host, const std::string& port = "6363");
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800161
162 /**
Alexander Afanasyev691c3ce2014-04-23 14:28:04 -0700163 * @brief Create a new Face using the given Transport
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700164 *
165 * @param transport A shared_ptr to a Transport object used for communication
166 *
Steve DiBenedettoc07b3a22014-03-19 12:32:52 -0600167 * @throws Face::Error on unsupported protocol
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800168 */
Alexander Afanasyevf7ca3202014-02-14 22:28:31 -0800169 explicit
170 Face(const shared_ptr<Transport>& transport);
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800171
172 /**
Alexander Afanasyev691c3ce2014-04-23 14:28:04 -0700173 * @brief Create a new Face using the given Transport and IO service object
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800174 *
Alexander Afanasyev691c3ce2014-04-23 14:28:04 -0700175 * @sa Face(boost::asio::io_service&)
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800176 *
Steve DiBenedettoc07b3a22014-03-19 12:32:52 -0600177 * @throws Face::Error on unsupported protocol
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800178 */
179 Face(const shared_ptr<Transport>& transport,
Alexander Afanasyev691c3ce2014-04-23 14:28:04 -0700180 boost::asio::io_service& ioService);
Alexander Afanasyev7682ccb2014-02-20 10:29:35 -0800181
Jeff Thompson4fe45512013-08-23 14:06:38 -0700182 /**
Junxiao Shiedd834e2014-10-28 20:28:58 -0700183 * @brief Create a new Face using the given Transport and IO service object
184 * @param transport the Transport used for communication
185 * @param ioService the io_service that controls all IO operations
186 * @param keyChain the KeyChain to sign commands
187 * @throws Face::Error on unsupported protocol
188 * @note shared_ptr is passed by value because ownership is shared with this class
189 */
190 Face(shared_ptr<Transport> transport,
191 boost::asio::io_service& ioService,
192 KeyChain& keyChain);
193
194 ~Face();
195
196public: // consumer
197 /**
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800198 * @brief Express Interest
199 *
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700200 * @param interest An Interest to be expressed
201 * @param onData Callback to be called when a matching data packet is received
202 * @param onTimeout (optional) A function object to call if the interest times out
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800203 *
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700204 * @return The pending interest ID which can be used with removePendingInterest
Alexander Afanasyev49bb1fb2014-07-21 12:54:01 -0700205 *
206 * @throws Error when Interest size exceeds maximum limit (MAX_NDN_PACKET_SIZE)
Jeff Thompson4fe45512013-08-23 14:06:38 -0700207 */
Alexander Afanasyevb790d952014-01-24 12:07:53 -0800208 const PendingInterestId*
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800209 expressInterest(const Interest& interest,
210 const OnData& onData, const OnTimeout& onTimeout = OnTimeout());
Jeff Thompson4fe45512013-08-23 14:06:38 -0700211
212 /**
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800213 * @brief Express Interest using name and Interest template
214 *
215 * @param name Name of the Interest
216 * @param tmpl Interest template to fill parameters
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700217 * @param onData Callback to be called when a matching data packet is received
218 * @param onTimeout (optional) A function object to call if the interest times out
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800219 *
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700220 * @return Opaque pending interest ID which can be used with removePendingInterest
Alexander Afanasyev49bb1fb2014-07-21 12:54:01 -0700221 *
222 * @throws Error when Interest size exceeds maximum limit (MAX_NDN_PACKET_SIZE)
Jeff Thompson7aec0252013-08-22 17:29:57 -0700223 */
Alexander Afanasyevb790d952014-01-24 12:07:53 -0800224 const PendingInterestId*
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800225 expressInterest(const Name& name,
Alexander Afanasyev7682ccb2014-02-20 10:29:35 -0800226 const Interest& tmpl,
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800227 const OnData& onData, const OnTimeout& onTimeout = OnTimeout());
Alexander Afanasyevfdbfc6d2014-04-14 15:12:11 -0700228
Jeff Thompson11095142013-10-01 16:20:28 -0700229 /**
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700230 * @brief Cancel previously expressed Interest
Alexander Afanasyev691c3ce2014-04-23 14:28:04 -0700231 *
Jeff Thompson11095142013-10-01 16:20:28 -0700232 * @param pendingInterestId The ID returned from expressInterest.
233 */
234 void
Alexander Afanasyev7682ccb2014-02-20 10:29:35 -0800235 removePendingInterest(const PendingInterestId* pendingInterestId);
Alexander Afanasyevfdbfc6d2014-04-14 15:12:11 -0700236
Jeff Thompson432c8be2013-08-09 16:16:08 -0700237 /**
Alexander Afanasyev6fcdde22014-08-22 19:03:36 -0700238 * @brief Get number of pending Interests
239 */
240 size_t
241 getNPendingInterests() const;
242
Junxiao Shiedd834e2014-10-28 20:28:58 -0700243public: // producer
Alexander Afanasyev6fcdde22014-08-22 19:03:36 -0700244 /**
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700245 * @brief Set InterestFilter to dispatch incoming matching interest to onInterest
246 * callback and register the filtered prefix with the connected NDN forwarder
247 *
248 * This version of setInterestFilter combines setInterestFilter and registerPrefix
249 * operations and is intended to be used when only one filter for the same prefix needed
250 * to be set. When multiple names sharing the same prefix should be dispatched to
251 * different callbacks, use one registerPrefix call, followed (in onSuccess callback) by
252 * a series of setInterestFilter calls.
Alexander Afanasyev691c3ce2014-04-23 14:28:04 -0700253 *
Alexander Afanasyev90164962014-03-06 08:29:59 +0000254 * @param interestFilter Interest filter (prefix part will be registered with the forwarder)
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700255 * @param onInterest A callback to be called when a matching interest is received
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700256 * @param onFailure A callback to be called when prefixRegister command fails
Joao Pereiraba1e3b92015-06-01 17:50:37 -0400257 * @param flags (optional) RIB flags
Joao Pereira0b3cac52015-07-02 14:49:49 -0400258 * @param signingInfo (optional) Signing parameters. When omitted, a default parameters
259 * used in the signature will be used.
Alexander Afanasyev691c3ce2014-04-23 14:28:04 -0700260 *
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700261 * @return Opaque registered prefix ID which can be used with unsetInterestFilter or
262 * removeRegisteredPrefix
Yingdi Yue66bf2a2014-04-28 17:07:36 -0700263 */
264 const RegisteredPrefixId*
Alexander Afanasyev90164962014-03-06 08:29:59 +0000265 setInterestFilter(const InterestFilter& interestFilter,
Yingdi Yue66bf2a2014-04-28 17:07:36 -0700266 const OnInterest& onInterest,
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700267 const RegisterPrefixFailureCallback& onFailure,
Joao Pereira0b3cac52015-07-02 14:49:49 -0400268 const security::SigningInfo& signingInfo = security::SigningInfo(),
Alexander Afanasyev0866f512014-08-11 13:25:09 -0700269 uint64_t flags = nfd::ROUTE_FLAG_CHILD_INHERIT);
Yingdi Yue66bf2a2014-04-28 17:07:36 -0700270
271 /**
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700272 * @brief Set InterestFilter to dispatch incoming matching interest to onInterest
273 * callback and register the filtered prefix with the connected NDN forwarder
274 *
275 * This version of setInterestFilter combines setInterestFilter and registerPrefix
276 * operations and is intended to be used when only one filter for the same prefix needed
277 * to be set. When multiple names sharing the same prefix should be dispatched to
278 * different callbacks, use one registerPrefix call, followed (in onSuccess callback) by
279 * a series of setInterestFilter calls.
Yingdi Yue66bf2a2014-04-28 17:07:36 -0700280 *
Alexander Afanasyev90164962014-03-06 08:29:59 +0000281 * @param interestFilter Interest filter (prefix part will be registered with the forwarder)
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700282 * @param onInterest A callback to be called when a matching interest is received
283 * @param onSuccess A callback to be called when prefixRegister command succeeds
284 * @param onFailure A callback to be called when prefixRegister command fails
Joao Pereiraba1e3b92015-06-01 17:50:37 -0400285 * @param flags (optional) RIB flags
Joao Pereira0b3cac52015-07-02 14:49:49 -0400286 * @param signingInfo (optional) Signing parameters. When omitted, a default parameters
287 * used in the signature will be used.
Yingdi Yue66bf2a2014-04-28 17:07:36 -0700288 *
Joao Pereira0b3cac52015-07-02 14:49:49 -0400289 * @return Opaque registered prefix ID which can be used with unsetInterestFilter or
290 * removeRegisteredPrefix
Yingdi Yue66bf2a2014-04-28 17:07:36 -0700291 */
292 const RegisteredPrefixId*
Alexander Afanasyev90164962014-03-06 08:29:59 +0000293 setInterestFilter(const InterestFilter& interestFilter,
Yingdi Yue66bf2a2014-04-28 17:07:36 -0700294 const OnInterest& onInterest,
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700295 const RegisterPrefixSuccessCallback& onSuccess,
296 const RegisterPrefixFailureCallback& onFailure,
Joao Pereira0b3cac52015-07-02 14:49:49 -0400297 const security::SigningInfo& signingInfo = security::SigningInfo(),
Alexander Afanasyev0866f512014-08-11 13:25:09 -0700298 uint64_t flags = nfd::ROUTE_FLAG_CHILD_INHERIT);
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700299
300 /**
301 * @brief Set InterestFilter to dispatch incoming matching interest to onInterest callback
302 *
303 * @param interestFilter Interest
304 * @param onInterest A callback to be called when a matching interest is received
305 *
306 * This method modifies library's FIB only, and does not register the prefix with the
307 * forwarder. It will always succeed. To register prefix with the forwarder, use
308 * registerPrefix, or use the setInterestFilter overload taking two callbacks.
309 *
310 * @return Opaque interest filter ID which can be used with unsetInterestFilter
311 */
312 const InterestFilterId*
313 setInterestFilter(const InterestFilter& interestFilter,
314 const OnInterest& onInterest);
315
Joao Pereira0b3cac52015-07-02 14:49:49 -0400316#ifdef NDN_FACE_KEEP_DEPRECATED_REGISTRATION_SIGNING
317 /**
318 * @deprecated Use override with SigningInfo instead of this function
319 * @brief Set InterestFilter to dispatch incoming matching interest to onInterest
320 * callback and register the filtered prefix with the connected NDN forwarder
321 *
322 * This version of setInterestFilter combines setInterestFilter and registerPrefix
323 * operations and is intended to be used when only one filter for the same prefix needed
324 * to be set. When multiple names sharing the same prefix should be dispatched to
325 * different callbacks, use one registerPrefix call, followed (in onSuccess callback) by
326 * a series of setInterestFilter calls.
327 *
328 * @param interestFilter Interest filter (prefix part will be registered with the forwarder)
329 * @param onInterest A callback to be called when a matching interest is received
330 * @param onSuccess A callback to be called when prefixRegister command succeeds
331 * @param onFailure A callback to be called when prefixRegister command fails
332 * @param flags (optional) RIB flags
333 * @param certificate (optional) A certificate under which the prefix registration
334 * command is signed. When omitted, a default certificate of
335 * the default identity is used to sign the registration command
336 *
337 * @return Opaque registered prefix ID which can be used with unsetInterestFilter or
338 * removeRegisteredPrefix
339 */
340 const RegisteredPrefixId*
341 setInterestFilter(const InterestFilter& interestFilter,
342 const OnInterest& onInterest,
343 const RegisterPrefixSuccessCallback& onSuccess,
344 const RegisterPrefixFailureCallback& onFailure,
345 const IdentityCertificate& certificate,
346 uint64_t flags = nfd::ROUTE_FLAG_CHILD_INHERIT);
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700347
348 /**
Joao Pereira0b3cac52015-07-02 14:49:49 -0400349 * @deprecated Use override with SigningInfo instead of this function
350 * @brief Set InterestFilter to dispatch incoming matching interest to onInterest
351 * callback and register the filtered prefix with the connected NDN forwarder
352 *
353 * This version of setInterestFilter combines setInterestFilter and registerPrefix
354 * operations and is intended to be used when only one filter for the same prefix needed
355 * to be set. When multiple names sharing the same prefix should be dispatched to
356 * different callbacks, use one registerPrefix call, followed (in onSuccess callback) by
357 * a series of setInterestFilter calls.
358 *
359 * @param interestFilter Interest filter (prefix part will be registered with the forwarder)
360 * @param onInterest A callback to be called when a matching interest is received
361 * @param onFailure A callback to be called when prefixRegister command fails
362 * @param flags (optional) RIB flags
363 * @param certificate (optional) A certificate under which the prefix registration
364 * command is signed. When omitted, a default certificate of
365 * the default identity is used to sign the registration command
366 *
367 * @return Opaque registered prefix ID which can be used with unsetInterestFilter or
368 * removeRegisteredPrefix
369 */
370 const RegisteredPrefixId*
371 setInterestFilter(const InterestFilter& interestFilter,
372 const OnInterest& onInterest,
373 const RegisterPrefixFailureCallback& onFailure,
374 const IdentityCertificate& certificate,
375 uint64_t flags = nfd::ROUTE_FLAG_CHILD_INHERIT);
376
377 /**
378 * @deprecated Use override with SigningInfo instead of this function
379 * @brief Set InterestFilter to dispatch incoming matching interest to onInterest
380 * callback and register the filtered prefix with the connected NDN forwarder
381 *
382 * This version of setInterestFilter combines setInterestFilter and registerPrefix
383 * operations and is intended to be used when only one filter for the same prefix needed
384 * to be set. When multiple names sharing the same prefix should be dispatched to
385 * different callbacks, use one registerPrefix call, followed (in onSuccess callback) by
386 * a series of setInterestFilter calls.
387 *
388 * @param interestFilter Interest filter (prefix part will be registered with the forwarder)
389 * @param onInterest A callback to be called when a matching interest is received
390 * @param onSuccess A callback to be called when prefixRegister command succeeds
391 * @param onFailure A callback to be called when prefixRegister command fails
392 * @param identity A signing identity. A prefix registration command is signed
393 * under the default certificate of this identity
394 * @param flags (optional) RIB flags
395 *
396 * @return Opaque registered prefix ID which can be used with removeRegisteredPrefix
397 */
398 const RegisteredPrefixId*
399 setInterestFilter(const InterestFilter& interestFilter,
400 const OnInterest& onInterest,
401 const RegisterPrefixSuccessCallback& onSuccess,
402 const RegisterPrefixFailureCallback& onFailure,
403 const Name& identity,
404 uint64_t flags = nfd::ROUTE_FLAG_CHILD_INHERIT);
405
406 /**
407 * @deprecated Use override with SigningInfo instead of this function
408 * @brief Set InterestFilter to dispatch incoming matching interest to onInterest
409 * callback and register the filtered prefix with the connected NDN forwarder
410 *
411 * This version of setInterestFilter combines setInterestFilter and registerPrefix
412 * operations and is intended to be used when only one filter for the same prefix needed
413 * to be set. When multiple names sharing the same prefix should be dispatched to
414 * different callbacks, use one registerPrefix call, followed (in onSuccess callback) by
415 * a series of setInterestFilter calls.
416 *
417 * @param interestFilter Interest filter (prefix part will be registered with the forwarder)
418 * @param onInterest A callback to be called when a matching interest is received
419 * @param onFailure A callback to be called when prefixRegister command fails
420 * @param identity A signing identity. A prefix registration command is signed
421 * under the default certificate of this identity
422 * @param flags (optional) RIB flags
423 *
424 * @return Opaque registered prefix ID which can be used with removeRegisteredPrefix
425 */
426 const RegisteredPrefixId*
427 setInterestFilter(const InterestFilter& interestFilter,
428 const OnInterest& onInterest,
429 const RegisterPrefixFailureCallback& onFailure,
430 const Name& identity,
431 uint64_t flags = nfd::ROUTE_FLAG_CHILD_INHERIT);
432#endif // NDN_FACE_KEEP_DEPRECATED_REGISTRATION_SIGNING
433
434 /**
435 * @brief Register prefix with the connected NDN forwarder
436 *
437 * This method only modifies forwarder's RIB and does not associate any
438 * onInterest callbacks. Use setInterestFilter method to dispatch incoming Interests to
439 * the right callbacks.
440 *
441 * @param prefix A prefix to register with the connected NDN forwarder
442 * @param onSuccess A callback to be called when prefixRegister command succeeds
443 * @param onFailure A callback to be called when prefixRegister command fails
444 * @param signingInfo (optional) Signing parameters. When omitted, a default parameters
445 * used in the signature will be used.
446 *
447 * @return The registered prefix ID which can be used with unregisterPrefix
448 */
449 const RegisteredPrefixId*
450 registerPrefix(const Name& prefix,
451 const RegisterPrefixSuccessCallback& onSuccess,
452 const RegisterPrefixFailureCallback& onFailure,
453 const security::SigningInfo& signingInfo = security::SigningInfo(),
454 uint64_t flags = nfd::ROUTE_FLAG_CHILD_INHERIT);
455
456#ifdef NDN_FACE_KEEP_DEPRECATED_REGISTRATION_SIGNING
457 /**
458 * @deprecated Use override with SigningInfo instead of this function
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700459 * @brief Register prefix with the connected NDN forwarder
460 *
Joao Pereiraba1e3b92015-06-01 17:50:37 -0400461 * This method only modifies forwarder's RIB and does not associate any
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700462 * onInterest callbacks. Use setInterestFilter method to dispatch incoming Interests to
463 * the right callbacks.
464 *
465 * @param prefix A prefix to register with the connected NDN forwarder
466 * @param onSuccess A callback to be called when prefixRegister command succeeds
467 * @param onFailure A callback to be called when prefixRegister command fails
468 * @param certificate (optional) A certificate under which the prefix registration
Junxiao Shi6a90f372014-10-13 20:29:30 -0700469 * command is signed. When omitted, a default certificate of
470 * the default identity is used to sign the registration command
Joao Pereiraba1e3b92015-06-01 17:50:37 -0400471 * @param flags (optional) RIB flags
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700472 *
473 * @return The registered prefix ID which can be used with unregisterPrefix
474 */
475 const RegisteredPrefixId*
476 registerPrefix(const Name& prefix,
477 const RegisterPrefixSuccessCallback& onSuccess,
478 const RegisterPrefixFailureCallback& onFailure,
Joao Pereira0b3cac52015-07-02 14:49:49 -0400479 const IdentityCertificate& certificate,
Alexander Afanasyev0866f512014-08-11 13:25:09 -0700480 uint64_t flags = nfd::ROUTE_FLAG_CHILD_INHERIT);
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700481
482 /**
Joao Pereira0b3cac52015-07-02 14:49:49 -0400483 * @deprecated Use override with SigningInfo instead of this function
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700484 * @brief Register prefix with the connected NDN forwarder and call onInterest when a matching
485 * interest is received.
486 *
Joao Pereiraba1e3b92015-06-01 17:50:37 -0400487 * This method only modifies forwarder's RIB and does not associate any
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700488 * onInterest callbacks. Use setInterestFilter method to dispatch incoming Interests to
489 * the right callbacks.
490 *
491 * @param prefix A prefix to register with the connected NDN forwarder
492 * @param onSuccess A callback to be called when prefixRegister command succeeds
493 * @param onFailure A callback to be called when prefixRegister command fails
Junxiao Shi6a90f372014-10-13 20:29:30 -0700494 * @param identity A signing identity. A prefix registration command is signed
495 * under the default certificate of this identity
Joao Pereiraba1e3b92015-06-01 17:50:37 -0400496 * @param flags (optional) RIB flags
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700497 *
498 * @return The registered prefix ID which can be used with unregisterPrefix
499 */
500 const RegisteredPrefixId*
501 registerPrefix(const Name& prefix,
502 const RegisterPrefixSuccessCallback& onSuccess,
503 const RegisterPrefixFailureCallback& onFailure,
Alexander Afanasyev0866f512014-08-11 13:25:09 -0700504 const Name& identity,
505 uint64_t flags = nfd::ROUTE_FLAG_CHILD_INHERIT);
Joao Pereira0b3cac52015-07-02 14:49:49 -0400506#endif // NDN_FACE_KEEP_DEPRECATED_REGISTRATION_SIGNING
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700507
508 /**
Alexander Afanasyev1b01c312014-05-26 16:58:10 +0300509 * @brief Remove the registered prefix entry with the registeredPrefixId
Alexander Afanasyev691c3ce2014-04-23 14:28:04 -0700510 *
511 * This does not affect another registered prefix with a different registeredPrefixId,
512 * even it if has the same prefix name. If there is no entry with the
513 * registeredPrefixId, do nothing.
514 *
Alexander Afanasyevee8bb1e2014-05-02 17:39:54 -0700515 * unsetInterestFilter will use the same credentials as original
516 * setInterestFilter/registerPrefix command
517 *
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700518 * @param registeredPrefixId The ID returned from registerPrefix
Jeff Thompson11095142013-10-01 16:20:28 -0700519 */
520 void
Alexander Afanasyev7682ccb2014-02-20 10:29:35 -0800521 unsetInterestFilter(const RegisteredPrefixId* registeredPrefixId);
Alexander Afanasyeva557d5a2013-12-28 21:59:03 -0800522
Alexander Afanasyevee8bb1e2014-05-02 17:39:54 -0700523 /**
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700524 * @brief Remove previously set InterestFilter from library's FIB
525 *
526 * This method always succeeds and will **NOT** send any request to the connected
527 * forwarder.
528 *
529 * @param interestFilterId The ID returned from setInterestFilter.
530 */
531 void
532 unsetInterestFilter(const InterestFilterId* interestFilterId);
533
534 /**
Joao Pereiraba1e3b92015-06-01 17:50:37 -0400535 * @brief Unregister prefix from RIB
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700536 *
537 * unregisterPrefix will use the same credentials as original
538 * setInterestFilter/registerPrefix command
539 *
540 * If registeredPrefixId was obtained using setInterestFilter, the corresponding
541 * InterestFilter will be unset too.
542 *
Alexander Afanasyev770827c2014-05-13 17:42:55 -0700543 * @param registeredPrefixId The ID returned from registerPrefix
544 * @param onSuccess Callback to be called when operation succeeds
545 * @param onFailure Callback to be called when operation fails
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700546 */
547 void
548 unregisterPrefix(const RegisteredPrefixId* registeredPrefixId,
549 const UnregisterPrefixSuccessCallback& onSuccess,
550 const UnregisterPrefixFailureCallback& onFailure);
551
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800552 /**
Alexander Afanasyeva557d5a2013-12-28 21:59:03 -0800553 * @brief Publish data packet
554 *
Alexander Afanasyev691c3ce2014-04-23 14:28:04 -0700555 * This method can be called to satisfy the incoming Interest or to put Data packet into
Alexander Afanasyev6a05b4b2014-07-18 17:23:00 -0700556 * the cache of the local NDN forwarder.
557 *
558 * @param data Data packet to publish. It is highly recommended to use Data packet that
559 * was created using make_shared<Data>(...). Otherwise, put() will make an
560 * extra copy of the Data packet to ensure validity of published Data until
561 * asynchronous put() operation finishes.
Alexander Afanasyev49bb1fb2014-07-21 12:54:01 -0700562 *
563 * @throws Error when Data size exceeds maximum limit (MAX_NDN_PACKET_SIZE)
Alexander Afanasyeva557d5a2013-12-28 21:59:03 -0800564 */
565 void
Alexander Afanasyev7682ccb2014-02-20 10:29:35 -0800566 put(const Data& data);
Alexander Afanasyevfdbfc6d2014-04-14 15:12:11 -0700567
Junxiao Shiedd834e2014-10-28 20:28:58 -0700568public: // IO routine
Jeff Thompson86507bc2013-08-23 20:51:38 -0700569 /**
Alexander Afanasyev691c3ce2014-04-23 14:28:04 -0700570 * @brief Process any data to receive or call timeout callbacks.
Alexander Afanasyeva557d5a2013-12-28 21:59:03 -0800571 *
572 * This call will block forever (default timeout == 0) to process IO on the face.
573 * To exit, one expected to call face.shutdown() from one of the callback methods.
574 *
Alexander Afanasyev691c3ce2014-04-23 14:28:04 -0700575 * If positive timeout is specified, then processEvents will exit after this timeout, if
576 * not stopped earlier with face.shutdown() or when all active events finish. The call
577 * can be called repeatedly, if desired.
Alexander Afanasyeva557d5a2013-12-28 21:59:03 -0800578 *
Alexander Afanasyev691c3ce2014-04-23 14:28:04 -0700579 * If negative timeout is specified, then processEvents will not block and process only
580 * pending events.
Alexander Afanasyevf75a0aa2014-01-09 14:29:22 -0800581 *
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700582 * @param timeout maximum time to block the thread
Alexander Afanasyev691c3ce2014-04-23 14:28:04 -0700583 * @param keepThread Keep thread in a blocked state (in event processing), even when
584 * there are no outstanding events (e.g., no Interest/Data is expected)
585 *
586 * @throw This may throw an exception for reading data or in the callback for processing
587 * the data. If you call this from an main event loop, you may want to catch and
588 * log/disregard all exceptions.
Jeff Thompson432c8be2013-08-09 16:16:08 -0700589 */
Alexander Afanasyevfdbfc6d2014-04-14 15:12:11 -0700590 void
Alexander Afanasyevaa0e7da2014-03-17 14:37:33 -0700591 processEvents(const time::milliseconds& timeout = time::milliseconds::zero(),
592 bool keepThread = false);
Jeff Thompson432c8be2013-08-09 16:16:08 -0700593
Alexander Afanasyev691c3ce2014-04-23 14:28:04 -0700594 /**
595 * @brief Shutdown face operations
596 *
597 * This method cancels all pending operations and closes connection to NDN Forwarder.
598 *
599 * Note that this method does not stop IO service and if the same IO service is shared
600 * between multiple Faces or with other IO objects (e.g., Scheduler).
601 */
Alexander Afanasyevfdbfc6d2014-04-14 15:12:11 -0700602 void
Jeff Thompson0050abe2013-09-17 12:50:25 -0700603 shutdown();
Yingdi Yu0d920812014-01-30 14:50:57 -0800604
Alexander Afanasyev691c3ce2014-04-23 14:28:04 -0700605 /**
Alexander Afanasyev691c3ce2014-04-23 14:28:04 -0700606 * @brief Get reference to IO service object
607 */
608 boost::asio::io_service&
609 getIoService()
610 {
Junxiao Shi2cced062014-11-02 21:27:38 -0700611 return m_ioService;
Alexander Afanasyev691c3ce2014-04-23 14:28:04 -0700612 }
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800613
614private:
Steve DiBenedettoa8659ff2014-12-04 14:50:28 -0700615
616 /**
617 * @throws ConfigFile::Error on parse error and unsupported protocols
618 */
619 void
Joao Pereira68c0d882015-05-19 14:27:55 -0400620 construct(KeyChain& keyChain);
Steve DiBenedettoa8659ff2014-12-04 14:50:28 -0700621
Steve DiBenedettoc07b3a22014-03-19 12:32:52 -0600622 /**
623 * @throws Face::Error on unsupported protocol
Junxiao Shi2cced062014-11-02 21:27:38 -0700624 * @note shared_ptr is passed by value because ownership is transferred to this function
Steve DiBenedettoc07b3a22014-03-19 12:32:52 -0600625 */
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800626 void
Joao Pereira68c0d882015-05-19 14:27:55 -0400627 construct(shared_ptr<Transport> transport, KeyChain& keyChain);
Steve DiBenedettoc07b3a22014-03-19 12:32:52 -0600628
Alexander Afanasyevfdbfc6d2014-04-14 15:12:11 -0700629 void
Alexander Afanasyev6d48bc12014-02-18 00:10:51 -0800630 onReceiveElement(const Block& wire);
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800631
Alexander Afanasyev7dced462014-03-19 15:12:32 -0700632 void
633 asyncShutdown();
Alexander Afanasyevfdbfc6d2014-04-14 15:12:11 -0700634
Jeff Thompsonb982b6d2013-07-15 18:15:45 -0700635private:
Junxiao Shi2cced062014-11-02 21:27:38 -0700636 /// the IO service owned by this Face, could be null
637 unique_ptr<boost::asio::io_service> m_internalIoService;
638 /// the IO service used by this Face
639 boost::asio::io_service& m_ioService;
Alexander Afanasyevfdbfc6d2014-04-14 15:12:11 -0700640
Alexander Afanasyevf39c5372014-02-17 19:42:56 -0800641 shared_ptr<Transport> m_transport;
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800642
Junxiao Shiedd834e2014-10-28 20:28:58 -0700643 /** @brief if not null, a pointer to an internal KeyChain owned by Face
644 * @note if a KeyChain is supplied to constructor, this pointer will be null,
645 * and the passed KeyChain is given to nfdController;
646 * currently Face does not keep the KeyChain passed in constructor
647 * because it's not needed, but this may change in the future
648 */
Joao Pereira68c0d882015-05-19 14:27:55 -0400649 unique_ptr<KeyChain> m_internalKeyChain;
Junxiao Shiedd834e2014-10-28 20:28:58 -0700650
Joao Pereira68c0d882015-05-19 14:27:55 -0400651 unique_ptr<nfd::Controller> m_nfdController;
Steve DiBenedettoc07b3a22014-03-19 12:32:52 -0600652
Alexander Afanasyev258ec2b2014-05-14 16:15:37 -0700653 class Impl;
Joao Pereira68c0d882015-05-19 14:27:55 -0400654 unique_ptr<Impl> m_impl;
Jeff Thompsonaa4e6db2013-07-15 17:25:23 -0700655};
656
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800657} // namespace ndn
Jeff Thompsonaa4e6db2013-07-15 17:25:23 -0700658
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800659#endif // NDN_FACE_HPP