blob: 2d76773cfc6eeacbc1a1c34cba4b00319eea75ca [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"
Alexander Afanasyev984ad192014-05-02 19:11:15 -070031#include "security/identity-certificate.hpp"
Alexander Afanasyev0222fba2014-02-09 23:16:02 -080032
Alexander Afanasyev258ec2b2014-05-14 16:15:37 -070033namespace boost {
34namespace asio {
35class io_service;
36}
37}
Alexander Afanasyev0222fba2014-02-09 23:16:02 -080038
Jeff Thompsonaa4e6db2013-07-15 17:25:23 -070039namespace ndn {
40
Alexander Afanasyev258ec2b2014-05-14 16:15:37 -070041class Transport;
42
43class PendingInterestId;
44class RegisteredPrefixId;
45class InterestFilterId;
46
Yingdi Yu1b0311c2015-06-10 14:58:47 -070047namespace security {
48class KeyChain;
49}
50using security::KeyChain;
51
Alexander Afanasyevee8bb1e2014-05-02 17:39:54 -070052namespace nfd {
53class Controller;
54}
Alexander Afanasyevee8bb1e2014-05-02 17:39:54 -070055
Jeff Thompsonfe08e5a2013-08-13 11:15:59 -070056/**
Alexander Afanasyev984ad192014-05-02 19:11:15 -070057 * @brief Callback called when expressed Interest gets satisfied with Data packet
Alexander Afanasyev0222fba2014-02-09 23:16:02 -080058 */
59typedef function<void(const Interest&, Data&)> OnData;
60
61/**
Alexander Afanasyev984ad192014-05-02 19:11:15 -070062 * @brief Callback called when expressed Interest times out
Alexander Afanasyev0222fba2014-02-09 23:16:02 -080063 */
64typedef function<void(const Interest&)> OnTimeout;
65
66/**
Alexander Afanasyev984ad192014-05-02 19:11:15 -070067 * @brief Callback called when incoming Interest matches the specified InterestFilter
Alexander Afanasyev0222fba2014-02-09 23:16:02 -080068 */
Alexander Afanasyev90164962014-03-06 08:29:59 +000069typedef function<void (const InterestFilter&, const Interest&)> OnInterest;
Alexander Afanasyev0222fba2014-02-09 23:16:02 -080070
71/**
Alexander Afanasyev984ad192014-05-02 19:11:15 -070072 * @brief Callback called when registerPrefix or setInterestFilter command succeeds
Alexander Afanasyev0222fba2014-02-09 23:16:02 -080073 */
Alexander Afanasyev984ad192014-05-02 19:11:15 -070074typedef function<void(const Name&)> RegisterPrefixSuccessCallback;
Alexander Afanasyev0222fba2014-02-09 23:16:02 -080075
Alexander Afanasyev984ad192014-05-02 19:11:15 -070076/**
77 * @brief Callback called when registerPrefix or setInterestFilter command fails
78 */
79typedef function<void(const Name&, const std::string&)> RegisterPrefixFailureCallback;
80
81/**
82 * @brief Callback called when unregisterPrefix or unsetInterestFilter command succeeds
83 */
84typedef function<void()> UnregisterPrefixSuccessCallback;
85
86/**
87 * @brief Callback called when unregisterPrefix or unsetInterestFilter command fails
88 */
89typedef function<void(const std::string&)> UnregisterPrefixFailureCallback;
Alexander Afanasyev0222fba2014-02-09 23:16:02 -080090
91
92/**
93 * @brief Abstraction to communicate with local or remote NDN forwarder
Jeff Thompsonfe08e5a2013-08-13 11:15:59 -070094 */
Alexander Afanasyev8460afb2014-02-15 20:31:42 -080095class Face : noncopyable
96{
Jeff Thompsonaa4e6db2013-07-15 17:25:23 -070097public:
Alexander Afanasyevfdbfc6d2014-04-14 15:12:11 -070098 class Error : public std::runtime_error
99 {
100 public:
101 explicit
102 Error(const std::string& what)
103 : std::runtime_error(what)
104 {
105 }
106 };
Alexander Afanasyevb790d952014-01-24 12:07:53 -0800107
Junxiao Shiedd834e2014-10-28 20:28:58 -0700108public: // constructors
Alexander Afanasyevb790d952014-01-24 12:07:53 -0800109 /**
Alexander Afanasyev691c3ce2014-04-23 14:28:04 -0700110 * @brief Create a new Face using the default transport (UnixTransport)
111 *
Steve DiBenedettoc07b3a22014-03-19 12:32:52 -0600112 * @throws ConfigFile::Error on configuration file parse failure
113 * @throws Face::Error on unsupported protocol
Alexander Afanasyevb790d952014-01-24 12:07:53 -0800114 */
Alexander Afanasyevf7ca3202014-02-14 22:28:31 -0800115 Face();
Alexander Afanasyeve2e0d752014-01-03 13:30:30 -0800116
117 /**
Alexander Afanasyev691c3ce2014-04-23 14:28:04 -0700118 * @brief Create a new Face using the default transport (UnixTransport)
119 *
Alexander Afanasyev691c3ce2014-04-23 14:28:04 -0700120 * @par Usage examples:
121 *
122 * Face face1;
123 * Face face2(face1.getIoService());
124 *
125 * // Now the following ensures that events on both faces are processed
126 * face1.processEvents();
127 * // or face1.getIoService().run();
128 *
129 * @par or
130 *
131 * boost::asio::io_service ioService;
132 * Face face1(ioService);
133 * Face face2(ioService);
134 * ...
135 *
136 * ioService.run();
137 *
138 * @param ioService A reference to boost::io_service object that should control all
139 * IO operations.
140 * @throws ConfigFile::Error on configuration file parse failure
141 * @throws Face::Error on unsupported protocol
142 */
143 explicit
144 Face(boost::asio::io_service& ioService);
145
146 /**
147 * @brief Create a new Face using TcpTransport
148 *
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700149 * @param host The host of the NDN forwarder
150 * @param port (optional) The port or service name of the NDN forwarder (**default**: "6363")
151 *
Steve DiBenedettoc07b3a22014-03-19 12:32:52 -0600152 * @throws Face::Error on unsupported protocol
Jeff Thompsonfe08e5a2013-08-13 11:15:59 -0700153 */
Alexander Afanasyev7682ccb2014-02-20 10:29:35 -0800154 Face(const std::string& host, const std::string& port = "6363");
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800155
156 /**
Alexander Afanasyev691c3ce2014-04-23 14:28:04 -0700157 * @brief Create a new Face using the given Transport
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700158 *
159 * @param transport A shared_ptr to a Transport object used for communication
160 *
Steve DiBenedettoc07b3a22014-03-19 12:32:52 -0600161 * @throws Face::Error on unsupported protocol
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800162 */
Alexander Afanasyevf7ca3202014-02-14 22:28:31 -0800163 explicit
164 Face(const shared_ptr<Transport>& transport);
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800165
166 /**
Alexander Afanasyev691c3ce2014-04-23 14:28:04 -0700167 * @brief Create a new Face using the given Transport and IO service object
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800168 *
Alexander Afanasyev691c3ce2014-04-23 14:28:04 -0700169 * @sa Face(boost::asio::io_service&)
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800170 *
Steve DiBenedettoc07b3a22014-03-19 12:32:52 -0600171 * @throws Face::Error on unsupported protocol
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800172 */
173 Face(const shared_ptr<Transport>& transport,
Alexander Afanasyev691c3ce2014-04-23 14:28:04 -0700174 boost::asio::io_service& ioService);
Alexander Afanasyev7682ccb2014-02-20 10:29:35 -0800175
Jeff Thompson4fe45512013-08-23 14:06:38 -0700176 /**
Junxiao Shiedd834e2014-10-28 20:28:58 -0700177 * @brief Create a new Face using the given Transport and IO service object
178 * @param transport the Transport used for communication
179 * @param ioService the io_service that controls all IO operations
180 * @param keyChain the KeyChain to sign commands
181 * @throws Face::Error on unsupported protocol
182 * @note shared_ptr is passed by value because ownership is shared with this class
183 */
184 Face(shared_ptr<Transport> transport,
185 boost::asio::io_service& ioService,
186 KeyChain& keyChain);
187
188 ~Face();
189
190public: // consumer
191 /**
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800192 * @brief Express Interest
193 *
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700194 * @param interest An Interest to be expressed
195 * @param onData Callback to be called when a matching data packet is received
196 * @param onTimeout (optional) A function object to call if the interest times out
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800197 *
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700198 * @return The pending interest ID which can be used with removePendingInterest
Alexander Afanasyev49bb1fb2014-07-21 12:54:01 -0700199 *
200 * @throws Error when Interest size exceeds maximum limit (MAX_NDN_PACKET_SIZE)
Jeff Thompson4fe45512013-08-23 14:06:38 -0700201 */
Alexander Afanasyevb790d952014-01-24 12:07:53 -0800202 const PendingInterestId*
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800203 expressInterest(const Interest& interest,
204 const OnData& onData, const OnTimeout& onTimeout = OnTimeout());
Jeff Thompson4fe45512013-08-23 14:06:38 -0700205
206 /**
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800207 * @brief Express Interest using name and Interest template
208 *
209 * @param name Name of the Interest
210 * @param tmpl Interest template to fill parameters
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700211 * @param onData Callback to be called when a matching data packet is received
212 * @param onTimeout (optional) A function object to call if the interest times out
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800213 *
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700214 * @return Opaque pending interest ID which can be used with removePendingInterest
Alexander Afanasyev49bb1fb2014-07-21 12:54:01 -0700215 *
216 * @throws Error when Interest size exceeds maximum limit (MAX_NDN_PACKET_SIZE)
Jeff Thompson7aec0252013-08-22 17:29:57 -0700217 */
Alexander Afanasyevb790d952014-01-24 12:07:53 -0800218 const PendingInterestId*
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800219 expressInterest(const Name& name,
Alexander Afanasyev7682ccb2014-02-20 10:29:35 -0800220 const Interest& tmpl,
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800221 const OnData& onData, const OnTimeout& onTimeout = OnTimeout());
Alexander Afanasyevfdbfc6d2014-04-14 15:12:11 -0700222
Jeff Thompson11095142013-10-01 16:20:28 -0700223 /**
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700224 * @brief Cancel previously expressed Interest
Alexander Afanasyev691c3ce2014-04-23 14:28:04 -0700225 *
Jeff Thompson11095142013-10-01 16:20:28 -0700226 * @param pendingInterestId The ID returned from expressInterest.
227 */
228 void
Alexander Afanasyev7682ccb2014-02-20 10:29:35 -0800229 removePendingInterest(const PendingInterestId* pendingInterestId);
Alexander Afanasyevfdbfc6d2014-04-14 15:12:11 -0700230
Jeff Thompson432c8be2013-08-09 16:16:08 -0700231 /**
Alexander Afanasyev6fcdde22014-08-22 19:03:36 -0700232 * @brief Get number of pending Interests
233 */
234 size_t
235 getNPendingInterests() const;
236
Junxiao Shiedd834e2014-10-28 20:28:58 -0700237public: // producer
Alexander Afanasyev6fcdde22014-08-22 19:03:36 -0700238 /**
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700239 * @brief Set InterestFilter to dispatch incoming matching interest to onInterest
240 * callback and register the filtered prefix with the connected NDN forwarder
241 *
242 * This version of setInterestFilter combines setInterestFilter and registerPrefix
243 * operations and is intended to be used when only one filter for the same prefix needed
244 * to be set. When multiple names sharing the same prefix should be dispatched to
245 * different callbacks, use one registerPrefix call, followed (in onSuccess callback) by
246 * a series of setInterestFilter calls.
Alexander Afanasyev691c3ce2014-04-23 14:28:04 -0700247 *
Alexander Afanasyev90164962014-03-06 08:29:59 +0000248 * @param interestFilter Interest filter (prefix part will be registered with the forwarder)
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700249 * @param onInterest A callback to be called when a matching interest is received
250 * @param onSuccess A callback to be called when prefixRegister command succeeds
251 * @param onFailure A callback to be called when prefixRegister command fails
Joao Pereiraba1e3b92015-06-01 17:50:37 -0400252 * @param flags (optional) RIB flags
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700253 * @param certificate (optional) A certificate under which the prefix registration
Junxiao Shi6a90f372014-10-13 20:29:30 -0700254 * command is signed. When omitted, a default certificate of
255 * the default identity is used to sign the registration command
Alexander Afanasyev691c3ce2014-04-23 14:28:04 -0700256 *
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700257 * @return Opaque registered prefix ID which can be used with unsetInterestFilter or
258 * removeRegisteredPrefix
Alexander Afanasyev7e6fefc2014-10-20 12:31:55 -0400259 *
260 * @note IdentityCertificate() creates a certificate with an empty name, which is an invalid
261 * certificate. A valid IdentityCertificate has at least 4 name components, as it follows
262 * `<...>/KEY/<...>/<key-id>/ID-CERT/<version>` naming model.
Jeff Thompson86507bc2013-08-23 20:51:38 -0700263 */
Alexander Afanasyevb790d952014-01-24 12:07:53 -0800264 const RegisteredPrefixId*
Alexander Afanasyev90164962014-03-06 08:29:59 +0000265 setInterestFilter(const InterestFilter& interestFilter,
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800266 const OnInterest& onInterest,
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700267 const RegisterPrefixSuccessCallback& onSuccess,
268 const RegisterPrefixFailureCallback& onFailure,
Alexander Afanasyev0866f512014-08-11 13:25:09 -0700269 const IdentityCertificate& certificate = IdentityCertificate(),
270 uint64_t flags = nfd::ROUTE_FLAG_CHILD_INHERIT);
Jeff Thompson11095142013-10-01 16:20:28 -0700271
272 /**
Alexander Afanasyev1b01c312014-05-26 16:58:10 +0300273 * @brief Set InterestFilter to dispatch incoming matching interest to onInterest
274 * callback and register the filtered prefix with the connected NDN forwarder
275 *
276 * This version of setInterestFilter combines setInterestFilter and registerPrefix
277 * operations and is intended to be used when only one filter for the same prefix needed
278 * to be set. When multiple names sharing the same prefix should be dispatched to
279 * different callbacks, use one registerPrefix call, followed (in onSuccess callback) by
280 * a series of setInterestFilter calls.
281 *
282 * @param interestFilter Interest filter (prefix part will be registered with the forwarder)
283 * @param onInterest A callback to be called when a matching interest is received
284 * @param onFailure A callback to be called when prefixRegister command fails
Joao Pereiraba1e3b92015-06-01 17:50:37 -0400285 * @param flags (optional) RIB flags
Alexander Afanasyev1b01c312014-05-26 16:58:10 +0300286 * @param certificate (optional) A certificate under which the prefix registration
Junxiao Shi6a90f372014-10-13 20:29:30 -0700287 * command is signed. When omitted, a default certificate of
288 * the default identity is used to sign the registration command
Alexander Afanasyev1b01c312014-05-26 16:58:10 +0300289 *
290 * @return Opaque registered prefix ID which can be used with unsetInterestFilter or
291 * removeRegisteredPrefix
Alexander Afanasyev7e6fefc2014-10-20 12:31:55 -0400292 *
293 * @note IdentityCertificate() creates a certificate with an empty name, which is an invalid
294 * certificate. A valid IdentityCertificate has at least 4 name components, as it follows
295 * `<...>/KEY/<...>/<key-id>/ID-CERT/<version>` naming model.
Yingdi Yue66bf2a2014-04-28 17:07:36 -0700296 */
297 const RegisteredPrefixId*
Alexander Afanasyev90164962014-03-06 08:29:59 +0000298 setInterestFilter(const InterestFilter& interestFilter,
Yingdi Yue66bf2a2014-04-28 17:07:36 -0700299 const OnInterest& onInterest,
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700300 const RegisterPrefixFailureCallback& onFailure,
Alexander Afanasyev0866f512014-08-11 13:25:09 -0700301 const IdentityCertificate& certificate = IdentityCertificate(),
302 uint64_t flags = nfd::ROUTE_FLAG_CHILD_INHERIT);
Yingdi Yue66bf2a2014-04-28 17:07:36 -0700303
304 /**
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700305 * @brief Set InterestFilter to dispatch incoming matching interest to onInterest
306 * callback and register the filtered prefix with the connected NDN forwarder
307 *
308 * This version of setInterestFilter combines setInterestFilter and registerPrefix
309 * operations and is intended to be used when only one filter for the same prefix needed
310 * to be set. When multiple names sharing the same prefix should be dispatched to
311 * different callbacks, use one registerPrefix call, followed (in onSuccess callback) by
312 * a series of setInterestFilter calls.
Yingdi Yue66bf2a2014-04-28 17:07:36 -0700313 *
Alexander Afanasyev90164962014-03-06 08:29:59 +0000314 * @param interestFilter Interest filter (prefix part will be registered with the forwarder)
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700315 * @param onInterest A callback to be called when a matching interest is received
316 * @param onSuccess A callback to be called when prefixRegister command succeeds
317 * @param onFailure A callback to be called when prefixRegister command fails
Junxiao Shi6a90f372014-10-13 20:29:30 -0700318 * @param identity A signing identity. A prefix registration command is signed
319 * under the default certificate of this identity
Joao Pereiraba1e3b92015-06-01 17:50:37 -0400320 * @param flags (optional) RIB flags
Yingdi Yue66bf2a2014-04-28 17:07:36 -0700321 *
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700322 * @return Opaque registered prefix ID which can be used with removeRegisteredPrefix
Yingdi Yue66bf2a2014-04-28 17:07:36 -0700323 */
324 const RegisteredPrefixId*
Alexander Afanasyev90164962014-03-06 08:29:59 +0000325 setInterestFilter(const InterestFilter& interestFilter,
Yingdi Yue66bf2a2014-04-28 17:07:36 -0700326 const OnInterest& onInterest,
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700327 const RegisterPrefixSuccessCallback& onSuccess,
328 const RegisterPrefixFailureCallback& onFailure,
Alexander Afanasyev0866f512014-08-11 13:25:09 -0700329 const Name& identity,
330 uint64_t flags = nfd::ROUTE_FLAG_CHILD_INHERIT);
Yingdi Yue66bf2a2014-04-28 17:07:36 -0700331
332 /**
Alexander Afanasyev1b01c312014-05-26 16:58:10 +0300333 * @brief Set InterestFilter to dispatch incoming matching interest to onInterest
334 * callback and register the filtered prefix with the connected NDN forwarder
335 *
336 * This version of setInterestFilter combines setInterestFilter and registerPrefix
337 * operations and is intended to be used when only one filter for the same prefix needed
338 * to be set. When multiple names sharing the same prefix should be dispatched to
339 * different callbacks, use one registerPrefix call, followed (in onSuccess callback) by
340 * a series of setInterestFilter calls.
341 *
342 * @param interestFilter Interest filter (prefix part will be registered with the forwarder)
343 * @param onInterest A callback to be called when a matching interest is received
344 * @param onFailure A callback to be called when prefixRegister command fails
Junxiao Shi6a90f372014-10-13 20:29:30 -0700345 * @param identity A signing identity. A prefix registration command is signed
346 * under the default certificate of this identity
Joao Pereiraba1e3b92015-06-01 17:50:37 -0400347 * @param flags (optional) RIB flags
Alexander Afanasyev1b01c312014-05-26 16:58:10 +0300348 *
349 * @return Opaque registered prefix ID which can be used with removeRegisteredPrefix
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700350 */
351 const RegisteredPrefixId*
352 setInterestFilter(const InterestFilter& interestFilter,
353 const OnInterest& onInterest,
354 const RegisterPrefixFailureCallback& onFailure,
Alexander Afanasyev0866f512014-08-11 13:25:09 -0700355 const Name& identity,
356 uint64_t flags = nfd::ROUTE_FLAG_CHILD_INHERIT);
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700357
358 /**
359 * @brief Set InterestFilter to dispatch incoming matching interest to onInterest callback
360 *
361 * @param interestFilter Interest
362 * @param onInterest A callback to be called when a matching interest is received
363 *
364 * This method modifies library's FIB only, and does not register the prefix with the
365 * forwarder. It will always succeed. To register prefix with the forwarder, use
366 * registerPrefix, or use the setInterestFilter overload taking two callbacks.
367 *
368 * @return Opaque interest filter ID which can be used with unsetInterestFilter
369 */
370 const InterestFilterId*
371 setInterestFilter(const InterestFilter& interestFilter,
372 const OnInterest& onInterest);
373
374
375 /**
376 * @brief Register prefix with the connected NDN forwarder
377 *
Joao Pereiraba1e3b92015-06-01 17:50:37 -0400378 * This method only modifies forwarder's RIB and does not associate any
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700379 * onInterest callbacks. Use setInterestFilter method to dispatch incoming Interests to
380 * the right callbacks.
381 *
382 * @param prefix A prefix to register with the connected NDN forwarder
383 * @param onSuccess A callback to be called when prefixRegister command succeeds
384 * @param onFailure A callback to be called when prefixRegister command fails
385 * @param certificate (optional) A certificate under which the prefix registration
Junxiao Shi6a90f372014-10-13 20:29:30 -0700386 * command is signed. When omitted, a default certificate of
387 * the default identity is used to sign the registration command
Joao Pereiraba1e3b92015-06-01 17:50:37 -0400388 * @param flags (optional) RIB flags
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700389 *
390 * @return The registered prefix ID which can be used with unregisterPrefix
Alexander Afanasyev7e6fefc2014-10-20 12:31:55 -0400391 *
392 * @note IdentityCertificate() creates a certificate with an empty name, which is an invalid
393 * certificate. A valid IdentityCertificate has at least 4 name components, as it follows
394 * `<...>/KEY/<...>/<key-id>/ID-CERT/<version>` naming model.
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700395 */
396 const RegisteredPrefixId*
397 registerPrefix(const Name& prefix,
398 const RegisterPrefixSuccessCallback& onSuccess,
399 const RegisterPrefixFailureCallback& onFailure,
Alexander Afanasyev0866f512014-08-11 13:25:09 -0700400 const IdentityCertificate& certificate = IdentityCertificate(),
401 uint64_t flags = nfd::ROUTE_FLAG_CHILD_INHERIT);
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700402
403 /**
404 * @brief Register prefix with the connected NDN forwarder and call onInterest when a matching
405 * interest is received.
406 *
Joao Pereiraba1e3b92015-06-01 17:50:37 -0400407 * This method only modifies forwarder's RIB and does not associate any
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700408 * onInterest callbacks. Use setInterestFilter method to dispatch incoming Interests to
409 * the right callbacks.
410 *
411 * @param prefix A prefix to register with the connected NDN forwarder
412 * @param onSuccess A callback to be called when prefixRegister command succeeds
413 * @param onFailure A callback to be called when prefixRegister command fails
Junxiao Shi6a90f372014-10-13 20:29:30 -0700414 * @param identity A signing identity. A prefix registration command is signed
415 * under the default certificate of this identity
Joao Pereiraba1e3b92015-06-01 17:50:37 -0400416 * @param flags (optional) RIB flags
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700417 *
418 * @return The registered prefix ID which can be used with unregisterPrefix
419 */
420 const RegisteredPrefixId*
421 registerPrefix(const Name& prefix,
422 const RegisterPrefixSuccessCallback& onSuccess,
423 const RegisterPrefixFailureCallback& onFailure,
Alexander Afanasyev0866f512014-08-11 13:25:09 -0700424 const Name& identity,
425 uint64_t flags = nfd::ROUTE_FLAG_CHILD_INHERIT);
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700426
427 /**
Alexander Afanasyev1b01c312014-05-26 16:58:10 +0300428 * @brief Remove the registered prefix entry with the registeredPrefixId
Alexander Afanasyev691c3ce2014-04-23 14:28:04 -0700429 *
430 * This does not affect another registered prefix with a different registeredPrefixId,
431 * even it if has the same prefix name. If there is no entry with the
432 * registeredPrefixId, do nothing.
433 *
Alexander Afanasyevee8bb1e2014-05-02 17:39:54 -0700434 * unsetInterestFilter will use the same credentials as original
435 * setInterestFilter/registerPrefix command
436 *
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700437 * @param registeredPrefixId The ID returned from registerPrefix
Jeff Thompson11095142013-10-01 16:20:28 -0700438 */
439 void
Alexander Afanasyev7682ccb2014-02-20 10:29:35 -0800440 unsetInterestFilter(const RegisteredPrefixId* registeredPrefixId);
Alexander Afanasyeva557d5a2013-12-28 21:59:03 -0800441
Alexander Afanasyevee8bb1e2014-05-02 17:39:54 -0700442 /**
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700443 * @brief Remove previously set InterestFilter from library's FIB
444 *
445 * This method always succeeds and will **NOT** send any request to the connected
446 * forwarder.
447 *
448 * @param interestFilterId The ID returned from setInterestFilter.
449 */
450 void
451 unsetInterestFilter(const InterestFilterId* interestFilterId);
452
453 /**
Joao Pereiraba1e3b92015-06-01 17:50:37 -0400454 * @brief Unregister prefix from RIB
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700455 *
456 * unregisterPrefix will use the same credentials as original
457 * setInterestFilter/registerPrefix command
458 *
459 * If registeredPrefixId was obtained using setInterestFilter, the corresponding
460 * InterestFilter will be unset too.
461 *
Alexander Afanasyev770827c2014-05-13 17:42:55 -0700462 * @param registeredPrefixId The ID returned from registerPrefix
463 * @param onSuccess Callback to be called when operation succeeds
464 * @param onFailure Callback to be called when operation fails
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700465 */
466 void
467 unregisterPrefix(const RegisteredPrefixId* registeredPrefixId,
468 const UnregisterPrefixSuccessCallback& onSuccess,
469 const UnregisterPrefixFailureCallback& onFailure);
470
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800471 /**
Alexander Afanasyeva557d5a2013-12-28 21:59:03 -0800472 * @brief Publish data packet
473 *
Alexander Afanasyev691c3ce2014-04-23 14:28:04 -0700474 * This method can be called to satisfy the incoming Interest or to put Data packet into
Alexander Afanasyev6a05b4b2014-07-18 17:23:00 -0700475 * the cache of the local NDN forwarder.
476 *
477 * @param data Data packet to publish. It is highly recommended to use Data packet that
478 * was created using make_shared<Data>(...). Otherwise, put() will make an
479 * extra copy of the Data packet to ensure validity of published Data until
480 * asynchronous put() operation finishes.
Alexander Afanasyev49bb1fb2014-07-21 12:54:01 -0700481 *
482 * @throws Error when Data size exceeds maximum limit (MAX_NDN_PACKET_SIZE)
Alexander Afanasyeva557d5a2013-12-28 21:59:03 -0800483 */
484 void
Alexander Afanasyev7682ccb2014-02-20 10:29:35 -0800485 put(const Data& data);
Alexander Afanasyevfdbfc6d2014-04-14 15:12:11 -0700486
Junxiao Shiedd834e2014-10-28 20:28:58 -0700487public: // IO routine
Jeff Thompson86507bc2013-08-23 20:51:38 -0700488 /**
Alexander Afanasyev691c3ce2014-04-23 14:28:04 -0700489 * @brief Process any data to receive or call timeout callbacks.
Alexander Afanasyeva557d5a2013-12-28 21:59:03 -0800490 *
491 * This call will block forever (default timeout == 0) to process IO on the face.
492 * To exit, one expected to call face.shutdown() from one of the callback methods.
493 *
Alexander Afanasyev691c3ce2014-04-23 14:28:04 -0700494 * If positive timeout is specified, then processEvents will exit after this timeout, if
495 * not stopped earlier with face.shutdown() or when all active events finish. The call
496 * can be called repeatedly, if desired.
Alexander Afanasyeva557d5a2013-12-28 21:59:03 -0800497 *
Alexander Afanasyev691c3ce2014-04-23 14:28:04 -0700498 * If negative timeout is specified, then processEvents will not block and process only
499 * pending events.
Alexander Afanasyevf75a0aa2014-01-09 14:29:22 -0800500 *
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700501 * @param timeout maximum time to block the thread
Alexander Afanasyev691c3ce2014-04-23 14:28:04 -0700502 * @param keepThread Keep thread in a blocked state (in event processing), even when
503 * there are no outstanding events (e.g., no Interest/Data is expected)
504 *
505 * @throw This may throw an exception for reading data or in the callback for processing
506 * the data. If you call this from an main event loop, you may want to catch and
507 * log/disregard all exceptions.
Jeff Thompson432c8be2013-08-09 16:16:08 -0700508 */
Alexander Afanasyevfdbfc6d2014-04-14 15:12:11 -0700509 void
Alexander Afanasyevaa0e7da2014-03-17 14:37:33 -0700510 processEvents(const time::milliseconds& timeout = time::milliseconds::zero(),
511 bool keepThread = false);
Jeff Thompson432c8be2013-08-09 16:16:08 -0700512
Alexander Afanasyev691c3ce2014-04-23 14:28:04 -0700513 /**
514 * @brief Shutdown face operations
515 *
516 * This method cancels all pending operations and closes connection to NDN Forwarder.
517 *
518 * Note that this method does not stop IO service and if the same IO service is shared
519 * between multiple Faces or with other IO objects (e.g., Scheduler).
520 */
Alexander Afanasyevfdbfc6d2014-04-14 15:12:11 -0700521 void
Jeff Thompson0050abe2013-09-17 12:50:25 -0700522 shutdown();
Yingdi Yu0d920812014-01-30 14:50:57 -0800523
Alexander Afanasyev691c3ce2014-04-23 14:28:04 -0700524 /**
Alexander Afanasyev691c3ce2014-04-23 14:28:04 -0700525 * @brief Get reference to IO service object
526 */
527 boost::asio::io_service&
528 getIoService()
529 {
Junxiao Shi2cced062014-11-02 21:27:38 -0700530 return m_ioService;
Alexander Afanasyev691c3ce2014-04-23 14:28:04 -0700531 }
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800532
533private:
Steve DiBenedettoa8659ff2014-12-04 14:50:28 -0700534
535 /**
536 * @throws ConfigFile::Error on parse error and unsupported protocols
537 */
538 void
Joao Pereira68c0d882015-05-19 14:27:55 -0400539 construct(KeyChain& keyChain);
Steve DiBenedettoa8659ff2014-12-04 14:50:28 -0700540
Steve DiBenedettoc07b3a22014-03-19 12:32:52 -0600541 /**
542 * @throws Face::Error on unsupported protocol
Junxiao Shi2cced062014-11-02 21:27:38 -0700543 * @note shared_ptr is passed by value because ownership is transferred to this function
Steve DiBenedettoc07b3a22014-03-19 12:32:52 -0600544 */
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800545 void
Joao Pereira68c0d882015-05-19 14:27:55 -0400546 construct(shared_ptr<Transport> transport, KeyChain& keyChain);
Steve DiBenedettoc07b3a22014-03-19 12:32:52 -0600547
Alexander Afanasyevfdbfc6d2014-04-14 15:12:11 -0700548 void
Alexander Afanasyev6d48bc12014-02-18 00:10:51 -0800549 onReceiveElement(const Block& wire);
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800550
Alexander Afanasyev7dced462014-03-19 15:12:32 -0700551 void
552 asyncShutdown();
Alexander Afanasyevfdbfc6d2014-04-14 15:12:11 -0700553
Jeff Thompsonb982b6d2013-07-15 18:15:45 -0700554private:
Junxiao Shi2cced062014-11-02 21:27:38 -0700555 /// the IO service owned by this Face, could be null
556 unique_ptr<boost::asio::io_service> m_internalIoService;
557 /// the IO service used by this Face
558 boost::asio::io_service& m_ioService;
Alexander Afanasyevfdbfc6d2014-04-14 15:12:11 -0700559
Alexander Afanasyevf39c5372014-02-17 19:42:56 -0800560 shared_ptr<Transport> m_transport;
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800561
Junxiao Shiedd834e2014-10-28 20:28:58 -0700562 /** @brief if not null, a pointer to an internal KeyChain owned by Face
563 * @note if a KeyChain is supplied to constructor, this pointer will be null,
564 * and the passed KeyChain is given to nfdController;
565 * currently Face does not keep the KeyChain passed in constructor
566 * because it's not needed, but this may change in the future
567 */
Joao Pereira68c0d882015-05-19 14:27:55 -0400568 unique_ptr<KeyChain> m_internalKeyChain;
Junxiao Shiedd834e2014-10-28 20:28:58 -0700569
Joao Pereira68c0d882015-05-19 14:27:55 -0400570 unique_ptr<nfd::Controller> m_nfdController;
Steve DiBenedettoc07b3a22014-03-19 12:32:52 -0600571
Alexander Afanasyev258ec2b2014-05-14 16:15:37 -0700572 class Impl;
Joao Pereira68c0d882015-05-19 14:27:55 -0400573 unique_ptr<Impl> m_impl;
Jeff Thompsonaa4e6db2013-07-15 17:25:23 -0700574};
575
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800576} // namespace ndn
Jeff Thompsonaa4e6db2013-07-15 17:25:23 -0700577
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800578#endif // NDN_FACE_HPP