blob: b375e93d859e8823957b8430ec04c631c6d08aee [file] [log] [blame]
Alexander Afanasyevc169a812014-05-20 20:37:29 -04001/* -*- Mode:C++; c-file-style:"gnu"; indent-tabs-mode:nil; -*- */
Junxiao Shi2ed9e072017-08-13 16:45:48 +00002/*
Alexander Afanasyev4c9a3d52017-01-03 17:45:19 -08003 * Copyright (c) 2013-2017 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"
Alexander Afanasyev4c9a3d52017-01-03 17:45:19 -080034#include "security/key-chain.hpp"
Joao Pereira0b3cac52015-07-02 14:49:49 -040035
Alexander Afanasyev258ec2b2014-05-14 16:15:37 -070036namespace boost {
37namespace asio {
38class io_service;
Alexander Afanasyev8cf1c562016-06-23 16:01:55 -070039} // namespace asio
40} // namespace boost
Alexander Afanasyev0222fba2014-02-09 23:16:02 -080041
Jeff Thompsonaa4e6db2013-07-15 17:25:23 -070042namespace ndn {
43
Alexander Afanasyev258ec2b2014-05-14 16:15:37 -070044class Transport;
45
46class PendingInterestId;
47class RegisteredPrefixId;
48class InterestFilterId;
49
Alexander Afanasyevee8bb1e2014-05-02 17:39:54 -070050namespace nfd {
51class Controller;
Alexander Afanasyev8cf1c562016-06-23 16:01:55 -070052} // namespace nfd
Alexander Afanasyevee8bb1e2014-05-02 17:39:54 -070053
Jeff Thompsonfe08e5a2013-08-13 11:15:59 -070054/**
Junxiao Shi103d8ed2016-08-07 20:34:10 +000055 * @brief Callback invoked when expressed Interest gets satisfied with a Data packet
Eric Newberry83872fd2015-08-06 17:01:24 -070056 */
57typedef function<void(const Interest&, const Data&)> DataCallback;
58
59/**
Junxiao Shi103d8ed2016-08-07 20:34:10 +000060 * @brief Callback invoked when Nack is sent in response to expressed Interest
Eric Newberry83872fd2015-08-06 17:01:24 -070061 */
62typedef function<void(const Interest&, const lp::Nack&)> NackCallback;
63
64/**
Junxiao Shi103d8ed2016-08-07 20:34:10 +000065 * @brief Callback invoked when expressed Interest times out
Eric Newberry83872fd2015-08-06 17:01:24 -070066 */
67typedef function<void(const Interest&)> TimeoutCallback;
68
69/**
Junxiao Shi103d8ed2016-08-07 20:34:10 +000070 * @brief Callback invoked when incoming Interest matches the specified InterestFilter
71 */
72typedef function<void(const InterestFilter&, const Interest&)> InterestCallback;
73
74/**
Junxiao Shi103d8ed2016-08-07 20:34:10 +000075 * @brief Callback invoked when registerPrefix or setInterestFilter command succeeds
Alexander Afanasyev0222fba2014-02-09 23:16:02 -080076 */
Alexander Afanasyev984ad192014-05-02 19:11:15 -070077typedef function<void(const Name&)> RegisterPrefixSuccessCallback;
Alexander Afanasyev0222fba2014-02-09 23:16:02 -080078
Alexander Afanasyev984ad192014-05-02 19:11:15 -070079/**
Junxiao Shi103d8ed2016-08-07 20:34:10 +000080 * @brief Callback invoked when registerPrefix or setInterestFilter command fails
Alexander Afanasyev984ad192014-05-02 19:11:15 -070081 */
82typedef function<void(const Name&, const std::string&)> RegisterPrefixFailureCallback;
83
84/**
Junxiao Shi103d8ed2016-08-07 20:34:10 +000085 * @brief Callback invoked when unregisterPrefix or unsetInterestFilter command succeeds
Alexander Afanasyev984ad192014-05-02 19:11:15 -070086 */
87typedef function<void()> UnregisterPrefixSuccessCallback;
88
89/**
Junxiao Shi103d8ed2016-08-07 20:34:10 +000090 * @brief Callback invoked when unregisterPrefix or unsetInterestFilter command fails
Alexander Afanasyev984ad192014-05-02 19:11:15 -070091 */
92typedef function<void(const std::string&)> UnregisterPrefixFailureCallback;
Alexander Afanasyev0222fba2014-02-09 23:16:02 -080093
Alexander Afanasyev0222fba2014-02-09 23:16:02 -080094/**
Junxiao Shi103d8ed2016-08-07 20:34:10 +000095 * @brief Provide a communication channel with local or remote NDN forwarder
Jeff Thompsonfe08e5a2013-08-13 11:15:59 -070096 */
Alexander Afanasyev8460afb2014-02-15 20:31:42 -080097class Face : noncopyable
98{
Jeff Thompsonaa4e6db2013-07-15 17:25:23 -070099public:
Alexander Afanasyevfdbfc6d2014-04-14 15:12:11 -0700100 class Error : public std::runtime_error
101 {
102 public:
103 explicit
104 Error(const std::string& what)
105 : std::runtime_error(what)
106 {
107 }
108 };
Alexander Afanasyevb790d952014-01-24 12:07:53 -0800109
Junxiao Shiedd834e2014-10-28 20:28:58 -0700110public: // constructors
Alexander Afanasyevb790d952014-01-24 12:07:53 -0800111 /**
Junxiao Shi103d8ed2016-08-07 20:34:10 +0000112 * @brief Create Face using given transport (or default transport if omitted)
113 * @param transport the transport for lower layer communication. If nullptr,
114 * a default transport will be used. The default transport is
115 * determined from a FaceUri in NDN_CLIENT_TRANSPORT environ,
116 * a FaceUri in configuration file 'transport' key, or UnixTransport.
Alexander Afanasyev691c3ce2014-04-23 14:28:04 -0700117 *
Junxiao Shi103d8ed2016-08-07 20:34:10 +0000118 * @throw ConfigFile::Error if @p transport is nullptr, and the configuration file cannot be
119 * parsed or specifies an unsupported protocol
120 * @note shared_ptr is passed by value because ownership is shared with this class
Alexander Afanasyevb790d952014-01-24 12:07:53 -0800121 */
Junxiao Shi103d8ed2016-08-07 20:34:10 +0000122 explicit
123 Face(shared_ptr<Transport> transport = nullptr);
Alexander Afanasyeve2e0d752014-01-03 13:30:30 -0800124
125 /**
Junxiao Shi103d8ed2016-08-07 20:34:10 +0000126 * @brief Create Face using default transport and given io_service
Alexander Afanasyev691c3ce2014-04-23 14:28:04 -0700127 *
Junxiao Shi103d8ed2016-08-07 20:34:10 +0000128 * Usage examples:
Alexander Afanasyev691c3ce2014-04-23 14:28:04 -0700129 *
Junxiao Shi103d8ed2016-08-07 20:34:10 +0000130 * @code
131 * Face face1;
132 * Face face2(face1.getIoService());
Alexander Afanasyev691c3ce2014-04-23 14:28:04 -0700133 *
Junxiao Shi103d8ed2016-08-07 20:34:10 +0000134 * // Now the following ensures that events on both faces are processed
135 * face1.processEvents();
136 * // or face1.getIoService().run();
137 * @endcode
Alexander Afanasyev691c3ce2014-04-23 14:28:04 -0700138 *
Junxiao Shi103d8ed2016-08-07 20:34:10 +0000139 * or
Alexander Afanasyev691c3ce2014-04-23 14:28:04 -0700140 *
Junxiao Shi103d8ed2016-08-07 20:34:10 +0000141 * @code
142 * boost::asio::io_service ioService;
143 * Face face1(ioService);
144 * Face face2(ioService);
Alexander Afanasyev691c3ce2014-04-23 14:28:04 -0700145 *
Junxiao Shi103d8ed2016-08-07 20:34:10 +0000146 * ioService.run();
147 * @endcode
Alexander Afanasyev691c3ce2014-04-23 14:28:04 -0700148 *
149 * @param ioService A reference to boost::io_service object that should control all
150 * IO operations.
Junxiao Shi103d8ed2016-08-07 20:34:10 +0000151 * @throw ConfigFile::Error the configuration file cannot be parsed or specifies an unsupported protocol
Alexander Afanasyev691c3ce2014-04-23 14:28:04 -0700152 */
153 explicit
154 Face(boost::asio::io_service& ioService);
155
156 /**
Junxiao Shi103d8ed2016-08-07 20:34:10 +0000157 * @brief Create Face using TcpTransport
Alexander Afanasyev691c3ce2014-04-23 14:28:04 -0700158 *
Junxiao Shi103d8ed2016-08-07 20:34:10 +0000159 * @param host IP address or hostname of the NDN forwarder
160 * @param port port number or service name of the NDN forwarder (**default**: "6363")
Jeff Thompsonfe08e5a2013-08-13 11:15:59 -0700161 */
Junxiao Shiae0b4182016-08-08 22:53:17 +0000162 explicit
Alexander Afanasyev7682ccb2014-02-20 10:29:35 -0800163 Face(const std::string& host, const std::string& port = "6363");
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800164
165 /**
Junxiao Shi103d8ed2016-08-07 20:34:10 +0000166 * @brief Create Face using given transport and KeyChain
167 * @param transport the transport for lower layer communication. If nullptr,
168 * a default transport will be used.
Alexander Afanasyev8cf1c562016-06-23 16:01:55 -0700169 * @param keyChain the KeyChain to sign commands
170 *
Junxiao Shi103d8ed2016-08-07 20:34:10 +0000171 * @sa Face(shared_ptr<Transport>)
172 *
173 * @throw ConfigFile::Error if @p transport is nullptr, and the configuration file cannot be
174 * parsed or specifies an unsupported protocol
Alexander Afanasyev8cf1c562016-06-23 16:01:55 -0700175 * @note shared_ptr is passed by value because ownership is shared with this class
176 */
177 Face(shared_ptr<Transport> transport, KeyChain& keyChain);
178
179 /**
Junxiao Shi103d8ed2016-08-07 20:34:10 +0000180 * @brief Create Face using given transport and IO service
181 * @param transport the transport for lower layer communication. If nullptr,
182 * a default transport will be used.
Alexander Afanasyevbb64c172015-12-29 20:32:45 -0800183 * @param ioService the io_service that controls all IO operations
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800184 *
Alexander Afanasyev691c3ce2014-04-23 14:28:04 -0700185 * @sa Face(boost::asio::io_service&)
Junxiao Shi103d8ed2016-08-07 20:34:10 +0000186 * @sa Face(shared_ptr<Transport>)
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800187 *
Junxiao Shi103d8ed2016-08-07 20:34:10 +0000188 * @throw ConfigFile::Error if @p transport is nullptr, and the configuration file cannot be
189 * parsed or specifies an unsupported protocol
Alexander Afanasyev8cf1c562016-06-23 16:01:55 -0700190 * @note shared_ptr is passed by value because ownership is shared with this class
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800191 */
Alexander Afanasyev8cf1c562016-06-23 16:01:55 -0700192 Face(shared_ptr<Transport> transport, boost::asio::io_service& ioService);
Alexander Afanasyev7682ccb2014-02-20 10:29:35 -0800193
Jeff Thompson4fe45512013-08-23 14:06:38 -0700194 /**
Junxiao Shi103d8ed2016-08-07 20:34:10 +0000195 * @brief Create a new Face using given Transport and IO service
196 * @param transport the transport for lower layer communication. If nullptr,
197 * a default transport will be used.
Junxiao Shiedd834e2014-10-28 20:28:58 -0700198 * @param ioService the io_service that controls all IO operations
199 * @param keyChain the KeyChain to sign commands
Alexander Afanasyev8cf1c562016-06-23 16:01:55 -0700200 *
Junxiao Shi103d8ed2016-08-07 20:34:10 +0000201 * @sa Face(boost::asio::io_service&)
202 * @sa Face(shared_ptr<Transport>, KeyChain&)
203 *
204 * @throw ConfigFile::Error if @p transport is nullptr, and the configuration file cannot be
205 * parsed or specifies an unsupported protocol
Junxiao Shiedd834e2014-10-28 20:28:58 -0700206 * @note shared_ptr is passed by value because ownership is shared with this class
207 */
Alexander Afanasyev8cf1c562016-06-23 16:01:55 -0700208 Face(shared_ptr<Transport> transport, boost::asio::io_service& ioService, KeyChain& keyChain);
Junxiao Shiedd834e2014-10-28 20:28:58 -0700209
Davide Pesavento7f20d6e2017-01-16 14:43:58 -0500210 virtual
Junxiao Shiedd834e2014-10-28 20:28:58 -0700211 ~Face();
212
213public: // consumer
214 /**
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800215 * @brief Express Interest
Eric Newberry83872fd2015-08-06 17:01:24 -0700216 * @param interest the Interest; a copy will be made, so that the caller is not
217 * required to maintain the argument unchanged
218 * @param afterSatisfied function to be invoked if Data is returned
219 * @param afterNacked function to be invoked if Network NACK is returned
220 * @param afterTimeout function to be invoked if neither Data nor Network NACK
221 * is returned within InterestLifetime
222 */
223 const PendingInterestId*
224 expressInterest(const Interest& interest,
225 const DataCallback& afterSatisfied,
226 const NackCallback& afterNacked,
227 const TimeoutCallback& afterTimeout);
228
229 /**
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 /**
Ilya Moiseenko56b0bf82015-11-08 11:14:28 -0500238 * @brief Cancel all previously expressed Interests
239 */
240 void
241 removeAllPendingInterests();
242
243 /**
Alexander Afanasyev6fcdde22014-08-22 19:03:36 -0700244 * @brief Get number of pending Interests
245 */
246 size_t
247 getNPendingInterests() const;
248
Junxiao Shiedd834e2014-10-28 20:28:58 -0700249public: // producer
Alexander Afanasyev6fcdde22014-08-22 19:03:36 -0700250 /**
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700251 * @brief Set InterestFilter to dispatch incoming matching interest to onInterest
252 * callback and register the filtered prefix with the connected NDN forwarder
253 *
254 * This version of setInterestFilter combines setInterestFilter and registerPrefix
255 * operations and is intended to be used when only one filter for the same prefix needed
256 * to be set. When multiple names sharing the same prefix should be dispatched to
257 * different callbacks, use one registerPrefix call, followed (in onSuccess callback) by
258 * a series of setInterestFilter calls.
Alexander Afanasyev691c3ce2014-04-23 14:28:04 -0700259 *
Alexander Afanasyev90164962014-03-06 08:29:59 +0000260 * @param interestFilter Interest filter (prefix part will be registered with the forwarder)
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700261 * @param onInterest A callback to be called when a matching interest is received
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700262 * @param onFailure A callback to be called when prefixRegister command fails
Joao Pereiraba1e3b92015-06-01 17:50:37 -0400263 * @param flags (optional) RIB flags
Joao Pereira0b3cac52015-07-02 14:49:49 -0400264 * @param signingInfo (optional) Signing parameters. When omitted, a default parameters
265 * used in the signature will be used.
Alexander Afanasyev691c3ce2014-04-23 14:28:04 -0700266 *
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700267 * @return Opaque registered prefix ID which can be used with unsetInterestFilter or
268 * removeRegisteredPrefix
Yingdi Yue66bf2a2014-04-28 17:07:36 -0700269 */
270 const RegisteredPrefixId*
Alexander Afanasyev90164962014-03-06 08:29:59 +0000271 setInterestFilter(const InterestFilter& interestFilter,
Junxiao Shi103d8ed2016-08-07 20:34:10 +0000272 const InterestCallback& onInterest,
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700273 const RegisterPrefixFailureCallback& onFailure,
Joao Pereira0b3cac52015-07-02 14:49:49 -0400274 const security::SigningInfo& signingInfo = security::SigningInfo(),
Alexander Afanasyev0866f512014-08-11 13:25:09 -0700275 uint64_t flags = nfd::ROUTE_FLAG_CHILD_INHERIT);
Yingdi Yue66bf2a2014-04-28 17:07:36 -0700276
277 /**
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700278 * @brief Set InterestFilter to dispatch incoming matching interest to onInterest
279 * callback and register the filtered prefix with the connected NDN forwarder
280 *
281 * This version of setInterestFilter combines setInterestFilter and registerPrefix
282 * operations and is intended to be used when only one filter for the same prefix needed
283 * to be set. When multiple names sharing the same prefix should be dispatched to
284 * different callbacks, use one registerPrefix call, followed (in onSuccess callback) by
285 * a series of setInterestFilter calls.
Yingdi Yue66bf2a2014-04-28 17:07:36 -0700286 *
Alexander Afanasyev90164962014-03-06 08:29:59 +0000287 * @param interestFilter Interest filter (prefix part will be registered with the forwarder)
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700288 * @param onInterest A callback to be called when a matching interest is received
289 * @param onSuccess A callback to be called when prefixRegister command succeeds
290 * @param onFailure A callback to be called when prefixRegister command fails
Joao Pereiraba1e3b92015-06-01 17:50:37 -0400291 * @param flags (optional) RIB flags
Joao Pereira0b3cac52015-07-02 14:49:49 -0400292 * @param signingInfo (optional) Signing parameters. When omitted, a default parameters
293 * used in the signature will be used.
Yingdi Yue66bf2a2014-04-28 17:07:36 -0700294 *
Joao Pereira0b3cac52015-07-02 14:49:49 -0400295 * @return Opaque registered prefix ID which can be used with unsetInterestFilter or
296 * removeRegisteredPrefix
Yingdi Yue66bf2a2014-04-28 17:07:36 -0700297 */
298 const RegisteredPrefixId*
Alexander Afanasyev90164962014-03-06 08:29:59 +0000299 setInterestFilter(const InterestFilter& interestFilter,
Junxiao Shi103d8ed2016-08-07 20:34:10 +0000300 const InterestCallback& onInterest,
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700301 const RegisterPrefixSuccessCallback& onSuccess,
302 const RegisterPrefixFailureCallback& onFailure,
Joao Pereira0b3cac52015-07-02 14:49:49 -0400303 const security::SigningInfo& signingInfo = security::SigningInfo(),
Alexander Afanasyev0866f512014-08-11 13:25:09 -0700304 uint64_t flags = nfd::ROUTE_FLAG_CHILD_INHERIT);
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700305
306 /**
307 * @brief Set InterestFilter to dispatch incoming matching interest to onInterest callback
308 *
309 * @param interestFilter Interest
310 * @param onInterest A callback to be called when a matching interest is received
311 *
312 * This method modifies library's FIB only, and does not register the prefix with the
313 * forwarder. It will always succeed. To register prefix with the forwarder, use
314 * registerPrefix, or use the setInterestFilter overload taking two callbacks.
315 *
316 * @return Opaque interest filter ID which can be used with unsetInterestFilter
317 */
318 const InterestFilterId*
319 setInterestFilter(const InterestFilter& interestFilter,
Junxiao Shi103d8ed2016-08-07 20:34:10 +0000320 const InterestCallback& onInterest);
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700321
Joao Pereira0b3cac52015-07-02 14:49:49 -0400322 /**
323 * @brief Register prefix with the connected NDN forwarder
324 *
325 * This method only modifies forwarder's RIB and does not associate any
326 * onInterest callbacks. Use setInterestFilter method to dispatch incoming Interests to
327 * the right callbacks.
328 *
329 * @param prefix A prefix to register with the connected NDN forwarder
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 signingInfo (optional) Signing parameters. When omitted, a default parameters
333 * used in the signature will be used.
Alexander Afanasyevf2a46222015-09-17 18:01:30 -0700334 * @param flags Prefix registration flags
Joao Pereira0b3cac52015-07-02 14:49:49 -0400335 *
336 * @return The registered prefix ID which can be used with unregisterPrefix
Alexander Afanasyevf2a46222015-09-17 18:01:30 -0700337 * @see nfd::RouteFlags
Joao Pereira0b3cac52015-07-02 14:49:49 -0400338 */
339 const RegisteredPrefixId*
340 registerPrefix(const Name& prefix,
341 const RegisterPrefixSuccessCallback& onSuccess,
342 const RegisterPrefixFailureCallback& onFailure,
343 const security::SigningInfo& signingInfo = security::SigningInfo(),
344 uint64_t flags = nfd::ROUTE_FLAG_CHILD_INHERIT);
345
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700346 /**
Alexander Afanasyev1b01c312014-05-26 16:58:10 +0300347 * @brief Remove the registered prefix entry with the registeredPrefixId
Alexander Afanasyev691c3ce2014-04-23 14:28:04 -0700348 *
349 * This does not affect another registered prefix with a different registeredPrefixId,
350 * even it if has the same prefix name. If there is no entry with the
351 * registeredPrefixId, do nothing.
352 *
Alexander Afanasyevee8bb1e2014-05-02 17:39:54 -0700353 * unsetInterestFilter will use the same credentials as original
354 * setInterestFilter/registerPrefix command
355 *
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700356 * @param registeredPrefixId The ID returned from registerPrefix
Jeff Thompson11095142013-10-01 16:20:28 -0700357 */
358 void
Alexander Afanasyev7682ccb2014-02-20 10:29:35 -0800359 unsetInterestFilter(const RegisteredPrefixId* registeredPrefixId);
Alexander Afanasyeva557d5a2013-12-28 21:59:03 -0800360
Alexander Afanasyevee8bb1e2014-05-02 17:39:54 -0700361 /**
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700362 * @brief Remove previously set InterestFilter from library's FIB
363 *
364 * This method always succeeds and will **NOT** send any request to the connected
365 * forwarder.
366 *
367 * @param interestFilterId The ID returned from setInterestFilter.
368 */
369 void
370 unsetInterestFilter(const InterestFilterId* interestFilterId);
371
372 /**
Joao Pereiraba1e3b92015-06-01 17:50:37 -0400373 * @brief Unregister prefix from RIB
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700374 *
375 * unregisterPrefix will use the same credentials as original
376 * setInterestFilter/registerPrefix command
377 *
378 * If registeredPrefixId was obtained using setInterestFilter, the corresponding
379 * InterestFilter will be unset too.
380 *
Alexander Afanasyev770827c2014-05-13 17:42:55 -0700381 * @param registeredPrefixId The ID returned from registerPrefix
382 * @param onSuccess Callback to be called when operation succeeds
383 * @param onFailure Callback to be called when operation fails
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700384 */
385 void
386 unregisterPrefix(const RegisteredPrefixId* registeredPrefixId,
387 const UnregisterPrefixSuccessCallback& onSuccess,
388 const UnregisterPrefixFailureCallback& onFailure);
389
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800390 /**
Alexander Afanasyeva557d5a2013-12-28 21:59:03 -0800391 * @brief Publish data packet
392 *
Alexander Afanasyev691c3ce2014-04-23 14:28:04 -0700393 * This method can be called to satisfy the incoming Interest or to put Data packet into
Alexander Afanasyev6a05b4b2014-07-18 17:23:00 -0700394 * the cache of the local NDN forwarder.
395 *
396 * @param data Data packet to publish. It is highly recommended to use Data packet that
397 * was created using make_shared<Data>(...). Otherwise, put() will make an
398 * extra copy of the Data packet to ensure validity of published Data until
399 * asynchronous put() operation finishes.
Alexander Afanasyev49bb1fb2014-07-21 12:54:01 -0700400 *
Junxiao Shi103d8ed2016-08-07 20:34:10 +0000401 * @throw Error when Data size exceeds maximum limit (MAX_NDN_PACKET_SIZE)
Alexander Afanasyeva557d5a2013-12-28 21:59:03 -0800402 */
403 void
Alexander Afanasyev7682ccb2014-02-20 10:29:35 -0800404 put(const Data& data);
Alexander Afanasyevfdbfc6d2014-04-14 15:12:11 -0700405
Eric Newberry83872fd2015-08-06 17:01:24 -0700406 /**
407 * @brief sends a Network NACK
408 * @param nack the Nack; a copy will be made, so that the caller is not required to
409 * maintain the argument unchanged
410 */
411 void
412 put(const lp::Nack& nack);
413
Junxiao Shiedd834e2014-10-28 20:28:58 -0700414public: // IO routine
Jeff Thompson86507bc2013-08-23 20:51:38 -0700415 /**
Alexander Afanasyev691c3ce2014-04-23 14:28:04 -0700416 * @brief Process any data to receive or call timeout callbacks.
Alexander Afanasyeva557d5a2013-12-28 21:59:03 -0800417 *
418 * This call will block forever (default timeout == 0) to process IO on the face.
419 * To exit, one expected to call face.shutdown() from one of the callback methods.
420 *
Alexander Afanasyev691c3ce2014-04-23 14:28:04 -0700421 * If positive timeout is specified, then processEvents will exit after this timeout, if
422 * not stopped earlier with face.shutdown() or when all active events finish. The call
423 * can be called repeatedly, if desired.
Alexander Afanasyeva557d5a2013-12-28 21:59:03 -0800424 *
Alexander Afanasyev691c3ce2014-04-23 14:28:04 -0700425 * If negative timeout is specified, then processEvents will not block and process only
426 * pending events.
Alexander Afanasyevf75a0aa2014-01-09 14:29:22 -0800427 *
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700428 * @param timeout maximum time to block the thread
Alexander Afanasyev691c3ce2014-04-23 14:28:04 -0700429 * @param keepThread Keep thread in a blocked state (in event processing), even when
430 * there are no outstanding events (e.g., no Interest/Data is expected)
431 *
432 * @throw This may throw an exception for reading data or in the callback for processing
433 * the data. If you call this from an main event loop, you may want to catch and
434 * log/disregard all exceptions.
Jeff Thompson432c8be2013-08-09 16:16:08 -0700435 */
Alexander Afanasyevfdbfc6d2014-04-14 15:12:11 -0700436 void
Junxiao Shi2ed9e072017-08-13 16:45:48 +0000437 processEvents(time::milliseconds timeout = time::milliseconds::zero(),
Junxiao Shic828dfc2016-09-15 13:26:22 +0000438 bool keepThread = false)
439 {
440 this->doProcessEvents(timeout, keepThread);
441 }
Jeff Thompson432c8be2013-08-09 16:16:08 -0700442
Alexander Afanasyev691c3ce2014-04-23 14:28:04 -0700443 /**
444 * @brief Shutdown face operations
445 *
446 * This method cancels all pending operations and closes connection to NDN Forwarder.
447 *
448 * Note that this method does not stop IO service and if the same IO service is shared
449 * between multiple Faces or with other IO objects (e.g., Scheduler).
450 */
Alexander Afanasyevfdbfc6d2014-04-14 15:12:11 -0700451 void
Jeff Thompson0050abe2013-09-17 12:50:25 -0700452 shutdown();
Yingdi Yu0d920812014-01-30 14:50:57 -0800453
Alexander Afanasyev691c3ce2014-04-23 14:28:04 -0700454 /**
Junxiao Shi103d8ed2016-08-07 20:34:10 +0000455 * @return reference to IO service object
Alexander Afanasyev691c3ce2014-04-23 14:28:04 -0700456 */
457 boost::asio::io_service&
458 getIoService()
459 {
Junxiao Shi2cced062014-11-02 21:27:38 -0700460 return m_ioService;
Alexander Afanasyev691c3ce2014-04-23 14:28:04 -0700461 }
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800462
Alexander Afanasyev3a6da362015-12-29 20:31:03 -0800463NDN_CXX_PUBLIC_WITH_TESTS_ELSE_PROTECTED:
464 /**
Junxiao Shi103d8ed2016-08-07 20:34:10 +0000465 * @return underlying transport
Alexander Afanasyev3a6da362015-12-29 20:31:03 -0800466 */
467 shared_ptr<Transport>
468 getTransport();
469
Junxiao Shic828dfc2016-09-15 13:26:22 +0000470protected:
471 virtual void
Junxiao Shi2ed9e072017-08-13 16:45:48 +0000472 doProcessEvents(time::milliseconds timeout, bool keepThread);
Junxiao Shic828dfc2016-09-15 13:26:22 +0000473
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800474private:
Steve DiBenedettoa8659ff2014-12-04 14:50:28 -0700475 /**
Junxiao Shi103d8ed2016-08-07 20:34:10 +0000476 * @throw ConfigFile::Error on parse error and unsupported protocols
Steve DiBenedettoa8659ff2014-12-04 14:50:28 -0700477 */
Alexander Afanasyevbb64c172015-12-29 20:32:45 -0800478 shared_ptr<Transport>
479 makeDefaultTransport();
Steve DiBenedettoa8659ff2014-12-04 14:50:28 -0700480
Steve DiBenedettoc07b3a22014-03-19 12:32:52 -0600481 /**
Junxiao Shi103d8ed2016-08-07 20:34:10 +0000482 * @throw Face::Error on unsupported protocol
Junxiao Shi2cced062014-11-02 21:27:38 -0700483 * @note shared_ptr is passed by value because ownership is transferred to this function
Steve DiBenedettoc07b3a22014-03-19 12:32:52 -0600484 */
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800485 void
Joao Pereira68c0d882015-05-19 14:27:55 -0400486 construct(shared_ptr<Transport> transport, KeyChain& keyChain);
Steve DiBenedettoc07b3a22014-03-19 12:32:52 -0600487
Alexander Afanasyevfdbfc6d2014-04-14 15:12:11 -0700488 void
Eric Newberry83872fd2015-08-06 17:01:24 -0700489 onReceiveElement(const Block& blockFromDaemon);
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800490
Alexander Afanasyev7dced462014-03-19 15:12:32 -0700491 void
492 asyncShutdown();
Alexander Afanasyevfdbfc6d2014-04-14 15:12:11 -0700493
Jeff Thompsonb982b6d2013-07-15 18:15:45 -0700494private:
Junxiao Shi2cced062014-11-02 21:27:38 -0700495 /// the IO service owned by this Face, could be null
496 unique_ptr<boost::asio::io_service> m_internalIoService;
497 /// the IO service used by this Face
498 boost::asio::io_service& m_ioService;
Alexander Afanasyevfdbfc6d2014-04-14 15:12:11 -0700499
Alexander Afanasyevf39c5372014-02-17 19:42:56 -0800500 shared_ptr<Transport> m_transport;
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800501
Junxiao Shi103d8ed2016-08-07 20:34:10 +0000502 /**
503 * @brief if not null, a pointer to an internal KeyChain owned by Face
504 * @note if a KeyChain is supplied to constructor, this pointer will be null,
505 * and the passed KeyChain is given to nfdController;
506 * currently Face does not keep the KeyChain passed in constructor
507 * because it's not needed, but this may change in the future
Junxiao Shiedd834e2014-10-28 20:28:58 -0700508 */
Joao Pereira68c0d882015-05-19 14:27:55 -0400509 unique_ptr<KeyChain> m_internalKeyChain;
Junxiao Shiedd834e2014-10-28 20:28:58 -0700510
Joao Pereira68c0d882015-05-19 14:27:55 -0400511 unique_ptr<nfd::Controller> m_nfdController;
Steve DiBenedettoc07b3a22014-03-19 12:32:52 -0600512
Alexander Afanasyev258ec2b2014-05-14 16:15:37 -0700513 class Impl;
Junxiao Shiae0b4182016-08-08 22:53:17 +0000514 shared_ptr<Impl> m_impl;
Jeff Thompsonaa4e6db2013-07-15 17:25:23 -0700515};
516
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800517} // namespace ndn
Jeff Thompsonaa4e6db2013-07-15 17:25:23 -0700518
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800519#endif // NDN_FACE_HPP