blob: 47e841e81a52ce372baf619c2bd52ba37c7e3d6e [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 Afanasyevc169a812014-05-20 20:37:29 -04003 * Copyright (c) 2013-2014 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.
Alexander Afanasyevdfa52c42014-04-24 21:10:11 -070020 *
21 * Based on code originally written by Jeff Thompson <jefft0@remap.ucla.edu>
Jeff Thompsonaa4e6db2013-07-15 17:25:23 -070022 */
23
Jeff Thompsonb9e3c8e2013-08-02 11:42:51 -070024#ifndef NDN_FACE_HPP
Jeff Thompsona0d18c92013-08-06 13:55:32 -070025#define NDN_FACE_HPP
Jeff Thompsonaa4e6db2013-07-15 17:25:23 -070026
Alexander Afanasyev0222fba2014-02-09 23:16:02 -080027#include "common.hpp"
Alexander Afanasyev258ec2b2014-05-14 16:15:37 -070028
29#include "name.hpp"
Alexander Afanasyev0222fba2014-02-09 23:16:02 -080030#include "interest.hpp"
Alexander Afanasyev258ec2b2014-05-14 16:15:37 -070031#include "interest-filter.hpp"
Alexander Afanasyev0222fba2014-02-09 23:16:02 -080032#include "data.hpp"
Alexander Afanasyev984ad192014-05-02 19:11:15 -070033#include "security/identity-certificate.hpp"
Alexander Afanasyev0222fba2014-02-09 23:16:02 -080034
Alexander Afanasyev258ec2b2014-05-14 16:15:37 -070035namespace boost {
36namespace asio {
37class io_service;
38}
39}
Alexander Afanasyev0222fba2014-02-09 23:16:02 -080040
Jeff Thompsonaa4e6db2013-07-15 17:25:23 -070041namespace ndn {
42
Alexander Afanasyev258ec2b2014-05-14 16:15:37 -070043class Transport;
Junxiao Shiedd834e2014-10-28 20:28:58 -070044class KeyChain;
Alexander Afanasyev258ec2b2014-05-14 16:15:37 -070045
46class PendingInterestId;
47class RegisteredPrefixId;
48class InterestFilterId;
49
Alexander Afanasyevee8bb1e2014-05-02 17:39:54 -070050namespace nfd {
51class Controller;
52}
Alexander Afanasyevee8bb1e2014-05-02 17:39:54 -070053
Jeff Thompsonfe08e5a2013-08-13 11:15:59 -070054/**
Alexander Afanasyev984ad192014-05-02 19:11:15 -070055 * @brief Callback called when expressed Interest gets satisfied with Data packet
Alexander Afanasyev0222fba2014-02-09 23:16:02 -080056 */
57typedef function<void(const Interest&, Data&)> OnData;
58
59/**
Alexander Afanasyev984ad192014-05-02 19:11:15 -070060 * @brief Callback called when expressed Interest times out
Alexander Afanasyev0222fba2014-02-09 23:16:02 -080061 */
62typedef function<void(const Interest&)> OnTimeout;
63
64/**
Alexander Afanasyev984ad192014-05-02 19:11:15 -070065 * @brief Callback called when incoming Interest matches the specified InterestFilter
Alexander Afanasyev0222fba2014-02-09 23:16:02 -080066 */
Alexander Afanasyev90164962014-03-06 08:29:59 +000067typedef function<void (const InterestFilter&, const Interest&)> OnInterest;
Alexander Afanasyev0222fba2014-02-09 23:16:02 -080068
69/**
Alexander Afanasyev984ad192014-05-02 19:11:15 -070070 * @brief Callback called when registerPrefix or setInterestFilter command succeeds
Alexander Afanasyev0222fba2014-02-09 23:16:02 -080071 */
Alexander Afanasyev984ad192014-05-02 19:11:15 -070072typedef function<void(const Name&)> RegisterPrefixSuccessCallback;
Alexander Afanasyev0222fba2014-02-09 23:16:02 -080073
Alexander Afanasyev984ad192014-05-02 19:11:15 -070074/**
75 * @brief Callback called when registerPrefix or setInterestFilter command fails
76 */
77typedef function<void(const Name&, const std::string&)> RegisterPrefixFailureCallback;
78
79/**
80 * @brief Callback called when unregisterPrefix or unsetInterestFilter command succeeds
81 */
82typedef function<void()> UnregisterPrefixSuccessCallback;
83
84/**
85 * @brief Callback called when unregisterPrefix or unsetInterestFilter command fails
86 */
87typedef function<void(const std::string&)> UnregisterPrefixFailureCallback;
Alexander Afanasyev0222fba2014-02-09 23:16:02 -080088
89
90/**
91 * @brief Abstraction to communicate with local or remote NDN forwarder
Jeff Thompsonfe08e5a2013-08-13 11:15:59 -070092 */
Alexander Afanasyev8460afb2014-02-15 20:31:42 -080093class Face : noncopyable
94{
Jeff Thompsonaa4e6db2013-07-15 17:25:23 -070095public:
Alexander Afanasyevfdbfc6d2014-04-14 15:12:11 -070096 class Error : public std::runtime_error
97 {
98 public:
99 explicit
100 Error(const std::string& what)
101 : std::runtime_error(what)
102 {
103 }
104 };
Alexander Afanasyevb790d952014-01-24 12:07:53 -0800105
Junxiao Shiedd834e2014-10-28 20:28:58 -0700106public: // constructors
Alexander Afanasyevb790d952014-01-24 12:07:53 -0800107 /**
Alexander Afanasyev691c3ce2014-04-23 14:28:04 -0700108 * @brief Create a new Face using the default transport (UnixTransport)
109 *
Steve DiBenedettoc07b3a22014-03-19 12:32:52 -0600110 * @throws ConfigFile::Error on configuration file parse failure
111 * @throws Face::Error on unsupported protocol
Alexander Afanasyevb790d952014-01-24 12:07:53 -0800112 */
Alexander Afanasyevf7ca3202014-02-14 22:28:31 -0800113 Face();
Alexander Afanasyeve2e0d752014-01-03 13:30:30 -0800114
115 /**
Alexander Afanasyev691c3ce2014-04-23 14:28:04 -0700116 * @brief Create a new Face using the default transport (UnixTransport)
117 *
Alexander Afanasyev691c3ce2014-04-23 14:28:04 -0700118 * @par Usage examples:
119 *
120 * Face face1;
121 * Face face2(face1.getIoService());
122 *
123 * // Now the following ensures that events on both faces are processed
124 * face1.processEvents();
125 * // or face1.getIoService().run();
126 *
127 * @par or
128 *
129 * boost::asio::io_service ioService;
130 * Face face1(ioService);
131 * Face face2(ioService);
132 * ...
133 *
134 * ioService.run();
135 *
136 * @param ioService A reference to boost::io_service object that should control all
137 * IO operations.
138 * @throws ConfigFile::Error on configuration file parse failure
139 * @throws Face::Error on unsupported protocol
140 */
141 explicit
142 Face(boost::asio::io_service& ioService);
143
144 /**
145 * @brief Create a new Face using TcpTransport
146 *
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700147 * @param host The host of the NDN forwarder
148 * @param port (optional) The port or service name of the NDN forwarder (**default**: "6363")
149 *
Steve DiBenedettoc07b3a22014-03-19 12:32:52 -0600150 * @throws Face::Error on unsupported protocol
Jeff Thompsonfe08e5a2013-08-13 11:15:59 -0700151 */
Alexander Afanasyev7682ccb2014-02-20 10:29:35 -0800152 Face(const std::string& host, const std::string& port = "6363");
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800153
154 /**
Alexander Afanasyev691c3ce2014-04-23 14:28:04 -0700155 * @brief Create a new Face using the given Transport
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700156 *
157 * @param transport A shared_ptr to a Transport object used for communication
158 *
Steve DiBenedettoc07b3a22014-03-19 12:32:52 -0600159 * @throws Face::Error on unsupported protocol
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800160 */
Alexander Afanasyevf7ca3202014-02-14 22:28:31 -0800161 explicit
162 Face(const shared_ptr<Transport>& transport);
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800163
164 /**
Alexander Afanasyev691c3ce2014-04-23 14:28:04 -0700165 * @brief Create a new Face using the given Transport and IO service object
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800166 *
Alexander Afanasyev691c3ce2014-04-23 14:28:04 -0700167 * @sa Face(boost::asio::io_service&)
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800168 *
Steve DiBenedettoc07b3a22014-03-19 12:32:52 -0600169 * @throws Face::Error on unsupported protocol
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800170 */
171 Face(const shared_ptr<Transport>& transport,
Alexander Afanasyev691c3ce2014-04-23 14:28:04 -0700172 boost::asio::io_service& ioService);
Alexander Afanasyev7682ccb2014-02-20 10:29:35 -0800173
Jeff Thompson4fe45512013-08-23 14:06:38 -0700174 /**
Junxiao Shiedd834e2014-10-28 20:28:58 -0700175 * @brief Create a new Face using the given Transport and IO service object
176 * @param transport the Transport used for communication
177 * @param ioService the io_service that controls all IO operations
178 * @param keyChain the KeyChain to sign commands
179 * @throws Face::Error on unsupported protocol
180 * @note shared_ptr is passed by value because ownership is shared with this class
181 */
182 Face(shared_ptr<Transport> transport,
183 boost::asio::io_service& ioService,
184 KeyChain& keyChain);
185
186 ~Face();
187
188public: // consumer
189 /**
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800190 * @brief Express Interest
191 *
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700192 * @param interest An Interest to be expressed
193 * @param onData Callback to be called when a matching data packet is received
194 * @param onTimeout (optional) A function object to call if the interest times out
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800195 *
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700196 * @return The pending interest ID which can be used with removePendingInterest
Alexander Afanasyev49bb1fb2014-07-21 12:54:01 -0700197 *
198 * @throws Error when Interest size exceeds maximum limit (MAX_NDN_PACKET_SIZE)
Jeff Thompson4fe45512013-08-23 14:06:38 -0700199 */
Alexander Afanasyevb790d952014-01-24 12:07:53 -0800200 const PendingInterestId*
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800201 expressInterest(const Interest& interest,
202 const OnData& onData, const OnTimeout& onTimeout = OnTimeout());
Jeff Thompson4fe45512013-08-23 14:06:38 -0700203
204 /**
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800205 * @brief Express Interest using name and Interest template
206 *
207 * @param name Name of the Interest
208 * @param tmpl Interest template to fill parameters
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700209 * @param onData Callback to be called when a matching data packet is received
210 * @param onTimeout (optional) A function object to call if the interest times out
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800211 *
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700212 * @return Opaque pending interest ID which can be used with removePendingInterest
Alexander Afanasyev49bb1fb2014-07-21 12:54:01 -0700213 *
214 * @throws Error when Interest size exceeds maximum limit (MAX_NDN_PACKET_SIZE)
Jeff Thompson7aec0252013-08-22 17:29:57 -0700215 */
Alexander Afanasyevb790d952014-01-24 12:07:53 -0800216 const PendingInterestId*
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800217 expressInterest(const Name& name,
Alexander Afanasyev7682ccb2014-02-20 10:29:35 -0800218 const Interest& tmpl,
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800219 const OnData& onData, const OnTimeout& onTimeout = OnTimeout());
Alexander Afanasyevfdbfc6d2014-04-14 15:12:11 -0700220
Jeff Thompson11095142013-10-01 16:20:28 -0700221 /**
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700222 * @brief Cancel previously expressed Interest
Alexander Afanasyev691c3ce2014-04-23 14:28:04 -0700223 *
Jeff Thompson11095142013-10-01 16:20:28 -0700224 * @param pendingInterestId The ID returned from expressInterest.
225 */
226 void
Alexander Afanasyev7682ccb2014-02-20 10:29:35 -0800227 removePendingInterest(const PendingInterestId* pendingInterestId);
Alexander Afanasyevfdbfc6d2014-04-14 15:12:11 -0700228
Jeff Thompson432c8be2013-08-09 16:16:08 -0700229 /**
Alexander Afanasyev6fcdde22014-08-22 19:03:36 -0700230 * @brief Get number of pending Interests
231 */
232 size_t
233 getNPendingInterests() const;
234
Junxiao Shiedd834e2014-10-28 20:28:58 -0700235public: // producer
Alexander Afanasyev6fcdde22014-08-22 19:03:36 -0700236 /**
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700237 * @brief Set InterestFilter to dispatch incoming matching interest to onInterest
238 * callback and register the filtered prefix with the connected NDN forwarder
239 *
240 * This version of setInterestFilter combines setInterestFilter and registerPrefix
241 * operations and is intended to be used when only one filter for the same prefix needed
242 * to be set. When multiple names sharing the same prefix should be dispatched to
243 * different callbacks, use one registerPrefix call, followed (in onSuccess callback) by
244 * a series of setInterestFilter calls.
Alexander Afanasyev691c3ce2014-04-23 14:28:04 -0700245 *
Alexander Afanasyev90164962014-03-06 08:29:59 +0000246 * @param interestFilter Interest filter (prefix part will be registered with the forwarder)
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700247 * @param onInterest A callback to be called when a matching interest is received
248 * @param onSuccess A callback to be called when prefixRegister command succeeds
249 * @param onFailure A callback to be called when prefixRegister command fails
Joao Pereiraba1e3b92015-06-01 17:50:37 -0400250 * @param flags (optional) RIB flags
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700251 * @param certificate (optional) A certificate under which the prefix registration
Junxiao Shi6a90f372014-10-13 20:29:30 -0700252 * command is signed. When omitted, a default certificate of
253 * the default identity is used to sign the registration command
Alexander Afanasyev691c3ce2014-04-23 14:28:04 -0700254 *
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700255 * @return Opaque registered prefix ID which can be used with unsetInterestFilter or
256 * removeRegisteredPrefix
Alexander Afanasyev7e6fefc2014-10-20 12:31:55 -0400257 *
258 * @note IdentityCertificate() creates a certificate with an empty name, which is an invalid
259 * certificate. A valid IdentityCertificate has at least 4 name components, as it follows
260 * `<...>/KEY/<...>/<key-id>/ID-CERT/<version>` naming model.
Jeff Thompson86507bc2013-08-23 20:51:38 -0700261 */
Alexander Afanasyevb790d952014-01-24 12:07:53 -0800262 const RegisteredPrefixId*
Alexander Afanasyev90164962014-03-06 08:29:59 +0000263 setInterestFilter(const InterestFilter& interestFilter,
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800264 const OnInterest& onInterest,
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700265 const RegisterPrefixSuccessCallback& onSuccess,
266 const RegisterPrefixFailureCallback& onFailure,
Alexander Afanasyev0866f512014-08-11 13:25:09 -0700267 const IdentityCertificate& certificate = IdentityCertificate(),
268 uint64_t flags = nfd::ROUTE_FLAG_CHILD_INHERIT);
Jeff Thompson11095142013-10-01 16:20:28 -0700269
270 /**
Alexander Afanasyev1b01c312014-05-26 16:58:10 +0300271 * @brief Set InterestFilter to dispatch incoming matching interest to onInterest
272 * callback and register the filtered prefix with the connected NDN forwarder
273 *
274 * This version of setInterestFilter combines setInterestFilter and registerPrefix
275 * operations and is intended to be used when only one filter for the same prefix needed
276 * to be set. When multiple names sharing the same prefix should be dispatched to
277 * different callbacks, use one registerPrefix call, followed (in onSuccess callback) by
278 * a series of setInterestFilter calls.
279 *
280 * @param interestFilter Interest filter (prefix part will be registered with the forwarder)
281 * @param onInterest A callback to be called when a matching interest is received
282 * @param onFailure A callback to be called when prefixRegister command fails
Joao Pereiraba1e3b92015-06-01 17:50:37 -0400283 * @param flags (optional) RIB flags
Alexander Afanasyev1b01c312014-05-26 16:58:10 +0300284 * @param certificate (optional) A certificate under which the prefix registration
Junxiao Shi6a90f372014-10-13 20:29:30 -0700285 * command is signed. When omitted, a default certificate of
286 * the default identity is used to sign the registration command
Alexander Afanasyev1b01c312014-05-26 16:58:10 +0300287 *
288 * @return Opaque registered prefix ID which can be used with unsetInterestFilter or
289 * removeRegisteredPrefix
Alexander Afanasyev7e6fefc2014-10-20 12:31:55 -0400290 *
291 * @note IdentityCertificate() creates a certificate with an empty name, which is an invalid
292 * certificate. A valid IdentityCertificate has at least 4 name components, as it follows
293 * `<...>/KEY/<...>/<key-id>/ID-CERT/<version>` naming model.
Yingdi Yue66bf2a2014-04-28 17:07:36 -0700294 */
295 const RegisteredPrefixId*
Alexander Afanasyev90164962014-03-06 08:29:59 +0000296 setInterestFilter(const InterestFilter& interestFilter,
Yingdi Yue66bf2a2014-04-28 17:07:36 -0700297 const OnInterest& onInterest,
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700298 const RegisterPrefixFailureCallback& onFailure,
Alexander Afanasyev0866f512014-08-11 13:25:09 -0700299 const IdentityCertificate& certificate = IdentityCertificate(),
300 uint64_t flags = nfd::ROUTE_FLAG_CHILD_INHERIT);
Yingdi Yue66bf2a2014-04-28 17:07:36 -0700301
302 /**
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700303 * @brief Set InterestFilter to dispatch incoming matching interest to onInterest
304 * callback and register the filtered prefix with the connected NDN forwarder
305 *
306 * This version of setInterestFilter combines setInterestFilter and registerPrefix
307 * operations and is intended to be used when only one filter for the same prefix needed
308 * to be set. When multiple names sharing the same prefix should be dispatched to
309 * different callbacks, use one registerPrefix call, followed (in onSuccess callback) by
310 * a series of setInterestFilter calls.
Yingdi Yue66bf2a2014-04-28 17:07:36 -0700311 *
Alexander Afanasyev90164962014-03-06 08:29:59 +0000312 * @param interestFilter Interest filter (prefix part will be registered with the forwarder)
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700313 * @param onInterest A callback to be called when a matching interest is received
314 * @param onSuccess A callback to be called when prefixRegister command succeeds
315 * @param onFailure A callback to be called when prefixRegister command fails
Junxiao Shi6a90f372014-10-13 20:29:30 -0700316 * @param identity A signing identity. A prefix registration command is signed
317 * under the default certificate of this identity
Joao Pereiraba1e3b92015-06-01 17:50:37 -0400318 * @param flags (optional) RIB flags
Yingdi Yue66bf2a2014-04-28 17:07:36 -0700319 *
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700320 * @return Opaque registered prefix ID which can be used with removeRegisteredPrefix
Yingdi Yue66bf2a2014-04-28 17:07:36 -0700321 */
322 const RegisteredPrefixId*
Alexander Afanasyev90164962014-03-06 08:29:59 +0000323 setInterestFilter(const InterestFilter& interestFilter,
Yingdi Yue66bf2a2014-04-28 17:07:36 -0700324 const OnInterest& onInterest,
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700325 const RegisterPrefixSuccessCallback& onSuccess,
326 const RegisterPrefixFailureCallback& onFailure,
Alexander Afanasyev0866f512014-08-11 13:25:09 -0700327 const Name& identity,
328 uint64_t flags = nfd::ROUTE_FLAG_CHILD_INHERIT);
Yingdi Yue66bf2a2014-04-28 17:07:36 -0700329
330 /**
Alexander Afanasyev1b01c312014-05-26 16:58:10 +0300331 * @brief Set InterestFilter to dispatch incoming matching interest to onInterest
332 * callback and register the filtered prefix with the connected NDN forwarder
333 *
334 * This version of setInterestFilter combines setInterestFilter and registerPrefix
335 * operations and is intended to be used when only one filter for the same prefix needed
336 * to be set. When multiple names sharing the same prefix should be dispatched to
337 * different callbacks, use one registerPrefix call, followed (in onSuccess callback) by
338 * a series of setInterestFilter calls.
339 *
340 * @param interestFilter Interest filter (prefix part will be registered with the forwarder)
341 * @param onInterest A callback to be called when a matching interest is received
342 * @param onFailure A callback to be called when prefixRegister command fails
Junxiao Shi6a90f372014-10-13 20:29:30 -0700343 * @param identity A signing identity. A prefix registration command is signed
344 * under the default certificate of this identity
Joao Pereiraba1e3b92015-06-01 17:50:37 -0400345 * @param flags (optional) RIB flags
Alexander Afanasyev1b01c312014-05-26 16:58:10 +0300346 *
347 * @return Opaque registered prefix ID which can be used with removeRegisteredPrefix
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700348 */
349 const RegisteredPrefixId*
350 setInterestFilter(const InterestFilter& interestFilter,
351 const OnInterest& onInterest,
352 const RegisterPrefixFailureCallback& onFailure,
Alexander Afanasyev0866f512014-08-11 13:25:09 -0700353 const Name& identity,
354 uint64_t flags = nfd::ROUTE_FLAG_CHILD_INHERIT);
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700355
356 /**
357 * @brief Set InterestFilter to dispatch incoming matching interest to onInterest callback
358 *
359 * @param interestFilter Interest
360 * @param onInterest A callback to be called when a matching interest is received
361 *
362 * This method modifies library's FIB only, and does not register the prefix with the
363 * forwarder. It will always succeed. To register prefix with the forwarder, use
364 * registerPrefix, or use the setInterestFilter overload taking two callbacks.
365 *
366 * @return Opaque interest filter ID which can be used with unsetInterestFilter
367 */
368 const InterestFilterId*
369 setInterestFilter(const InterestFilter& interestFilter,
370 const OnInterest& onInterest);
371
372
373 /**
374 * @brief Register prefix with the connected NDN forwarder
375 *
Joao Pereiraba1e3b92015-06-01 17:50:37 -0400376 * This method only modifies forwarder's RIB and does not associate any
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700377 * onInterest callbacks. Use setInterestFilter method to dispatch incoming Interests to
378 * the right callbacks.
379 *
380 * @param prefix A prefix to register with the connected NDN forwarder
381 * @param onSuccess A callback to be called when prefixRegister command succeeds
382 * @param onFailure A callback to be called when prefixRegister command fails
383 * @param certificate (optional) A certificate under which the prefix registration
Junxiao Shi6a90f372014-10-13 20:29:30 -0700384 * command is signed. When omitted, a default certificate of
385 * the default identity is used to sign the registration command
Joao Pereiraba1e3b92015-06-01 17:50:37 -0400386 * @param flags (optional) RIB flags
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700387 *
388 * @return The registered prefix ID which can be used with unregisterPrefix
Alexander Afanasyev7e6fefc2014-10-20 12:31:55 -0400389 *
390 * @note IdentityCertificate() creates a certificate with an empty name, which is an invalid
391 * certificate. A valid IdentityCertificate has at least 4 name components, as it follows
392 * `<...>/KEY/<...>/<key-id>/ID-CERT/<version>` naming model.
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700393 */
394 const RegisteredPrefixId*
395 registerPrefix(const Name& prefix,
396 const RegisterPrefixSuccessCallback& onSuccess,
397 const RegisterPrefixFailureCallback& onFailure,
Alexander Afanasyev0866f512014-08-11 13:25:09 -0700398 const IdentityCertificate& certificate = IdentityCertificate(),
399 uint64_t flags = nfd::ROUTE_FLAG_CHILD_INHERIT);
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700400
401 /**
402 * @brief Register prefix with the connected NDN forwarder and call onInterest when a matching
403 * interest is received.
404 *
Joao Pereiraba1e3b92015-06-01 17:50:37 -0400405 * This method only modifies forwarder's RIB and does not associate any
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700406 * onInterest callbacks. Use setInterestFilter method to dispatch incoming Interests to
407 * the right callbacks.
408 *
409 * @param prefix A prefix to register with the connected NDN forwarder
410 * @param onSuccess A callback to be called when prefixRegister command succeeds
411 * @param onFailure A callback to be called when prefixRegister command fails
Junxiao Shi6a90f372014-10-13 20:29:30 -0700412 * @param identity A signing identity. A prefix registration command is signed
413 * under the default certificate of this identity
Joao Pereiraba1e3b92015-06-01 17:50:37 -0400414 * @param flags (optional) RIB flags
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700415 *
416 * @return The registered prefix ID which can be used with unregisterPrefix
417 */
418 const RegisteredPrefixId*
419 registerPrefix(const Name& prefix,
420 const RegisterPrefixSuccessCallback& onSuccess,
421 const RegisterPrefixFailureCallback& onFailure,
Alexander Afanasyev0866f512014-08-11 13:25:09 -0700422 const Name& identity,
423 uint64_t flags = nfd::ROUTE_FLAG_CHILD_INHERIT);
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700424
425 /**
Alexander Afanasyev1b01c312014-05-26 16:58:10 +0300426 * @brief Remove the registered prefix entry with the registeredPrefixId
Alexander Afanasyev691c3ce2014-04-23 14:28:04 -0700427 *
428 * This does not affect another registered prefix with a different registeredPrefixId,
429 * even it if has the same prefix name. If there is no entry with the
430 * registeredPrefixId, do nothing.
431 *
Alexander Afanasyevee8bb1e2014-05-02 17:39:54 -0700432 * unsetInterestFilter will use the same credentials as original
433 * setInterestFilter/registerPrefix command
434 *
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700435 * @param registeredPrefixId The ID returned from registerPrefix
Jeff Thompson11095142013-10-01 16:20:28 -0700436 */
437 void
Alexander Afanasyev7682ccb2014-02-20 10:29:35 -0800438 unsetInterestFilter(const RegisteredPrefixId* registeredPrefixId);
Alexander Afanasyeva557d5a2013-12-28 21:59:03 -0800439
Alexander Afanasyevee8bb1e2014-05-02 17:39:54 -0700440 /**
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700441 * @brief Remove previously set InterestFilter from library's FIB
442 *
443 * This method always succeeds and will **NOT** send any request to the connected
444 * forwarder.
445 *
446 * @param interestFilterId The ID returned from setInterestFilter.
447 */
448 void
449 unsetInterestFilter(const InterestFilterId* interestFilterId);
450
451 /**
Joao Pereiraba1e3b92015-06-01 17:50:37 -0400452 * @brief Unregister prefix from RIB
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700453 *
454 * unregisterPrefix will use the same credentials as original
455 * setInterestFilter/registerPrefix command
456 *
457 * If registeredPrefixId was obtained using setInterestFilter, the corresponding
458 * InterestFilter will be unset too.
459 *
Alexander Afanasyev770827c2014-05-13 17:42:55 -0700460 * @param registeredPrefixId The ID returned from registerPrefix
461 * @param onSuccess Callback to be called when operation succeeds
462 * @param onFailure Callback to be called when operation fails
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700463 */
464 void
465 unregisterPrefix(const RegisteredPrefixId* registeredPrefixId,
466 const UnregisterPrefixSuccessCallback& onSuccess,
467 const UnregisterPrefixFailureCallback& onFailure);
468
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800469 /**
Alexander Afanasyeva557d5a2013-12-28 21:59:03 -0800470 * @brief Publish data packet
471 *
Alexander Afanasyev691c3ce2014-04-23 14:28:04 -0700472 * This method can be called to satisfy the incoming Interest or to put Data packet into
Alexander Afanasyev6a05b4b2014-07-18 17:23:00 -0700473 * the cache of the local NDN forwarder.
474 *
475 * @param data Data packet to publish. It is highly recommended to use Data packet that
476 * was created using make_shared<Data>(...). Otherwise, put() will make an
477 * extra copy of the Data packet to ensure validity of published Data until
478 * asynchronous put() operation finishes.
Alexander Afanasyev49bb1fb2014-07-21 12:54:01 -0700479 *
480 * @throws Error when Data size exceeds maximum limit (MAX_NDN_PACKET_SIZE)
Alexander Afanasyeva557d5a2013-12-28 21:59:03 -0800481 */
482 void
Alexander Afanasyev7682ccb2014-02-20 10:29:35 -0800483 put(const Data& data);
Alexander Afanasyevfdbfc6d2014-04-14 15:12:11 -0700484
Junxiao Shiedd834e2014-10-28 20:28:58 -0700485public: // IO routine
Jeff Thompson86507bc2013-08-23 20:51:38 -0700486 /**
Alexander Afanasyev691c3ce2014-04-23 14:28:04 -0700487 * @brief Process any data to receive or call timeout callbacks.
Alexander Afanasyeva557d5a2013-12-28 21:59:03 -0800488 *
489 * This call will block forever (default timeout == 0) to process IO on the face.
490 * To exit, one expected to call face.shutdown() from one of the callback methods.
491 *
Alexander Afanasyev691c3ce2014-04-23 14:28:04 -0700492 * If positive timeout is specified, then processEvents will exit after this timeout, if
493 * not stopped earlier with face.shutdown() or when all active events finish. The call
494 * can be called repeatedly, if desired.
Alexander Afanasyeva557d5a2013-12-28 21:59:03 -0800495 *
Alexander Afanasyev691c3ce2014-04-23 14:28:04 -0700496 * If negative timeout is specified, then processEvents will not block and process only
497 * pending events.
Alexander Afanasyevf75a0aa2014-01-09 14:29:22 -0800498 *
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700499 * @param timeout maximum time to block the thread
Alexander Afanasyev691c3ce2014-04-23 14:28:04 -0700500 * @param keepThread Keep thread in a blocked state (in event processing), even when
501 * there are no outstanding events (e.g., no Interest/Data is expected)
502 *
503 * @throw This may throw an exception for reading data or in the callback for processing
504 * the data. If you call this from an main event loop, you may want to catch and
505 * log/disregard all exceptions.
Jeff Thompson432c8be2013-08-09 16:16:08 -0700506 */
Alexander Afanasyevfdbfc6d2014-04-14 15:12:11 -0700507 void
Alexander Afanasyevaa0e7da2014-03-17 14:37:33 -0700508 processEvents(const time::milliseconds& timeout = time::milliseconds::zero(),
509 bool keepThread = false);
Jeff Thompson432c8be2013-08-09 16:16:08 -0700510
Alexander Afanasyev691c3ce2014-04-23 14:28:04 -0700511 /**
512 * @brief Shutdown face operations
513 *
514 * This method cancels all pending operations and closes connection to NDN Forwarder.
515 *
516 * Note that this method does not stop IO service and if the same IO service is shared
517 * between multiple Faces or with other IO objects (e.g., Scheduler).
518 */
Alexander Afanasyevfdbfc6d2014-04-14 15:12:11 -0700519 void
Jeff Thompson0050abe2013-09-17 12:50:25 -0700520 shutdown();
Yingdi Yu0d920812014-01-30 14:50:57 -0800521
Alexander Afanasyev691c3ce2014-04-23 14:28:04 -0700522 /**
Alexander Afanasyev691c3ce2014-04-23 14:28:04 -0700523 * @brief Get reference to IO service object
524 */
525 boost::asio::io_service&
526 getIoService()
527 {
Junxiao Shi2cced062014-11-02 21:27:38 -0700528 return m_ioService;
Alexander Afanasyev691c3ce2014-04-23 14:28:04 -0700529 }
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800530
531private:
Steve DiBenedettoa8659ff2014-12-04 14:50:28 -0700532
533 /**
534 * @throws ConfigFile::Error on parse error and unsupported protocols
535 */
536 void
Joao Pereira68c0d882015-05-19 14:27:55 -0400537 construct(KeyChain& keyChain);
Steve DiBenedettoa8659ff2014-12-04 14:50:28 -0700538
Steve DiBenedettoc07b3a22014-03-19 12:32:52 -0600539 /**
540 * @throws Face::Error on unsupported protocol
Junxiao Shi2cced062014-11-02 21:27:38 -0700541 * @note shared_ptr is passed by value because ownership is transferred to this function
Steve DiBenedettoc07b3a22014-03-19 12:32:52 -0600542 */
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800543 void
Joao Pereira68c0d882015-05-19 14:27:55 -0400544 construct(shared_ptr<Transport> transport, KeyChain& keyChain);
Steve DiBenedettoc07b3a22014-03-19 12:32:52 -0600545
Alexander Afanasyev691c3ce2014-04-23 14:28:04 -0700546 class ProcessEventsTimeout
547 {
548 };
549
Alexander Afanasyevfdbfc6d2014-04-14 15:12:11 -0700550 void
Alexander Afanasyev6d48bc12014-02-18 00:10:51 -0800551 onReceiveElement(const Block& wire);
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800552
Alexander Afanasyev7dced462014-03-19 15:12:32 -0700553 void
554 asyncShutdown();
Alexander Afanasyevfdbfc6d2014-04-14 15:12:11 -0700555
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800556 static void
557 fireProcessEventsTimeout(const boost::system::error_code& error);
558
Jeff Thompsonb982b6d2013-07-15 18:15:45 -0700559private:
Junxiao Shi2cced062014-11-02 21:27:38 -0700560 /// the IO service owned by this Face, could be null
561 unique_ptr<boost::asio::io_service> m_internalIoService;
562 /// the IO service used by this Face
563 boost::asio::io_service& m_ioService;
Alexander Afanasyevfdbfc6d2014-04-14 15:12:11 -0700564
Alexander Afanasyevf39c5372014-02-17 19:42:56 -0800565 shared_ptr<Transport> m_transport;
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800566
Junxiao Shiedd834e2014-10-28 20:28:58 -0700567 /** @brief if not null, a pointer to an internal KeyChain owned by Face
568 * @note if a KeyChain is supplied to constructor, this pointer will be null,
569 * and the passed KeyChain is given to nfdController;
570 * currently Face does not keep the KeyChain passed in constructor
571 * because it's not needed, but this may change in the future
572 */
Joao Pereira68c0d882015-05-19 14:27:55 -0400573 unique_ptr<KeyChain> m_internalKeyChain;
Junxiao Shiedd834e2014-10-28 20:28:58 -0700574
Joao Pereira68c0d882015-05-19 14:27:55 -0400575 unique_ptr<nfd::Controller> m_nfdController;
Steve DiBenedettoc07b3a22014-03-19 12:32:52 -0600576
Alexander Afanasyev258ec2b2014-05-14 16:15:37 -0700577 class Impl;
Joao Pereira68c0d882015-05-19 14:27:55 -0400578 unique_ptr<Impl> m_impl;
Jeff Thompsonaa4e6db2013-07-15 17:25:23 -0700579};
580
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800581} // namespace ndn
Jeff Thompsonaa4e6db2013-07-15 17:25:23 -0700582
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800583#endif // NDN_FACE_HPP