blob: 23634f14f865058872029b45465479d2626a81cc [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/*
Eric Newberry33063392018-06-23 01:59:36 -07003 * Copyright (C) 2013-2018 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
Junxiao Shib6e276f2017-08-14 20:10:04 +000025#include "data.hpp"
Alexander Afanasyev258ec2b2014-05-14 16:15:37 -070026#include "name.hpp"
Alexander Afanasyev0222fba2014-02-09 23:16:02 -080027#include "interest.hpp"
Alexander Afanasyev258ec2b2014-05-14 16:15:37 -070028#include "interest-filter.hpp"
Junxiao Shi4b469982015-12-03 18:20:19 +000029#include "encoding/nfd-constants.hpp"
Eric Newberry83872fd2015-08-06 17:01:24 -070030#include "lp/nack.hpp"
Davide Pesavento4d0d0962017-12-19 22:23:14 -050031#include "net/asio-fwd.hpp"
Alexander Afanasyev4c9a3d52017-01-03 17:45:19 -080032#include "security/key-chain.hpp"
Junxiao Shib6e276f2017-08-14 20:10:04 +000033#include "security/signing-info.hpp"
Joao Pereira0b3cac52015-07-02 14:49:49 -040034
Jeff Thompsonaa4e6db2013-07-15 17:25:23 -070035namespace ndn {
36
Alexander Afanasyev258ec2b2014-05-14 16:15:37 -070037class Transport;
38
39class PendingInterestId;
40class RegisteredPrefixId;
41class InterestFilterId;
42
Alexander Afanasyevee8bb1e2014-05-02 17:39:54 -070043namespace nfd {
44class Controller;
Alexander Afanasyev8cf1c562016-06-23 16:01:55 -070045} // namespace nfd
Alexander Afanasyevee8bb1e2014-05-02 17:39:54 -070046
Jeff Thompsonfe08e5a2013-08-13 11:15:59 -070047/**
Junxiao Shi103d8ed2016-08-07 20:34:10 +000048 * @brief Callback invoked when expressed Interest gets satisfied with a Data packet
Eric Newberry83872fd2015-08-06 17:01:24 -070049 */
50typedef function<void(const Interest&, const Data&)> DataCallback;
51
52/**
Junxiao Shi103d8ed2016-08-07 20:34:10 +000053 * @brief Callback invoked when Nack is sent in response to expressed Interest
Eric Newberry83872fd2015-08-06 17:01:24 -070054 */
55typedef function<void(const Interest&, const lp::Nack&)> NackCallback;
56
57/**
Junxiao Shi103d8ed2016-08-07 20:34:10 +000058 * @brief Callback invoked when expressed Interest times out
Eric Newberry83872fd2015-08-06 17:01:24 -070059 */
60typedef function<void(const Interest&)> TimeoutCallback;
61
62/**
Junxiao Shi103d8ed2016-08-07 20:34:10 +000063 * @brief Callback invoked when incoming Interest matches the specified InterestFilter
64 */
65typedef function<void(const InterestFilter&, const Interest&)> InterestCallback;
66
67/**
Junxiao Shi103d8ed2016-08-07 20:34:10 +000068 * @brief Callback invoked when registerPrefix or setInterestFilter command succeeds
Alexander Afanasyev0222fba2014-02-09 23:16:02 -080069 */
Alexander Afanasyev984ad192014-05-02 19:11:15 -070070typedef function<void(const Name&)> RegisterPrefixSuccessCallback;
Alexander Afanasyev0222fba2014-02-09 23:16:02 -080071
Alexander Afanasyev984ad192014-05-02 19:11:15 -070072/**
Junxiao Shi103d8ed2016-08-07 20:34:10 +000073 * @brief Callback invoked when registerPrefix or setInterestFilter command fails
Alexander Afanasyev984ad192014-05-02 19:11:15 -070074 */
75typedef function<void(const Name&, const std::string&)> RegisterPrefixFailureCallback;
76
77/**
Junxiao Shi103d8ed2016-08-07 20:34:10 +000078 * @brief Callback invoked when unregisterPrefix or unsetInterestFilter command succeeds
Alexander Afanasyev984ad192014-05-02 19:11:15 -070079 */
80typedef function<void()> UnregisterPrefixSuccessCallback;
81
82/**
Junxiao Shi103d8ed2016-08-07 20:34:10 +000083 * @brief Callback invoked when unregisterPrefix or unsetInterestFilter command fails
Alexander Afanasyev984ad192014-05-02 19:11:15 -070084 */
85typedef function<void(const std::string&)> UnregisterPrefixFailureCallback;
Alexander Afanasyev0222fba2014-02-09 23:16:02 -080086
Alexander Afanasyev0222fba2014-02-09 23:16:02 -080087/**
Junxiao Shi103d8ed2016-08-07 20:34:10 +000088 * @brief Provide a communication channel with local or remote NDN forwarder
Jeff Thompsonfe08e5a2013-08-13 11:15:59 -070089 */
Alexander Afanasyev8460afb2014-02-15 20:31:42 -080090class Face : noncopyable
91{
Jeff Thompsonaa4e6db2013-07-15 17:25:23 -070092public:
Alexander Afanasyevfdbfc6d2014-04-14 15:12:11 -070093 class Error : public std::runtime_error
94 {
95 public:
96 explicit
97 Error(const std::string& what)
98 : std::runtime_error(what)
99 {
100 }
101 };
Alexander Afanasyevb790d952014-01-24 12:07:53 -0800102
Junxiao Shib6e276f2017-08-14 20:10:04 +0000103 /**
104 * @brief Exception thrown when attempting to send a packet over size limit
105 */
106 class OversizedPacketError : public Error
107 {
108 public:
109 /**
110 * @brief Constructor
111 * @param pktType packet type, 'I' for Interest, 'D' for Data, 'N' for Nack
112 * @param name packet name
113 * @param wireSize wire encoding size
114 */
115 OversizedPacketError(char pktType, const Name& name, size_t wireSize);
116
117 public:
118 const char pktType;
119 const Name name;
120 const size_t wireSize;
121 };
122
Junxiao Shiedd834e2014-10-28 20:28:58 -0700123public: // constructors
Alexander Afanasyevb790d952014-01-24 12:07:53 -0800124 /**
Junxiao Shi103d8ed2016-08-07 20:34:10 +0000125 * @brief Create Face using given transport (or default transport if omitted)
126 * @param transport the transport for lower layer communication. If nullptr,
127 * a default transport will be used. The default transport is
128 * determined from a FaceUri in NDN_CLIENT_TRANSPORT environ,
129 * a FaceUri in configuration file 'transport' key, or UnixTransport.
Alexander Afanasyev691c3ce2014-04-23 14:28:04 -0700130 *
Junxiao Shib6e276f2017-08-14 20:10:04 +0000131 * @throw ConfigFile::Error @p transport is nullptr, and the configuration file cannot be
Junxiao Shi103d8ed2016-08-07 20:34:10 +0000132 * parsed or specifies an unsupported protocol
133 * @note shared_ptr is passed by value because ownership is shared with this class
Alexander Afanasyevb790d952014-01-24 12:07:53 -0800134 */
Junxiao Shi103d8ed2016-08-07 20:34:10 +0000135 explicit
136 Face(shared_ptr<Transport> transport = nullptr);
Alexander Afanasyeve2e0d752014-01-03 13:30:30 -0800137
138 /**
Junxiao Shi103d8ed2016-08-07 20:34:10 +0000139 * @brief Create Face using default transport and given io_service
Alexander Afanasyev691c3ce2014-04-23 14:28:04 -0700140 *
Junxiao Shi103d8ed2016-08-07 20:34:10 +0000141 * Usage examples:
Alexander Afanasyev691c3ce2014-04-23 14:28:04 -0700142 *
Junxiao Shi103d8ed2016-08-07 20:34:10 +0000143 * @code
144 * Face face1;
145 * Face face2(face1.getIoService());
Alexander Afanasyev691c3ce2014-04-23 14:28:04 -0700146 *
Junxiao Shi103d8ed2016-08-07 20:34:10 +0000147 * // Now the following ensures that events on both faces are processed
148 * face1.processEvents();
149 * // or face1.getIoService().run();
150 * @endcode
Alexander Afanasyev691c3ce2014-04-23 14:28:04 -0700151 *
Junxiao Shi103d8ed2016-08-07 20:34:10 +0000152 * or
Alexander Afanasyev691c3ce2014-04-23 14:28:04 -0700153 *
Junxiao Shi103d8ed2016-08-07 20:34:10 +0000154 * @code
155 * boost::asio::io_service ioService;
156 * Face face1(ioService);
157 * Face face2(ioService);
Alexander Afanasyev691c3ce2014-04-23 14:28:04 -0700158 *
Junxiao Shi103d8ed2016-08-07 20:34:10 +0000159 * ioService.run();
160 * @endcode
Alexander Afanasyev691c3ce2014-04-23 14:28:04 -0700161 *
162 * @param ioService A reference to boost::io_service object that should control all
163 * IO operations.
Junxiao Shi103d8ed2016-08-07 20:34:10 +0000164 * @throw ConfigFile::Error the configuration file cannot be parsed or specifies an unsupported protocol
Alexander Afanasyev691c3ce2014-04-23 14:28:04 -0700165 */
166 explicit
167 Face(boost::asio::io_service& ioService);
168
169 /**
Junxiao Shi103d8ed2016-08-07 20:34:10 +0000170 * @brief Create Face using TcpTransport
Alexander Afanasyev691c3ce2014-04-23 14:28:04 -0700171 *
Junxiao Shi103d8ed2016-08-07 20:34:10 +0000172 * @param host IP address or hostname of the NDN forwarder
173 * @param port port number or service name of the NDN forwarder (**default**: "6363")
Jeff Thompsonfe08e5a2013-08-13 11:15:59 -0700174 */
Junxiao Shiae0b4182016-08-08 22:53:17 +0000175 explicit
Alexander Afanasyev7682ccb2014-02-20 10:29:35 -0800176 Face(const std::string& host, const std::string& port = "6363");
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800177
178 /**
Junxiao Shi103d8ed2016-08-07 20:34:10 +0000179 * @brief Create Face using given transport and KeyChain
180 * @param transport the transport for lower layer communication. If nullptr,
181 * a default transport will be used.
Alexander Afanasyev8cf1c562016-06-23 16:01:55 -0700182 * @param keyChain the KeyChain to sign commands
183 *
Junxiao Shi103d8ed2016-08-07 20:34:10 +0000184 * @sa Face(shared_ptr<Transport>)
185 *
Junxiao Shib6e276f2017-08-14 20:10:04 +0000186 * @throw ConfigFile::Error @p transport is nullptr, and the configuration file cannot be
Junxiao Shi103d8ed2016-08-07 20:34:10 +0000187 * parsed or specifies an unsupported protocol
Alexander Afanasyev8cf1c562016-06-23 16:01:55 -0700188 * @note shared_ptr is passed by value because ownership is shared with this class
189 */
190 Face(shared_ptr<Transport> transport, KeyChain& keyChain);
191
192 /**
Eric Newberry33063392018-06-23 01:59:36 -0700193 * @brief Create Face using given transport and io_service
Junxiao Shi103d8ed2016-08-07 20:34:10 +0000194 * @param transport the transport for lower layer communication. If nullptr,
195 * a default transport will be used.
Alexander Afanasyevbb64c172015-12-29 20:32:45 -0800196 * @param ioService the io_service that controls all IO operations
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800197 *
Alexander Afanasyev691c3ce2014-04-23 14:28:04 -0700198 * @sa Face(boost::asio::io_service&)
Junxiao Shi103d8ed2016-08-07 20:34:10 +0000199 * @sa Face(shared_ptr<Transport>)
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800200 *
Junxiao Shib6e276f2017-08-14 20:10:04 +0000201 * @throw ConfigFile::Error @p transport is nullptr, and the configuration file cannot be
Junxiao Shi103d8ed2016-08-07 20:34:10 +0000202 * parsed or specifies an unsupported protocol
Alexander Afanasyev8cf1c562016-06-23 16:01:55 -0700203 * @note shared_ptr is passed by value because ownership is shared with this class
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800204 */
Alexander Afanasyev8cf1c562016-06-23 16:01:55 -0700205 Face(shared_ptr<Transport> transport, boost::asio::io_service& ioService);
Alexander Afanasyev7682ccb2014-02-20 10:29:35 -0800206
Jeff Thompson4fe45512013-08-23 14:06:38 -0700207 /**
Eric Newberry33063392018-06-23 01:59:36 -0700208 * @brief Create a new Face using given Transport and io_service
Junxiao Shi103d8ed2016-08-07 20:34:10 +0000209 * @param transport the transport for lower layer communication. If nullptr,
210 * a default transport will be used.
Junxiao Shiedd834e2014-10-28 20:28:58 -0700211 * @param ioService the io_service that controls all IO operations
212 * @param keyChain the KeyChain to sign commands
Alexander Afanasyev8cf1c562016-06-23 16:01:55 -0700213 *
Junxiao Shi103d8ed2016-08-07 20:34:10 +0000214 * @sa Face(boost::asio::io_service&)
215 * @sa Face(shared_ptr<Transport>, KeyChain&)
216 *
Junxiao Shib6e276f2017-08-14 20:10:04 +0000217 * @throw ConfigFile::Error @p transport is nullptr, and the configuration file cannot be
Junxiao Shi103d8ed2016-08-07 20:34:10 +0000218 * parsed or specifies an unsupported protocol
Junxiao Shiedd834e2014-10-28 20:28:58 -0700219 * @note shared_ptr is passed by value because ownership is shared with this class
220 */
Alexander Afanasyev8cf1c562016-06-23 16:01:55 -0700221 Face(shared_ptr<Transport> transport, boost::asio::io_service& ioService, KeyChain& keyChain);
Junxiao Shiedd834e2014-10-28 20:28:58 -0700222
Davide Pesavento7f20d6e2017-01-16 14:43:58 -0500223 virtual
Junxiao Shiedd834e2014-10-28 20:28:58 -0700224 ~Face();
225
226public: // consumer
227 /**
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800228 * @brief Express Interest
Eric Newberry83872fd2015-08-06 17:01:24 -0700229 * @param interest the Interest; a copy will be made, so that the caller is not
230 * required to maintain the argument unchanged
231 * @param afterSatisfied function to be invoked if Data is returned
232 * @param afterNacked function to be invoked if Network NACK is returned
233 * @param afterTimeout function to be invoked if neither Data nor Network NACK
234 * is returned within InterestLifetime
Junxiao Shib6e276f2017-08-14 20:10:04 +0000235 * @throw OversizedPacketError encoded Interest size exceeds MAX_NDN_PACKET_SIZE
Eric Newberry83872fd2015-08-06 17:01:24 -0700236 */
237 const PendingInterestId*
238 expressInterest(const Interest& interest,
239 const DataCallback& afterSatisfied,
240 const NackCallback& afterNacked,
241 const TimeoutCallback& afterTimeout);
242
243 /**
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700244 * @brief Cancel previously expressed Interest
Alexander Afanasyev691c3ce2014-04-23 14:28:04 -0700245 *
Jeff Thompson11095142013-10-01 16:20:28 -0700246 * @param pendingInterestId The ID returned from expressInterest.
247 */
248 void
Alexander Afanasyev7682ccb2014-02-20 10:29:35 -0800249 removePendingInterest(const PendingInterestId* pendingInterestId);
Alexander Afanasyevfdbfc6d2014-04-14 15:12:11 -0700250
Jeff Thompson432c8be2013-08-09 16:16:08 -0700251 /**
Ilya Moiseenko56b0bf82015-11-08 11:14:28 -0500252 * @brief Cancel all previously expressed Interests
253 */
254 void
255 removeAllPendingInterests();
256
257 /**
Alexander Afanasyev6fcdde22014-08-22 19:03:36 -0700258 * @brief Get number of pending Interests
259 */
260 size_t
261 getNPendingInterests() const;
262
Junxiao Shiedd834e2014-10-28 20:28:58 -0700263public: // producer
Alexander Afanasyev6fcdde22014-08-22 19:03:36 -0700264 /**
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700265 * @brief Set InterestFilter to dispatch incoming matching interest to onInterest
266 * callback and register the filtered prefix with the connected NDN forwarder
267 *
268 * This version of setInterestFilter combines setInterestFilter and registerPrefix
269 * operations and is intended to be used when only one filter for the same prefix needed
270 * to be set. When multiple names sharing the same prefix should be dispatched to
271 * different callbacks, use one registerPrefix call, followed (in onSuccess callback) by
272 * a series of setInterestFilter calls.
Alexander Afanasyev691c3ce2014-04-23 14:28:04 -0700273 *
Alexander Afanasyev90164962014-03-06 08:29:59 +0000274 * @param interestFilter Interest filter (prefix part will be registered with the forwarder)
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700275 * @param onInterest A callback to be called when a matching interest is received
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700276 * @param onFailure A callback to be called when prefixRegister command fails
Joao Pereiraba1e3b92015-06-01 17:50:37 -0400277 * @param flags (optional) RIB flags
Joao Pereira0b3cac52015-07-02 14:49:49 -0400278 * @param signingInfo (optional) Signing parameters. When omitted, a default parameters
279 * used in the signature will be used.
Alexander Afanasyev691c3ce2014-04-23 14:28:04 -0700280 *
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700281 * @return Opaque registered prefix ID which can be used with unsetInterestFilter or
282 * removeRegisteredPrefix
Yingdi Yue66bf2a2014-04-28 17:07:36 -0700283 */
284 const RegisteredPrefixId*
Alexander Afanasyev90164962014-03-06 08:29:59 +0000285 setInterestFilter(const InterestFilter& interestFilter,
Junxiao Shi103d8ed2016-08-07 20:34:10 +0000286 const InterestCallback& onInterest,
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700287 const RegisterPrefixFailureCallback& onFailure,
Joao Pereira0b3cac52015-07-02 14:49:49 -0400288 const security::SigningInfo& signingInfo = security::SigningInfo(),
Alexander Afanasyev0866f512014-08-11 13:25:09 -0700289 uint64_t flags = nfd::ROUTE_FLAG_CHILD_INHERIT);
Yingdi Yue66bf2a2014-04-28 17:07:36 -0700290
291 /**
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700292 * @brief Set InterestFilter to dispatch incoming matching interest to onInterest
293 * callback and register the filtered prefix with the connected NDN forwarder
294 *
295 * This version of setInterestFilter combines setInterestFilter and registerPrefix
296 * operations and is intended to be used when only one filter for the same prefix needed
297 * to be set. When multiple names sharing the same prefix should be dispatched to
298 * different callbacks, use one registerPrefix call, followed (in onSuccess callback) by
299 * a series of setInterestFilter calls.
Yingdi Yue66bf2a2014-04-28 17:07:36 -0700300 *
Alexander Afanasyev90164962014-03-06 08:29:59 +0000301 * @param interestFilter Interest filter (prefix part will be registered with the forwarder)
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700302 * @param onInterest A callback to be called when a matching interest is received
303 * @param onSuccess A callback to be called when prefixRegister command succeeds
304 * @param onFailure A callback to be called when prefixRegister command fails
Joao Pereiraba1e3b92015-06-01 17:50:37 -0400305 * @param flags (optional) RIB flags
Joao Pereira0b3cac52015-07-02 14:49:49 -0400306 * @param signingInfo (optional) Signing parameters. When omitted, a default parameters
307 * used in the signature will be used.
Yingdi Yue66bf2a2014-04-28 17:07:36 -0700308 *
Joao Pereira0b3cac52015-07-02 14:49:49 -0400309 * @return Opaque registered prefix ID which can be used with unsetInterestFilter or
310 * removeRegisteredPrefix
Yingdi Yue66bf2a2014-04-28 17:07:36 -0700311 */
312 const RegisteredPrefixId*
Alexander Afanasyev90164962014-03-06 08:29:59 +0000313 setInterestFilter(const InterestFilter& interestFilter,
Junxiao Shi103d8ed2016-08-07 20:34:10 +0000314 const InterestCallback& onInterest,
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700315 const RegisterPrefixSuccessCallback& onSuccess,
316 const RegisterPrefixFailureCallback& onFailure,
Joao Pereira0b3cac52015-07-02 14:49:49 -0400317 const security::SigningInfo& signingInfo = security::SigningInfo(),
Alexander Afanasyev0866f512014-08-11 13:25:09 -0700318 uint64_t flags = nfd::ROUTE_FLAG_CHILD_INHERIT);
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700319
320 /**
321 * @brief Set InterestFilter to dispatch incoming matching interest to onInterest callback
322 *
323 * @param interestFilter Interest
324 * @param onInterest A callback to be called when a matching interest is received
325 *
326 * This method modifies library's FIB only, and does not register the prefix with the
327 * forwarder. It will always succeed. To register prefix with the forwarder, use
328 * registerPrefix, or use the setInterestFilter overload taking two callbacks.
329 *
330 * @return Opaque interest filter ID which can be used with unsetInterestFilter
331 */
332 const InterestFilterId*
333 setInterestFilter(const InterestFilter& interestFilter,
Junxiao Shi103d8ed2016-08-07 20:34:10 +0000334 const InterestCallback& onInterest);
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700335
Joao Pereira0b3cac52015-07-02 14:49:49 -0400336 /**
337 * @brief Register prefix with the connected NDN forwarder
338 *
339 * This method only modifies forwarder's RIB and does not associate any
340 * onInterest callbacks. Use setInterestFilter method to dispatch incoming Interests to
341 * the right callbacks.
342 *
343 * @param prefix A prefix to register with the connected NDN forwarder
344 * @param onSuccess A callback to be called when prefixRegister command succeeds
345 * @param onFailure A callback to be called when prefixRegister command fails
346 * @param signingInfo (optional) Signing parameters. When omitted, a default parameters
347 * used in the signature will be used.
Alexander Afanasyevf2a46222015-09-17 18:01:30 -0700348 * @param flags Prefix registration flags
Joao Pereira0b3cac52015-07-02 14:49:49 -0400349 *
350 * @return The registered prefix ID which can be used with unregisterPrefix
Alexander Afanasyevf2a46222015-09-17 18:01:30 -0700351 * @see nfd::RouteFlags
Joao Pereira0b3cac52015-07-02 14:49:49 -0400352 */
353 const RegisteredPrefixId*
354 registerPrefix(const Name& prefix,
355 const RegisterPrefixSuccessCallback& onSuccess,
356 const RegisterPrefixFailureCallback& onFailure,
357 const security::SigningInfo& signingInfo = security::SigningInfo(),
358 uint64_t flags = nfd::ROUTE_FLAG_CHILD_INHERIT);
359
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700360 /**
Alexander Afanasyev1b01c312014-05-26 16:58:10 +0300361 * @brief Remove the registered prefix entry with the registeredPrefixId
Alexander Afanasyev691c3ce2014-04-23 14:28:04 -0700362 *
363 * This does not affect another registered prefix with a different registeredPrefixId,
364 * even it if has the same prefix name. If there is no entry with the
365 * registeredPrefixId, do nothing.
366 *
Alexander Afanasyevee8bb1e2014-05-02 17:39:54 -0700367 * unsetInterestFilter will use the same credentials as original
368 * setInterestFilter/registerPrefix command
369 *
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700370 * @param registeredPrefixId The ID returned from registerPrefix
Jeff Thompson11095142013-10-01 16:20:28 -0700371 */
372 void
Alexander Afanasyev7682ccb2014-02-20 10:29:35 -0800373 unsetInterestFilter(const RegisteredPrefixId* registeredPrefixId);
Alexander Afanasyeva557d5a2013-12-28 21:59:03 -0800374
Alexander Afanasyevee8bb1e2014-05-02 17:39:54 -0700375 /**
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700376 * @brief Remove previously set InterestFilter from library's FIB
377 *
378 * This method always succeeds and will **NOT** send any request to the connected
379 * forwarder.
380 *
381 * @param interestFilterId The ID returned from setInterestFilter.
382 */
383 void
384 unsetInterestFilter(const InterestFilterId* interestFilterId);
385
386 /**
Joao Pereiraba1e3b92015-06-01 17:50:37 -0400387 * @brief Unregister prefix from RIB
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700388 *
389 * unregisterPrefix will use the same credentials as original
390 * setInterestFilter/registerPrefix command
391 *
392 * If registeredPrefixId was obtained using setInterestFilter, the corresponding
393 * InterestFilter will be unset too.
394 *
Alexander Afanasyev770827c2014-05-13 17:42:55 -0700395 * @param registeredPrefixId The ID returned from registerPrefix
396 * @param onSuccess Callback to be called when operation succeeds
397 * @param onFailure Callback to be called when operation fails
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700398 */
399 void
400 unregisterPrefix(const RegisteredPrefixId* registeredPrefixId,
401 const UnregisterPrefixSuccessCallback& onSuccess,
402 const UnregisterPrefixFailureCallback& onFailure);
403
Junxiao Shib6e276f2017-08-14 20:10:04 +0000404 /**
Alexander Afanasyeva557d5a2013-12-28 21:59:03 -0800405 * @brief Publish data packet
Junxiao Shib6e276f2017-08-14 20:10:04 +0000406 * @param data the Data; a copy will be made, so that the caller is not required to
407 * maintain the argument unchanged
Alexander Afanasyeva557d5a2013-12-28 21:59:03 -0800408 *
Junxiao Shib6e276f2017-08-14 20:10:04 +0000409 * This method can be called to satisfy incoming Interests, or to add Data packet into the cache
410 * of the local NDN forwarder if forwarder is configured to accept unsolicited Data.
Alexander Afanasyev6a05b4b2014-07-18 17:23:00 -0700411 *
Junxiao Shib6e276f2017-08-14 20:10:04 +0000412 * @throw OversizedPacketError encoded Data size exceeds MAX_NDN_PACKET_SIZE
Alexander Afanasyeva557d5a2013-12-28 21:59:03 -0800413 */
414 void
Junxiao Shib6e276f2017-08-14 20:10:04 +0000415 put(Data data);
Alexander Afanasyevfdbfc6d2014-04-14 15:12:11 -0700416
Eric Newberry83872fd2015-08-06 17:01:24 -0700417 /**
Junxiao Shib6e276f2017-08-14 20:10:04 +0000418 * @brief Send a network NACK
Eric Newberry83872fd2015-08-06 17:01:24 -0700419 * @param nack the Nack; a copy will be made, so that the caller is not required to
420 * maintain the argument unchanged
Junxiao Shib6e276f2017-08-14 20:10:04 +0000421 * @throw OversizedPacketError encoded Nack size exceeds MAX_NDN_PACKET_SIZE
Eric Newberry83872fd2015-08-06 17:01:24 -0700422 */
423 void
Junxiao Shib6e276f2017-08-14 20:10:04 +0000424 put(lp::Nack nack);
Eric Newberry83872fd2015-08-06 17:01:24 -0700425
Junxiao Shiedd834e2014-10-28 20:28:58 -0700426public: // IO routine
Jeff Thompson86507bc2013-08-23 20:51:38 -0700427 /**
Alexander Afanasyev691c3ce2014-04-23 14:28:04 -0700428 * @brief Process any data to receive or call timeout callbacks.
Alexander Afanasyeva557d5a2013-12-28 21:59:03 -0800429 *
430 * This call will block forever (default timeout == 0) to process IO on the face.
Eric Newberry33063392018-06-23 01:59:36 -0700431 * To exit cleanly on a producer, unset any Interest filters with unsetInterestFilter() and wait
432 * for processEvents() to return. To exit after an error, one can call shutdown().
433 * In consumer applications, processEvents() will return when all expressed Interests have been
434 * satisfied, Nacked, or timed out. To terminate earlier, a consumer application should call
435 * removePendingInterests() for all previously expressed and still-pending Interests.
Alexander Afanasyeva557d5a2013-12-28 21:59:03 -0800436 *
Eric Newberry33063392018-06-23 01:59:36 -0700437 * If a positive timeout is specified, then processEvents() will exit after this timeout, provided
438 * it is not stopped earlier with shutdown() or when all active events finish. processEvents()
Alexander Afanasyev691c3ce2014-04-23 14:28:04 -0700439 * can be called repeatedly, if desired.
Alexander Afanasyeva557d5a2013-12-28 21:59:03 -0800440 *
Eric Newberry33063392018-06-23 01:59:36 -0700441 * If a negative timeout is specified, then processEvents will not block and will process only
Alexander Afanasyev691c3ce2014-04-23 14:28:04 -0700442 * pending events.
Alexander Afanasyevf75a0aa2014-01-09 14:29:22 -0800443 *
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700444 * @param timeout maximum time to block the thread
Alexander Afanasyev691c3ce2014-04-23 14:28:04 -0700445 * @param keepThread Keep thread in a blocked state (in event processing), even when
Eric Newberry33063392018-06-23 01:59:36 -0700446 * there are no outstanding events (e.g., no Interest/Data is expected).
447 * If timeout is zero and this parameter is true, the only way to stop
448 * processEvents() is to call shutdown().
Alexander Afanasyev691c3ce2014-04-23 14:28:04 -0700449 *
Junxiao Shib6e276f2017-08-14 20:10:04 +0000450 * @note This may throw an exception for reading data or in the callback for processing
Alexander Afanasyev691c3ce2014-04-23 14:28:04 -0700451 * the data. If you call this from an main event loop, you may want to catch and
452 * log/disregard all exceptions.
Junxiao Shib6e276f2017-08-14 20:10:04 +0000453 *
454 * @throw OversizedPacketError encoded packet size exceeds MAX_NDN_PACKET_SIZE
Jeff Thompson432c8be2013-08-09 16:16:08 -0700455 */
Alexander Afanasyevfdbfc6d2014-04-14 15:12:11 -0700456 void
Junxiao Shi2ed9e072017-08-13 16:45:48 +0000457 processEvents(time::milliseconds timeout = time::milliseconds::zero(),
Junxiao Shic828dfc2016-09-15 13:26:22 +0000458 bool keepThread = false)
459 {
460 this->doProcessEvents(timeout, keepThread);
461 }
Jeff Thompson432c8be2013-08-09 16:16:08 -0700462
Alexander Afanasyev691c3ce2014-04-23 14:28:04 -0700463 /**
464 * @brief Shutdown face operations
465 *
466 * This method cancels all pending operations and closes connection to NDN Forwarder.
467 *
Eric Newberry33063392018-06-23 01:59:36 -0700468 * Note that this method does not stop the io_service if it is shared between multiple Faces or
469 * with other IO objects (e.g., Scheduler).
470 *
471 * @warning Calling this method could cause outgoing packets to be lost. Producers that shut down
472 * immediately after sending a Data packet should instead use unsetInterestFilter() to
473 * shut down cleanly.
Alexander Afanasyev691c3ce2014-04-23 14:28:04 -0700474 */
Alexander Afanasyevfdbfc6d2014-04-14 15:12:11 -0700475 void
Jeff Thompson0050abe2013-09-17 12:50:25 -0700476 shutdown();
Yingdi Yu0d920812014-01-30 14:50:57 -0800477
Alexander Afanasyev691c3ce2014-04-23 14:28:04 -0700478 /**
Eric Newberry33063392018-06-23 01:59:36 -0700479 * @return reference to io_service object
Alexander Afanasyev691c3ce2014-04-23 14:28:04 -0700480 */
481 boost::asio::io_service&
482 getIoService()
483 {
Junxiao Shi2cced062014-11-02 21:27:38 -0700484 return m_ioService;
Alexander Afanasyev691c3ce2014-04-23 14:28:04 -0700485 }
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800486
Alexander Afanasyev3a6da362015-12-29 20:31:03 -0800487NDN_CXX_PUBLIC_WITH_TESTS_ELSE_PROTECTED:
488 /**
Junxiao Shi103d8ed2016-08-07 20:34:10 +0000489 * @return underlying transport
Alexander Afanasyev3a6da362015-12-29 20:31:03 -0800490 */
491 shared_ptr<Transport>
492 getTransport();
493
Junxiao Shic828dfc2016-09-15 13:26:22 +0000494protected:
495 virtual void
Junxiao Shi2ed9e072017-08-13 16:45:48 +0000496 doProcessEvents(time::milliseconds timeout, bool keepThread);
Junxiao Shic828dfc2016-09-15 13:26:22 +0000497
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800498private:
Steve DiBenedettoa8659ff2014-12-04 14:50:28 -0700499 /**
Junxiao Shi103d8ed2016-08-07 20:34:10 +0000500 * @throw ConfigFile::Error on parse error and unsupported protocols
Steve DiBenedettoa8659ff2014-12-04 14:50:28 -0700501 */
Alexander Afanasyevbb64c172015-12-29 20:32:45 -0800502 shared_ptr<Transport>
503 makeDefaultTransport();
Steve DiBenedettoa8659ff2014-12-04 14:50:28 -0700504
Steve DiBenedettoc07b3a22014-03-19 12:32:52 -0600505 /**
Junxiao Shi103d8ed2016-08-07 20:34:10 +0000506 * @throw Face::Error on unsupported protocol
Junxiao Shi2cced062014-11-02 21:27:38 -0700507 * @note shared_ptr is passed by value because ownership is transferred to this function
Steve DiBenedettoc07b3a22014-03-19 12:32:52 -0600508 */
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800509 void
Joao Pereira68c0d882015-05-19 14:27:55 -0400510 construct(shared_ptr<Transport> transport, KeyChain& keyChain);
Steve DiBenedettoc07b3a22014-03-19 12:32:52 -0600511
Alexander Afanasyevfdbfc6d2014-04-14 15:12:11 -0700512 void
Eric Newberry83872fd2015-08-06 17:01:24 -0700513 onReceiveElement(const Block& blockFromDaemon);
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800514
Alexander Afanasyev7dced462014-03-19 15:12:32 -0700515 void
516 asyncShutdown();
Alexander Afanasyevfdbfc6d2014-04-14 15:12:11 -0700517
Jeff Thompsonb982b6d2013-07-15 18:15:45 -0700518private:
Eric Newberry33063392018-06-23 01:59:36 -0700519 /// the io_service owned by this Face, could be null
Junxiao Shi2cced062014-11-02 21:27:38 -0700520 unique_ptr<boost::asio::io_service> m_internalIoService;
Eric Newberry33063392018-06-23 01:59:36 -0700521 /// the io_service used by this Face
Junxiao Shi2cced062014-11-02 21:27:38 -0700522 boost::asio::io_service& m_ioService;
Alexander Afanasyevfdbfc6d2014-04-14 15:12:11 -0700523
Alexander Afanasyevf39c5372014-02-17 19:42:56 -0800524 shared_ptr<Transport> m_transport;
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800525
Junxiao Shi103d8ed2016-08-07 20:34:10 +0000526 /**
527 * @brief if not null, a pointer to an internal KeyChain owned by Face
528 * @note if a KeyChain is supplied to constructor, this pointer will be null,
529 * and the passed KeyChain is given to nfdController;
530 * currently Face does not keep the KeyChain passed in constructor
531 * because it's not needed, but this may change in the future
Junxiao Shiedd834e2014-10-28 20:28:58 -0700532 */
Joao Pereira68c0d882015-05-19 14:27:55 -0400533 unique_ptr<KeyChain> m_internalKeyChain;
Junxiao Shiedd834e2014-10-28 20:28:58 -0700534
Joao Pereira68c0d882015-05-19 14:27:55 -0400535 unique_ptr<nfd::Controller> m_nfdController;
Steve DiBenedettoc07b3a22014-03-19 12:32:52 -0600536
Alexander Afanasyev258ec2b2014-05-14 16:15:37 -0700537 class Impl;
Junxiao Shiae0b4182016-08-08 22:53:17 +0000538 shared_ptr<Impl> m_impl;
Jeff Thompsonaa4e6db2013-07-15 17:25:23 -0700539};
540
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800541} // namespace ndn
Jeff Thompsonaa4e6db2013-07-15 17:25:23 -0700542
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800543#endif // NDN_FACE_HPP