blob: 9a01d1703c59cfe8eb8c176e82c3064ab0c15807 [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"
Junxiao Shi4b469982015-12-03 18:20:19 +000031#include "encoding/nfd-constants.hpp"
Eric Newberry83872fd2015-08-06 17:01:24 -070032#include "lp/nack.hpp"
Junxiao Shi4b469982015-12-03 18:20:19 +000033#include "security/signing-info.hpp"
Joao Pereira0b3cac52015-07-02 14:49:49 -040034
35#define NDN_FACE_KEEP_DEPRECATED_REGISTRATION_SIGNING
36
37#ifdef NDN_FACE_KEEP_DEPRECATED_REGISTRATION_SIGNING
Alexander Afanasyev984ad192014-05-02 19:11:15 -070038#include "security/identity-certificate.hpp"
Joao Pereira0b3cac52015-07-02 14:49:49 -040039#endif // NDN_FACE_KEEP_DEPRECATED_REGISTRATION_SIGNING
Alexander Afanasyev0222fba2014-02-09 23:16:02 -080040
Alexander Afanasyev258ec2b2014-05-14 16:15:37 -070041namespace boost {
42namespace asio {
43class io_service;
44}
45}
Alexander Afanasyev0222fba2014-02-09 23:16:02 -080046
Jeff Thompsonaa4e6db2013-07-15 17:25:23 -070047namespace ndn {
48
Alexander Afanasyev258ec2b2014-05-14 16:15:37 -070049class Transport;
50
51class PendingInterestId;
52class RegisteredPrefixId;
53class InterestFilterId;
54
Yingdi Yu1b0311c2015-06-10 14:58:47 -070055namespace security {
56class KeyChain;
57}
58using security::KeyChain;
59
Alexander Afanasyevee8bb1e2014-05-02 17:39:54 -070060namespace nfd {
61class Controller;
62}
Alexander Afanasyevee8bb1e2014-05-02 17:39:54 -070063
Jeff Thompsonfe08e5a2013-08-13 11:15:59 -070064/**
Eric Newberry83872fd2015-08-06 17:01:24 -070065 * @brief Callback called when expressed Interest gets satisfied with a Data packet
66 */
67typedef function<void(const Interest&, const Data&)> DataCallback;
68
69/**
70 * @brief Callback called when Nack is sent in response to expressed Interest
71 */
72typedef function<void(const Interest&, const lp::Nack&)> NackCallback;
73
74/**
75 * @brief Callback called when expressed Interest times out
76 */
77typedef function<void(const Interest&)> TimeoutCallback;
78
79/**
Alexander Afanasyev984ad192014-05-02 19:11:15 -070080 * @brief Callback called when expressed Interest gets satisfied with Data packet
Eric Newberry83872fd2015-08-06 17:01:24 -070081 * @deprecated use DataCallback
Alexander Afanasyev0222fba2014-02-09 23:16:02 -080082 */
83typedef function<void(const Interest&, Data&)> OnData;
84
85/**
Alexander Afanasyev984ad192014-05-02 19:11:15 -070086 * @brief Callback called when expressed Interest times out
Eric Newberry83872fd2015-08-06 17:01:24 -070087 * @deprecated use TimeoutCallback
Alexander Afanasyev0222fba2014-02-09 23:16:02 -080088 */
89typedef function<void(const Interest&)> OnTimeout;
90
91/**
Alexander Afanasyev984ad192014-05-02 19:11:15 -070092 * @brief Callback called when incoming Interest matches the specified InterestFilter
Alexander Afanasyev0222fba2014-02-09 23:16:02 -080093 */
Alexander Afanasyev90164962014-03-06 08:29:59 +000094typedef function<void (const InterestFilter&, const Interest&)> OnInterest;
Alexander Afanasyev0222fba2014-02-09 23:16:02 -080095
96/**
Alexander Afanasyev984ad192014-05-02 19:11:15 -070097 * @brief Callback called when registerPrefix or setInterestFilter command succeeds
Alexander Afanasyev0222fba2014-02-09 23:16:02 -080098 */
Alexander Afanasyev984ad192014-05-02 19:11:15 -070099typedef function<void(const Name&)> RegisterPrefixSuccessCallback;
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800100
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700101/**
102 * @brief Callback called when registerPrefix or setInterestFilter command fails
103 */
104typedef function<void(const Name&, const std::string&)> RegisterPrefixFailureCallback;
105
106/**
107 * @brief Callback called when unregisterPrefix or unsetInterestFilter command succeeds
108 */
109typedef function<void()> UnregisterPrefixSuccessCallback;
110
111/**
112 * @brief Callback called when unregisterPrefix or unsetInterestFilter command fails
113 */
114typedef function<void(const std::string&)> UnregisterPrefixFailureCallback;
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800115
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800116/**
117 * @brief Abstraction to communicate with local or remote NDN forwarder
Jeff Thompsonfe08e5a2013-08-13 11:15:59 -0700118 */
Alexander Afanasyev8460afb2014-02-15 20:31:42 -0800119class Face : noncopyable
120{
Jeff Thompsonaa4e6db2013-07-15 17:25:23 -0700121public:
Alexander Afanasyevfdbfc6d2014-04-14 15:12:11 -0700122 class Error : public std::runtime_error
123 {
124 public:
125 explicit
126 Error(const std::string& what)
127 : std::runtime_error(what)
128 {
129 }
130 };
Alexander Afanasyevb790d952014-01-24 12:07:53 -0800131
Junxiao Shiedd834e2014-10-28 20:28:58 -0700132public: // constructors
Alexander Afanasyevb790d952014-01-24 12:07:53 -0800133 /**
Alexander Afanasyev691c3ce2014-04-23 14:28:04 -0700134 * @brief Create a new Face using the default transport (UnixTransport)
135 *
Steve DiBenedettoc07b3a22014-03-19 12:32:52 -0600136 * @throws ConfigFile::Error on configuration file parse failure
137 * @throws Face::Error on unsupported protocol
Alexander Afanasyevb790d952014-01-24 12:07:53 -0800138 */
Alexander Afanasyevf7ca3202014-02-14 22:28:31 -0800139 Face();
Alexander Afanasyeve2e0d752014-01-03 13:30:30 -0800140
141 /**
Alexander Afanasyev691c3ce2014-04-23 14:28:04 -0700142 * @brief Create a new Face using the default transport (UnixTransport)
143 *
Alexander Afanasyev691c3ce2014-04-23 14:28:04 -0700144 * @par Usage examples:
145 *
146 * Face face1;
147 * Face face2(face1.getIoService());
148 *
149 * // Now the following ensures that events on both faces are processed
150 * face1.processEvents();
151 * // or face1.getIoService().run();
152 *
153 * @par or
154 *
155 * boost::asio::io_service ioService;
156 * Face face1(ioService);
157 * Face face2(ioService);
158 * ...
159 *
160 * ioService.run();
161 *
162 * @param ioService A reference to boost::io_service object that should control all
163 * IO operations.
164 * @throws ConfigFile::Error on configuration file parse failure
165 * @throws Face::Error on unsupported protocol
166 */
167 explicit
168 Face(boost::asio::io_service& ioService);
169
170 /**
171 * @brief Create a new Face using TcpTransport
172 *
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700173 * @param host The host of the NDN forwarder
174 * @param port (optional) The port or service name of the NDN forwarder (**default**: "6363")
175 *
Steve DiBenedettoc07b3a22014-03-19 12:32:52 -0600176 * @throws Face::Error on unsupported protocol
Jeff Thompsonfe08e5a2013-08-13 11:15:59 -0700177 */
Alexander Afanasyev7682ccb2014-02-20 10:29:35 -0800178 Face(const std::string& host, const std::string& port = "6363");
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800179
180 /**
Alexander Afanasyev691c3ce2014-04-23 14:28:04 -0700181 * @brief Create a new Face using the given Transport
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700182 *
183 * @param transport A shared_ptr to a Transport object used for communication
184 *
Steve DiBenedettoc07b3a22014-03-19 12:32:52 -0600185 * @throws Face::Error on unsupported protocol
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800186 */
Alexander Afanasyevf7ca3202014-02-14 22:28:31 -0800187 explicit
188 Face(const shared_ptr<Transport>& transport);
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800189
190 /**
Alexander Afanasyev691c3ce2014-04-23 14:28:04 -0700191 * @brief Create a new Face using the given Transport and IO service object
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800192 *
Alexander Afanasyev691c3ce2014-04-23 14:28:04 -0700193 * @sa Face(boost::asio::io_service&)
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800194 *
Steve DiBenedettoc07b3a22014-03-19 12:32:52 -0600195 * @throws Face::Error on unsupported protocol
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800196 */
197 Face(const shared_ptr<Transport>& transport,
Alexander Afanasyev691c3ce2014-04-23 14:28:04 -0700198 boost::asio::io_service& ioService);
Alexander Afanasyev7682ccb2014-02-20 10:29:35 -0800199
Jeff Thompson4fe45512013-08-23 14:06:38 -0700200 /**
Junxiao Shiedd834e2014-10-28 20:28:58 -0700201 * @brief Create a new Face using the given Transport and IO service object
202 * @param transport the Transport used for communication
203 * @param ioService the io_service that controls all IO operations
204 * @param keyChain the KeyChain to sign commands
205 * @throws Face::Error on unsupported protocol
206 * @note shared_ptr is passed by value because ownership is shared with this class
207 */
208 Face(shared_ptr<Transport> transport,
209 boost::asio::io_service& ioService,
210 KeyChain& keyChain);
211
212 ~Face();
213
214public: // consumer
215 /**
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800216 * @brief Express Interest
Eric Newberry83872fd2015-08-06 17:01:24 -0700217 * @param interest the Interest; a copy will be made, so that the caller is not
218 * required to maintain the argument unchanged
219 * @param afterSatisfied function to be invoked if Data is returned
220 * @param afterNacked function to be invoked if Network NACK is returned
221 * @param afterTimeout function to be invoked if neither Data nor Network NACK
222 * is returned within InterestLifetime
223 */
224 const PendingInterestId*
225 expressInterest(const Interest& interest,
226 const DataCallback& afterSatisfied,
227 const NackCallback& afterNacked,
228 const TimeoutCallback& afterTimeout);
229
230 /**
231 * @brief Express Interest
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800232 *
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700233 * @param interest An Interest to be expressed
234 * @param onData Callback to be called when a matching data packet is received
Eric Newberry83872fd2015-08-06 17:01:24 -0700235 * @param onTimeout (optional) A function object to call if the interest times out or is Nacked
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800236 *
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700237 * @return The pending interest ID which can be used with removePendingInterest
Alexander Afanasyev49bb1fb2014-07-21 12:54:01 -0700238 *
239 * @throws Error when Interest size exceeds maximum limit (MAX_NDN_PACKET_SIZE)
Eric Newberry83872fd2015-08-06 17:01:24 -0700240 *
241 * @deprecated use expressInterest(Interest, DataCallback, NackCallback, TimeoutCallback)
Jeff Thompson4fe45512013-08-23 14:06:38 -0700242 */
Alexander Afanasyevb790d952014-01-24 12:07:53 -0800243 const PendingInterestId*
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800244 expressInterest(const Interest& interest,
Eric Newberry83872fd2015-08-06 17:01:24 -0700245 const OnData& onData,
246 const OnTimeout& onTimeout = nullptr);
Jeff Thompson4fe45512013-08-23 14:06:38 -0700247
248 /**
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800249 * @brief Express Interest using name and Interest template
250 *
251 * @param name Name of the Interest
252 * @param tmpl Interest template to fill parameters
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700253 * @param onData Callback to be called when a matching data packet is received
Eric Newberry83872fd2015-08-06 17:01:24 -0700254 * @param onTimeout (optional) A function object to call if the interest times out or is Nacked
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800255 *
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700256 * @return Opaque pending interest ID which can be used with removePendingInterest
Alexander Afanasyev49bb1fb2014-07-21 12:54:01 -0700257 *
258 * @throws Error when Interest size exceeds maximum limit (MAX_NDN_PACKET_SIZE)
Eric Newberry83872fd2015-08-06 17:01:24 -0700259 *
260 * @deprecated use expressInterest(Interest, DataCallback, NackCallback, TimeoutCallback)
Jeff Thompson7aec0252013-08-22 17:29:57 -0700261 */
Alexander Afanasyevb790d952014-01-24 12:07:53 -0800262 const PendingInterestId*
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800263 expressInterest(const Name& name,
Alexander Afanasyev7682ccb2014-02-20 10:29:35 -0800264 const Interest& tmpl,
Eric Newberry83872fd2015-08-06 17:01:24 -0700265 const OnData& onData,
266 const OnTimeout& onTimeout = nullptr);
Alexander Afanasyevfdbfc6d2014-04-14 15:12:11 -0700267
Jeff Thompson11095142013-10-01 16:20:28 -0700268 /**
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700269 * @brief Cancel previously expressed Interest
Alexander Afanasyev691c3ce2014-04-23 14:28:04 -0700270 *
Jeff Thompson11095142013-10-01 16:20:28 -0700271 * @param pendingInterestId The ID returned from expressInterest.
272 */
273 void
Alexander Afanasyev7682ccb2014-02-20 10:29:35 -0800274 removePendingInterest(const PendingInterestId* pendingInterestId);
Alexander Afanasyevfdbfc6d2014-04-14 15:12:11 -0700275
Jeff Thompson432c8be2013-08-09 16:16:08 -0700276 /**
Ilya Moiseenko56b0bf82015-11-08 11:14:28 -0500277 * @brief Cancel all previously expressed Interests
278 */
279 void
280 removeAllPendingInterests();
281
282 /**
Alexander Afanasyev6fcdde22014-08-22 19:03:36 -0700283 * @brief Get number of pending Interests
284 */
285 size_t
286 getNPendingInterests() const;
287
Junxiao Shiedd834e2014-10-28 20:28:58 -0700288public: // producer
Alexander Afanasyev6fcdde22014-08-22 19:03:36 -0700289 /**
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700290 * @brief Set InterestFilter to dispatch incoming matching interest to onInterest
291 * callback and register the filtered prefix with the connected NDN forwarder
292 *
293 * This version of setInterestFilter combines setInterestFilter and registerPrefix
294 * operations and is intended to be used when only one filter for the same prefix needed
295 * to be set. When multiple names sharing the same prefix should be dispatched to
296 * different callbacks, use one registerPrefix call, followed (in onSuccess callback) by
297 * a series of setInterestFilter calls.
Alexander Afanasyev691c3ce2014-04-23 14:28:04 -0700298 *
Alexander Afanasyev90164962014-03-06 08:29:59 +0000299 * @param interestFilter Interest filter (prefix part will be registered with the forwarder)
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700300 * @param onInterest A callback to be called when a matching interest is received
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700301 * @param onFailure A callback to be called when prefixRegister command fails
Joao Pereiraba1e3b92015-06-01 17:50:37 -0400302 * @param flags (optional) RIB flags
Joao Pereira0b3cac52015-07-02 14:49:49 -0400303 * @param signingInfo (optional) Signing parameters. When omitted, a default parameters
304 * used in the signature will be used.
Alexander Afanasyev691c3ce2014-04-23 14:28:04 -0700305 *
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700306 * @return Opaque registered prefix ID which can be used with unsetInterestFilter or
307 * removeRegisteredPrefix
Yingdi Yue66bf2a2014-04-28 17:07:36 -0700308 */
309 const RegisteredPrefixId*
Alexander Afanasyev90164962014-03-06 08:29:59 +0000310 setInterestFilter(const InterestFilter& interestFilter,
Yingdi Yue66bf2a2014-04-28 17:07:36 -0700311 const OnInterest& onInterest,
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700312 const RegisterPrefixFailureCallback& onFailure,
Joao Pereira0b3cac52015-07-02 14:49:49 -0400313 const security::SigningInfo& signingInfo = security::SigningInfo(),
Alexander Afanasyev0866f512014-08-11 13:25:09 -0700314 uint64_t flags = nfd::ROUTE_FLAG_CHILD_INHERIT);
Yingdi Yue66bf2a2014-04-28 17:07:36 -0700315
316 /**
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700317 * @brief Set InterestFilter to dispatch incoming matching interest to onInterest
318 * callback and register the filtered prefix with the connected NDN forwarder
319 *
320 * This version of setInterestFilter combines setInterestFilter and registerPrefix
321 * operations and is intended to be used when only one filter for the same prefix needed
322 * to be set. When multiple names sharing the same prefix should be dispatched to
323 * different callbacks, use one registerPrefix call, followed (in onSuccess callback) by
324 * a series of setInterestFilter calls.
Yingdi Yue66bf2a2014-04-28 17:07:36 -0700325 *
Alexander Afanasyev90164962014-03-06 08:29:59 +0000326 * @param interestFilter Interest filter (prefix part will be registered with the forwarder)
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700327 * @param onInterest A callback to be called when a matching interest is received
328 * @param onSuccess A callback to be called when prefixRegister command succeeds
329 * @param onFailure A callback to be called when prefixRegister command fails
Joao Pereiraba1e3b92015-06-01 17:50:37 -0400330 * @param flags (optional) RIB flags
Joao Pereira0b3cac52015-07-02 14:49:49 -0400331 * @param signingInfo (optional) Signing parameters. When omitted, a default parameters
332 * used in the signature will be used.
Yingdi Yue66bf2a2014-04-28 17:07:36 -0700333 *
Joao Pereira0b3cac52015-07-02 14:49:49 -0400334 * @return Opaque registered prefix ID which can be used with unsetInterestFilter or
335 * removeRegisteredPrefix
Yingdi Yue66bf2a2014-04-28 17:07:36 -0700336 */
337 const RegisteredPrefixId*
Alexander Afanasyev90164962014-03-06 08:29:59 +0000338 setInterestFilter(const InterestFilter& interestFilter,
Yingdi Yue66bf2a2014-04-28 17:07:36 -0700339 const OnInterest& onInterest,
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700340 const RegisterPrefixSuccessCallback& onSuccess,
341 const RegisterPrefixFailureCallback& onFailure,
Joao Pereira0b3cac52015-07-02 14:49:49 -0400342 const security::SigningInfo& signingInfo = security::SigningInfo(),
Alexander Afanasyev0866f512014-08-11 13:25:09 -0700343 uint64_t flags = nfd::ROUTE_FLAG_CHILD_INHERIT);
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700344
345 /**
346 * @brief Set InterestFilter to dispatch incoming matching interest to onInterest callback
347 *
348 * @param interestFilter Interest
349 * @param onInterest A callback to be called when a matching interest is received
350 *
351 * This method modifies library's FIB only, and does not register the prefix with the
352 * forwarder. It will always succeed. To register prefix with the forwarder, use
353 * registerPrefix, or use the setInterestFilter overload taking two callbacks.
354 *
355 * @return Opaque interest filter ID which can be used with unsetInterestFilter
356 */
357 const InterestFilterId*
358 setInterestFilter(const InterestFilter& interestFilter,
359 const OnInterest& onInterest);
360
Joao Pereira0b3cac52015-07-02 14:49:49 -0400361#ifdef NDN_FACE_KEEP_DEPRECATED_REGISTRATION_SIGNING
362 /**
363 * @deprecated Use override with SigningInfo instead of this function
364 * @brief Set InterestFilter to dispatch incoming matching interest to onInterest
365 * callback and register the filtered prefix with the connected NDN forwarder
366 *
367 * This version of setInterestFilter combines setInterestFilter and registerPrefix
368 * operations and is intended to be used when only one filter for the same prefix needed
369 * to be set. When multiple names sharing the same prefix should be dispatched to
370 * different callbacks, use one registerPrefix call, followed (in onSuccess callback) by
371 * a series of setInterestFilter calls.
372 *
373 * @param interestFilter Interest filter (prefix part will be registered with the forwarder)
374 * @param onInterest A callback to be called when a matching interest is received
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 flags (optional) RIB flags
378 * @param certificate (optional) A certificate under which the prefix registration
379 * command is signed. When omitted, a default certificate of
380 * the default identity is used to sign the registration command
381 *
382 * @return Opaque registered prefix ID which can be used with unsetInterestFilter or
383 * removeRegisteredPrefix
384 */
philobb778e72015-08-25 14:49:19 -0700385 DEPRECATED(
Joao Pereira0b3cac52015-07-02 14:49:49 -0400386 const RegisteredPrefixId*
387 setInterestFilter(const InterestFilter& interestFilter,
388 const OnInterest& onInterest,
389 const RegisterPrefixSuccessCallback& onSuccess,
390 const RegisterPrefixFailureCallback& onFailure,
391 const IdentityCertificate& certificate,
philobb778e72015-08-25 14:49:19 -0700392 uint64_t flags = nfd::ROUTE_FLAG_CHILD_INHERIT));
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700393
394 /**
Joao Pereira0b3cac52015-07-02 14:49:49 -0400395 * @deprecated Use override with SigningInfo instead of this function
396 * @brief Set InterestFilter to dispatch incoming matching interest to onInterest
397 * callback and register the filtered prefix with the connected NDN forwarder
398 *
399 * This version of setInterestFilter combines setInterestFilter and registerPrefix
400 * operations and is intended to be used when only one filter for the same prefix needed
401 * to be set. When multiple names sharing the same prefix should be dispatched to
402 * different callbacks, use one registerPrefix call, followed (in onSuccess callback) by
403 * a series of setInterestFilter calls.
404 *
405 * @param interestFilter Interest filter (prefix part will be registered with the forwarder)
406 * @param onInterest A callback to be called when a matching interest is received
407 * @param onFailure A callback to be called when prefixRegister command fails
408 * @param flags (optional) RIB flags
409 * @param certificate (optional) A certificate under which the prefix registration
410 * command is signed. When omitted, a default certificate of
411 * the default identity is used to sign the registration command
412 *
413 * @return Opaque registered prefix ID which can be used with unsetInterestFilter or
414 * removeRegisteredPrefix
415 */
philobb778e72015-08-25 14:49:19 -0700416 DEPRECATED(
Joao Pereira0b3cac52015-07-02 14:49:49 -0400417 const RegisteredPrefixId*
418 setInterestFilter(const InterestFilter& interestFilter,
419 const OnInterest& onInterest,
420 const RegisterPrefixFailureCallback& onFailure,
421 const IdentityCertificate& certificate,
philobb778e72015-08-25 14:49:19 -0700422 uint64_t flags = nfd::ROUTE_FLAG_CHILD_INHERIT));
Joao Pereira0b3cac52015-07-02 14:49:49 -0400423
424 /**
425 * @deprecated Use override with SigningInfo instead of this function
426 * @brief Set InterestFilter to dispatch incoming matching interest to onInterest
427 * callback and register the filtered prefix with the connected NDN forwarder
428 *
429 * This version of setInterestFilter combines setInterestFilter and registerPrefix
430 * operations and is intended to be used when only one filter for the same prefix needed
431 * to be set. When multiple names sharing the same prefix should be dispatched to
432 * different callbacks, use one registerPrefix call, followed (in onSuccess callback) by
433 * a series of setInterestFilter calls.
434 *
435 * @param interestFilter Interest filter (prefix part will be registered with the forwarder)
436 * @param onInterest A callback to be called when a matching interest is received
437 * @param onSuccess A callback to be called when prefixRegister command succeeds
438 * @param onFailure A callback to be called when prefixRegister command fails
439 * @param identity A signing identity. A prefix registration command is signed
440 * under the default certificate of this identity
441 * @param flags (optional) RIB flags
442 *
443 * @return Opaque registered prefix ID which can be used with removeRegisteredPrefix
444 */
philobb778e72015-08-25 14:49:19 -0700445 DEPRECATED(
Joao Pereira0b3cac52015-07-02 14:49:49 -0400446 const RegisteredPrefixId*
447 setInterestFilter(const InterestFilter& interestFilter,
448 const OnInterest& onInterest,
449 const RegisterPrefixSuccessCallback& onSuccess,
450 const RegisterPrefixFailureCallback& onFailure,
451 const Name& identity,
philobb778e72015-08-25 14:49:19 -0700452 uint64_t flags = nfd::ROUTE_FLAG_CHILD_INHERIT));
Joao Pereira0b3cac52015-07-02 14:49:49 -0400453
454 /**
455 * @deprecated Use override with SigningInfo instead of this function
456 * @brief Set InterestFilter to dispatch incoming matching interest to onInterest
457 * callback and register the filtered prefix with the connected NDN forwarder
458 *
459 * This version of setInterestFilter combines setInterestFilter and registerPrefix
460 * operations and is intended to be used when only one filter for the same prefix needed
461 * to be set. When multiple names sharing the same prefix should be dispatched to
462 * different callbacks, use one registerPrefix call, followed (in onSuccess callback) by
463 * a series of setInterestFilter calls.
464 *
465 * @param interestFilter Interest filter (prefix part will be registered with the forwarder)
466 * @param onInterest A callback to be called when a matching interest is received
467 * @param onFailure A callback to be called when prefixRegister command fails
468 * @param identity A signing identity. A prefix registration command is signed
469 * under the default certificate of this identity
470 * @param flags (optional) RIB flags
471 *
472 * @return Opaque registered prefix ID which can be used with removeRegisteredPrefix
473 */
philobb778e72015-08-25 14:49:19 -0700474 DEPRECATED(
Joao Pereira0b3cac52015-07-02 14:49:49 -0400475 const RegisteredPrefixId*
476 setInterestFilter(const InterestFilter& interestFilter,
477 const OnInterest& onInterest,
478 const RegisterPrefixFailureCallback& onFailure,
479 const Name& identity,
philobb778e72015-08-25 14:49:19 -0700480 uint64_t flags = nfd::ROUTE_FLAG_CHILD_INHERIT));
Joao Pereira0b3cac52015-07-02 14:49:49 -0400481#endif // NDN_FACE_KEEP_DEPRECATED_REGISTRATION_SIGNING
482
483 /**
484 * @brief Register prefix with the connected NDN forwarder
485 *
486 * This method only modifies forwarder's RIB and does not associate any
487 * onInterest callbacks. Use setInterestFilter method to dispatch incoming Interests to
488 * the right callbacks.
489 *
490 * @param prefix A prefix to register with the connected NDN forwarder
491 * @param onSuccess A callback to be called when prefixRegister command succeeds
492 * @param onFailure A callback to be called when prefixRegister command fails
493 * @param signingInfo (optional) Signing parameters. When omitted, a default parameters
494 * used in the signature will be used.
Alexander Afanasyevf2a46222015-09-17 18:01:30 -0700495 * @param flags Prefix registration flags
Joao Pereira0b3cac52015-07-02 14:49:49 -0400496 *
497 * @return The registered prefix ID which can be used with unregisterPrefix
Alexander Afanasyevf2a46222015-09-17 18:01:30 -0700498 * @see nfd::RouteFlags
Joao Pereira0b3cac52015-07-02 14:49:49 -0400499 */
500 const RegisteredPrefixId*
501 registerPrefix(const Name& prefix,
502 const RegisterPrefixSuccessCallback& onSuccess,
503 const RegisterPrefixFailureCallback& onFailure,
504 const security::SigningInfo& signingInfo = security::SigningInfo(),
505 uint64_t flags = nfd::ROUTE_FLAG_CHILD_INHERIT);
506
507#ifdef NDN_FACE_KEEP_DEPRECATED_REGISTRATION_SIGNING
508 /**
509 * @deprecated Use override with SigningInfo instead of this function
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700510 * @brief Register prefix with the connected NDN forwarder
511 *
Joao Pereiraba1e3b92015-06-01 17:50:37 -0400512 * This method only modifies forwarder's RIB and does not associate any
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700513 * onInterest callbacks. Use setInterestFilter method to dispatch incoming Interests to
514 * the right callbacks.
515 *
516 * @param prefix A prefix to register with the connected NDN forwarder
517 * @param onSuccess A callback to be called when prefixRegister command succeeds
518 * @param onFailure A callback to be called when prefixRegister command fails
519 * @param certificate (optional) A certificate under which the prefix registration
Junxiao Shi6a90f372014-10-13 20:29:30 -0700520 * command is signed. When omitted, a default certificate of
521 * the default identity is used to sign the registration command
Joao Pereiraba1e3b92015-06-01 17:50:37 -0400522 * @param flags (optional) RIB flags
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700523 *
524 * @return The registered prefix ID which can be used with unregisterPrefix
525 */
philobb778e72015-08-25 14:49:19 -0700526 DEPRECATED(
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700527 const RegisteredPrefixId*
528 registerPrefix(const Name& prefix,
529 const RegisterPrefixSuccessCallback& onSuccess,
530 const RegisterPrefixFailureCallback& onFailure,
Joao Pereira0b3cac52015-07-02 14:49:49 -0400531 const IdentityCertificate& certificate,
philobb778e72015-08-25 14:49:19 -0700532 uint64_t flags = nfd::ROUTE_FLAG_CHILD_INHERIT));
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700533
534 /**
Joao Pereira0b3cac52015-07-02 14:49:49 -0400535 * @deprecated Use override with SigningInfo instead of this function
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700536 * @brief Register prefix with the connected NDN forwarder and call onInterest when a matching
537 * interest is received.
538 *
Joao Pereiraba1e3b92015-06-01 17:50:37 -0400539 * This method only modifies forwarder's RIB and does not associate any
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700540 * onInterest callbacks. Use setInterestFilter method to dispatch incoming Interests to
541 * the right callbacks.
542 *
543 * @param prefix A prefix to register with the connected NDN forwarder
544 * @param onSuccess A callback to be called when prefixRegister command succeeds
545 * @param onFailure A callback to be called when prefixRegister command fails
Junxiao Shi6a90f372014-10-13 20:29:30 -0700546 * @param identity A signing identity. A prefix registration command is signed
547 * under the default certificate of this identity
Joao Pereiraba1e3b92015-06-01 17:50:37 -0400548 * @param flags (optional) RIB flags
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700549 *
550 * @return The registered prefix ID which can be used with unregisterPrefix
551 */
philobb778e72015-08-25 14:49:19 -0700552 DEPRECATED(
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700553 const RegisteredPrefixId*
554 registerPrefix(const Name& prefix,
555 const RegisterPrefixSuccessCallback& onSuccess,
556 const RegisterPrefixFailureCallback& onFailure,
Alexander Afanasyev0866f512014-08-11 13:25:09 -0700557 const Name& identity,
philobb778e72015-08-25 14:49:19 -0700558 uint64_t flags = nfd::ROUTE_FLAG_CHILD_INHERIT));
Joao Pereira0b3cac52015-07-02 14:49:49 -0400559#endif // NDN_FACE_KEEP_DEPRECATED_REGISTRATION_SIGNING
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700560
561 /**
Alexander Afanasyev1b01c312014-05-26 16:58:10 +0300562 * @brief Remove the registered prefix entry with the registeredPrefixId
Alexander Afanasyev691c3ce2014-04-23 14:28:04 -0700563 *
564 * This does not affect another registered prefix with a different registeredPrefixId,
565 * even it if has the same prefix name. If there is no entry with the
566 * registeredPrefixId, do nothing.
567 *
Alexander Afanasyevee8bb1e2014-05-02 17:39:54 -0700568 * unsetInterestFilter will use the same credentials as original
569 * setInterestFilter/registerPrefix command
570 *
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700571 * @param registeredPrefixId The ID returned from registerPrefix
Jeff Thompson11095142013-10-01 16:20:28 -0700572 */
573 void
Alexander Afanasyev7682ccb2014-02-20 10:29:35 -0800574 unsetInterestFilter(const RegisteredPrefixId* registeredPrefixId);
Alexander Afanasyeva557d5a2013-12-28 21:59:03 -0800575
Alexander Afanasyevee8bb1e2014-05-02 17:39:54 -0700576 /**
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700577 * @brief Remove previously set InterestFilter from library's FIB
578 *
579 * This method always succeeds and will **NOT** send any request to the connected
580 * forwarder.
581 *
582 * @param interestFilterId The ID returned from setInterestFilter.
583 */
584 void
585 unsetInterestFilter(const InterestFilterId* interestFilterId);
586
587 /**
Joao Pereiraba1e3b92015-06-01 17:50:37 -0400588 * @brief Unregister prefix from RIB
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700589 *
590 * unregisterPrefix will use the same credentials as original
591 * setInterestFilter/registerPrefix command
592 *
593 * If registeredPrefixId was obtained using setInterestFilter, the corresponding
594 * InterestFilter will be unset too.
595 *
Alexander Afanasyev770827c2014-05-13 17:42:55 -0700596 * @param registeredPrefixId The ID returned from registerPrefix
597 * @param onSuccess Callback to be called when operation succeeds
598 * @param onFailure Callback to be called when operation fails
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700599 */
600 void
601 unregisterPrefix(const RegisteredPrefixId* registeredPrefixId,
602 const UnregisterPrefixSuccessCallback& onSuccess,
603 const UnregisterPrefixFailureCallback& onFailure);
604
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800605 /**
Alexander Afanasyeva557d5a2013-12-28 21:59:03 -0800606 * @brief Publish data packet
607 *
Alexander Afanasyev691c3ce2014-04-23 14:28:04 -0700608 * This method can be called to satisfy the incoming Interest or to put Data packet into
Alexander Afanasyev6a05b4b2014-07-18 17:23:00 -0700609 * the cache of the local NDN forwarder.
610 *
611 * @param data Data packet to publish. It is highly recommended to use Data packet that
612 * was created using make_shared<Data>(...). Otherwise, put() will make an
613 * extra copy of the Data packet to ensure validity of published Data until
614 * asynchronous put() operation finishes.
Alexander Afanasyev49bb1fb2014-07-21 12:54:01 -0700615 *
616 * @throws Error when Data size exceeds maximum limit (MAX_NDN_PACKET_SIZE)
Alexander Afanasyeva557d5a2013-12-28 21:59:03 -0800617 */
618 void
Alexander Afanasyev7682ccb2014-02-20 10:29:35 -0800619 put(const Data& data);
Alexander Afanasyevfdbfc6d2014-04-14 15:12:11 -0700620
Eric Newberry83872fd2015-08-06 17:01:24 -0700621 /**
622 * @brief sends a Network NACK
623 * @param nack the Nack; a copy will be made, so that the caller is not required to
624 * maintain the argument unchanged
625 */
626 void
627 put(const lp::Nack& nack);
628
Junxiao Shiedd834e2014-10-28 20:28:58 -0700629public: // IO routine
Jeff Thompson86507bc2013-08-23 20:51:38 -0700630 /**
Alexander Afanasyev691c3ce2014-04-23 14:28:04 -0700631 * @brief Process any data to receive or call timeout callbacks.
Alexander Afanasyeva557d5a2013-12-28 21:59:03 -0800632 *
633 * This call will block forever (default timeout == 0) to process IO on the face.
634 * To exit, one expected to call face.shutdown() from one of the callback methods.
635 *
Alexander Afanasyev691c3ce2014-04-23 14:28:04 -0700636 * If positive timeout is specified, then processEvents will exit after this timeout, if
637 * not stopped earlier with face.shutdown() or when all active events finish. The call
638 * can be called repeatedly, if desired.
Alexander Afanasyeva557d5a2013-12-28 21:59:03 -0800639 *
Alexander Afanasyev691c3ce2014-04-23 14:28:04 -0700640 * If negative timeout is specified, then processEvents will not block and process only
641 * pending events.
Alexander Afanasyevf75a0aa2014-01-09 14:29:22 -0800642 *
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700643 * @param timeout maximum time to block the thread
Alexander Afanasyev691c3ce2014-04-23 14:28:04 -0700644 * @param keepThread Keep thread in a blocked state (in event processing), even when
645 * there are no outstanding events (e.g., no Interest/Data is expected)
646 *
647 * @throw This may throw an exception for reading data or in the callback for processing
648 * the data. If you call this from an main event loop, you may want to catch and
649 * log/disregard all exceptions.
Jeff Thompson432c8be2013-08-09 16:16:08 -0700650 */
Alexander Afanasyevfdbfc6d2014-04-14 15:12:11 -0700651 void
Alexander Afanasyevaa0e7da2014-03-17 14:37:33 -0700652 processEvents(const time::milliseconds& timeout = time::milliseconds::zero(),
653 bool keepThread = false);
Jeff Thompson432c8be2013-08-09 16:16:08 -0700654
Alexander Afanasyev691c3ce2014-04-23 14:28:04 -0700655 /**
656 * @brief Shutdown face operations
657 *
658 * This method cancels all pending operations and closes connection to NDN Forwarder.
659 *
660 * Note that this method does not stop IO service and if the same IO service is shared
661 * between multiple Faces or with other IO objects (e.g., Scheduler).
662 */
Alexander Afanasyevfdbfc6d2014-04-14 15:12:11 -0700663 void
Jeff Thompson0050abe2013-09-17 12:50:25 -0700664 shutdown();
Yingdi Yu0d920812014-01-30 14:50:57 -0800665
Alexander Afanasyev691c3ce2014-04-23 14:28:04 -0700666 /**
Alexander Afanasyev691c3ce2014-04-23 14:28:04 -0700667 * @brief Get reference to IO service object
668 */
669 boost::asio::io_service&
670 getIoService()
671 {
Junxiao Shi2cced062014-11-02 21:27:38 -0700672 return m_ioService;
Alexander Afanasyev691c3ce2014-04-23 14:28:04 -0700673 }
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800674
675private:
Steve DiBenedettoa8659ff2014-12-04 14:50:28 -0700676
677 /**
678 * @throws ConfigFile::Error on parse error and unsupported protocols
679 */
680 void
Joao Pereira68c0d882015-05-19 14:27:55 -0400681 construct(KeyChain& keyChain);
Steve DiBenedettoa8659ff2014-12-04 14:50:28 -0700682
Steve DiBenedettoc07b3a22014-03-19 12:32:52 -0600683 /**
684 * @throws Face::Error on unsupported protocol
Junxiao Shi2cced062014-11-02 21:27:38 -0700685 * @note shared_ptr is passed by value because ownership is transferred to this function
Steve DiBenedettoc07b3a22014-03-19 12:32:52 -0600686 */
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800687 void
Joao Pereira68c0d882015-05-19 14:27:55 -0400688 construct(shared_ptr<Transport> transport, KeyChain& keyChain);
Steve DiBenedettoc07b3a22014-03-19 12:32:52 -0600689
Alexander Afanasyevfdbfc6d2014-04-14 15:12:11 -0700690 void
Eric Newberry83872fd2015-08-06 17:01:24 -0700691 onReceiveElement(const Block& blockFromDaemon);
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800692
Alexander Afanasyev7dced462014-03-19 15:12:32 -0700693 void
694 asyncShutdown();
Alexander Afanasyevfdbfc6d2014-04-14 15:12:11 -0700695
Jeff Thompsonb982b6d2013-07-15 18:15:45 -0700696private:
Junxiao Shi2cced062014-11-02 21:27:38 -0700697 /// the IO service owned by this Face, could be null
698 unique_ptr<boost::asio::io_service> m_internalIoService;
699 /// the IO service used by this Face
700 boost::asio::io_service& m_ioService;
Alexander Afanasyevfdbfc6d2014-04-14 15:12:11 -0700701
Alexander Afanasyevf39c5372014-02-17 19:42:56 -0800702 shared_ptr<Transport> m_transport;
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800703
Junxiao Shiedd834e2014-10-28 20:28:58 -0700704 /** @brief if not null, a pointer to an internal KeyChain owned by Face
705 * @note if a KeyChain is supplied to constructor, this pointer will be null,
706 * and the passed KeyChain is given to nfdController;
707 * currently Face does not keep the KeyChain passed in constructor
708 * because it's not needed, but this may change in the future
709 */
Joao Pereira68c0d882015-05-19 14:27:55 -0400710 unique_ptr<KeyChain> m_internalKeyChain;
Junxiao Shiedd834e2014-10-28 20:28:58 -0700711
Joao Pereira68c0d882015-05-19 14:27:55 -0400712 unique_ptr<nfd::Controller> m_nfdController;
Steve DiBenedettoc07b3a22014-03-19 12:32:52 -0600713
Alexander Afanasyev258ec2b2014-05-14 16:15:37 -0700714 class Impl;
Joao Pereira68c0d882015-05-19 14:27:55 -0400715 unique_ptr<Impl> m_impl;
Jeff Thompsonaa4e6db2013-07-15 17:25:23 -0700716};
717
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800718} // namespace ndn
Jeff Thompsonaa4e6db2013-07-15 17:25:23 -0700719
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800720#endif // NDN_FACE_HPP