blob: 9f11b0a80bc366c5a95cda7432d316b1e4ab7914 [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;
44
45class PendingInterestId;
46class RegisteredPrefixId;
47class InterestFilterId;
48
Alexander Afanasyevee8bb1e2014-05-02 17:39:54 -070049namespace nfd {
50class Controller;
51}
Alexander Afanasyevee8bb1e2014-05-02 17:39:54 -070052
Jeff Thompsonfe08e5a2013-08-13 11:15:59 -070053/**
Alexander Afanasyev984ad192014-05-02 19:11:15 -070054 * @brief Callback called when expressed Interest gets satisfied with Data packet
Alexander Afanasyev0222fba2014-02-09 23:16:02 -080055 */
56typedef function<void(const Interest&, Data&)> OnData;
57
58/**
Alexander Afanasyev984ad192014-05-02 19:11:15 -070059 * @brief Callback called when expressed Interest times out
Alexander Afanasyev0222fba2014-02-09 23:16:02 -080060 */
61typedef function<void(const Interest&)> OnTimeout;
62
63/**
Alexander Afanasyev984ad192014-05-02 19:11:15 -070064 * @brief Callback called when incoming Interest matches the specified InterestFilter
Alexander Afanasyev0222fba2014-02-09 23:16:02 -080065 */
Alexander Afanasyev90164962014-03-06 08:29:59 +000066typedef function<void (const InterestFilter&, const Interest&)> OnInterest;
Alexander Afanasyev0222fba2014-02-09 23:16:02 -080067
68/**
Alexander Afanasyev984ad192014-05-02 19:11:15 -070069 * @brief Callback called when registerPrefix or setInterestFilter command succeeds
Alexander Afanasyev0222fba2014-02-09 23:16:02 -080070 */
Alexander Afanasyev984ad192014-05-02 19:11:15 -070071typedef function<void(const Name&)> RegisterPrefixSuccessCallback;
Alexander Afanasyev0222fba2014-02-09 23:16:02 -080072
Alexander Afanasyev984ad192014-05-02 19:11:15 -070073/**
74 * @brief Callback called when registerPrefix or setInterestFilter command fails
75 */
76typedef function<void(const Name&, const std::string&)> RegisterPrefixFailureCallback;
77
78/**
79 * @brief Callback called when unregisterPrefix or unsetInterestFilter command succeeds
80 */
81typedef function<void()> UnregisterPrefixSuccessCallback;
82
83/**
84 * @brief Callback called when unregisterPrefix or unsetInterestFilter command fails
85 */
86typedef function<void(const std::string&)> UnregisterPrefixFailureCallback;
Alexander Afanasyev0222fba2014-02-09 23:16:02 -080087
88
89/**
90 * @brief Abstraction to communicate with local or remote NDN forwarder
Jeff Thompsonfe08e5a2013-08-13 11:15:59 -070091 */
Alexander Afanasyev8460afb2014-02-15 20:31:42 -080092class Face : noncopyable
93{
Jeff Thompsonaa4e6db2013-07-15 17:25:23 -070094public:
Alexander Afanasyevfdbfc6d2014-04-14 15:12:11 -070095 class Error : public std::runtime_error
96 {
97 public:
98 explicit
99 Error(const std::string& what)
100 : std::runtime_error(what)
101 {
102 }
103 };
Alexander Afanasyevb790d952014-01-24 12:07:53 -0800104
105 /**
Alexander Afanasyev691c3ce2014-04-23 14:28:04 -0700106 * @brief Create a new Face using the default transport (UnixTransport)
107 *
Steve DiBenedettoc07b3a22014-03-19 12:32:52 -0600108 * @throws ConfigFile::Error on configuration file parse failure
109 * @throws Face::Error on unsupported protocol
Alexander Afanasyevb790d952014-01-24 12:07:53 -0800110 */
Alexander Afanasyevf7ca3202014-02-14 22:28:31 -0800111 Face();
Alexander Afanasyeve2e0d752014-01-03 13:30:30 -0800112
113 /**
Alexander Afanasyev691c3ce2014-04-23 14:28:04 -0700114 * @brief Create a new Face using the default transport (UnixTransport)
115 *
116 * @deprecated This constructor is deprecated. Use `Face(boost::asio::io_service&)`
117 * instead.
118 *
119 * @param ioService A shared pointer to boost::io_service object that should control all
120 * IO operations
Steve DiBenedettoc07b3a22014-03-19 12:32:52 -0600121 * @throws ConfigFile::Error on configuration file parse failure
122 * @throws Face::Error on unsupported protocol
Jeff Thompsonfe08e5a2013-08-13 11:15:59 -0700123 */
Alexander Afanasyev9c578182014-05-14 17:28:28 -0700124 DEPRECATED(
Alexander Afanasyevf7ca3202014-02-14 22:28:31 -0800125 explicit
Alexander Afanasyev9c578182014-05-14 17:28:28 -0700126 Face(const shared_ptr<boost::asio::io_service>& ioService));
Alexander Afanasyev7682ccb2014-02-20 10:29:35 -0800127
Jeff Thompsonfe08e5a2013-08-13 11:15:59 -0700128 /**
Alexander Afanasyev691c3ce2014-04-23 14:28:04 -0700129 * @brief Create a new Face using the default transport (UnixTransport)
130 *
131 * @par Usage examples:
132 *
133 * Face face1;
134 * Face face2(face1.getIoService());
135 *
136 * // Now the following ensures that events on both faces are processed
137 * face1.processEvents();
138 * // or face1.getIoService().run();
139 *
140 * @par or
141 *
142 * boost::asio::io_service ioService;
143 * Face face1(ioService);
144 * Face face2(ioService);
145 * ...
146 *
147 * ioService.run();
148 *
149 * @param ioService A reference to boost::io_service object that should control all
150 * IO operations.
151 * @throws ConfigFile::Error on configuration file parse failure
152 * @throws Face::Error on unsupported protocol
153 */
154 explicit
155 Face(boost::asio::io_service& ioService);
156
157 /**
158 * @brief Create a new Face using TcpTransport
159 *
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700160 * @param host The host of the NDN forwarder
161 * @param port (optional) The port or service name of the NDN forwarder (**default**: "6363")
162 *
Steve DiBenedettoc07b3a22014-03-19 12:32:52 -0600163 * @throws Face::Error on unsupported protocol
Jeff Thompsonfe08e5a2013-08-13 11:15:59 -0700164 */
Alexander Afanasyev7682ccb2014-02-20 10:29:35 -0800165 Face(const std::string& host, const std::string& port = "6363");
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800166
167 /**
Alexander Afanasyev691c3ce2014-04-23 14:28:04 -0700168 * @brief Create a new Face using the given Transport
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700169 *
170 * @param transport A shared_ptr to a Transport object used for communication
171 *
Steve DiBenedettoc07b3a22014-03-19 12:32:52 -0600172 * @throws Face::Error on unsupported protocol
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800173 */
Alexander Afanasyevf7ca3202014-02-14 22:28:31 -0800174 explicit
175 Face(const shared_ptr<Transport>& transport);
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800176
177 /**
Alexander Afanasyev691c3ce2014-04-23 14:28:04 -0700178 * @brief Create a new Face using the given Transport and IO service object
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800179 *
Alexander Afanasyev691c3ce2014-04-23 14:28:04 -0700180 * @sa Face(boost::asio::io_service&)
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800181 *
Steve DiBenedettoc07b3a22014-03-19 12:32:52 -0600182 * @throws Face::Error on unsupported protocol
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800183 */
184 Face(const shared_ptr<Transport>& transport,
Alexander Afanasyev691c3ce2014-04-23 14:28:04 -0700185 boost::asio::io_service& ioService);
Alexander Afanasyev7682ccb2014-02-20 10:29:35 -0800186
Jeff Thompson4fe45512013-08-23 14:06:38 -0700187 /**
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800188 * @brief Express Interest
189 *
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700190 * @param interest An Interest to be expressed
191 * @param onData Callback to be called when a matching data packet is received
192 * @param onTimeout (optional) A function object to call if the interest times out
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800193 *
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700194 * @return The pending interest ID which can be used with removePendingInterest
Alexander Afanasyev49bb1fb2014-07-21 12:54:01 -0700195 *
196 * @throws Error when Interest size exceeds maximum limit (MAX_NDN_PACKET_SIZE)
Jeff Thompson4fe45512013-08-23 14:06:38 -0700197 */
Alexander Afanasyevb790d952014-01-24 12:07:53 -0800198 const PendingInterestId*
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800199 expressInterest(const Interest& interest,
200 const OnData& onData, const OnTimeout& onTimeout = OnTimeout());
Jeff Thompson4fe45512013-08-23 14:06:38 -0700201
202 /**
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800203 * @brief Express Interest using name and Interest template
204 *
205 * @param name Name of the Interest
206 * @param tmpl Interest template to fill parameters
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700207 * @param onData Callback to be called when a matching data packet is received
208 * @param onTimeout (optional) A function object to call if the interest times out
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800209 *
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700210 * @return Opaque pending interest ID which can be used with removePendingInterest
Alexander Afanasyev49bb1fb2014-07-21 12:54:01 -0700211 *
212 * @throws Error when Interest size exceeds maximum limit (MAX_NDN_PACKET_SIZE)
Jeff Thompson7aec0252013-08-22 17:29:57 -0700213 */
Alexander Afanasyevb790d952014-01-24 12:07:53 -0800214 const PendingInterestId*
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800215 expressInterest(const Name& name,
Alexander Afanasyev7682ccb2014-02-20 10:29:35 -0800216 const Interest& tmpl,
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800217 const OnData& onData, const OnTimeout& onTimeout = OnTimeout());
Alexander Afanasyevfdbfc6d2014-04-14 15:12:11 -0700218
Jeff Thompson11095142013-10-01 16:20:28 -0700219 /**
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700220 * @brief Cancel previously expressed Interest
Alexander Afanasyev691c3ce2014-04-23 14:28:04 -0700221 *
Jeff Thompson11095142013-10-01 16:20:28 -0700222 * @param pendingInterestId The ID returned from expressInterest.
223 */
224 void
Alexander Afanasyev7682ccb2014-02-20 10:29:35 -0800225 removePendingInterest(const PendingInterestId* pendingInterestId);
Alexander Afanasyevfdbfc6d2014-04-14 15:12:11 -0700226
Jeff Thompson432c8be2013-08-09 16:16:08 -0700227 /**
Alexander Afanasyev6fcdde22014-08-22 19:03:36 -0700228 * @brief Get number of pending Interests
229 */
230 size_t
231 getNPendingInterests() const;
232
233 /**
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700234 * @brief Set InterestFilter to dispatch incoming matching interest to onInterest
235 * callback and register the filtered prefix with the connected NDN forwarder
236 *
237 * This version of setInterestFilter combines setInterestFilter and registerPrefix
238 * operations and is intended to be used when only one filter for the same prefix needed
239 * to be set. When multiple names sharing the same prefix should be dispatched to
240 * different callbacks, use one registerPrefix call, followed (in onSuccess callback) by
241 * a series of setInterestFilter calls.
Alexander Afanasyev691c3ce2014-04-23 14:28:04 -0700242 *
Alexander Afanasyev90164962014-03-06 08:29:59 +0000243 * @param interestFilter Interest filter (prefix part will be registered with the forwarder)
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700244 * @param onInterest A callback to be called when a matching interest is received
245 * @param onSuccess A callback to be called when prefixRegister command succeeds
246 * @param onFailure A callback to be called when prefixRegister command fails
Alexander Afanasyev0866f512014-08-11 13:25:09 -0700247 * @param flags (optional) RIB flags (not used when direct FIB management is requested)
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700248 * @param certificate (optional) A certificate under which the prefix registration
Junxiao Shi6a90f372014-10-13 20:29:30 -0700249 * command is signed. When omitted, a default certificate of
250 * the default identity is used to sign the registration command
Alexander Afanasyev691c3ce2014-04-23 14:28:04 -0700251 *
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700252 * @return Opaque registered prefix ID which can be used with unsetInterestFilter or
253 * removeRegisteredPrefix
Jeff Thompson86507bc2013-08-23 20:51:38 -0700254 */
Alexander Afanasyevb790d952014-01-24 12:07:53 -0800255 const RegisteredPrefixId*
Alexander Afanasyev90164962014-03-06 08:29:59 +0000256 setInterestFilter(const InterestFilter& interestFilter,
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800257 const OnInterest& onInterest,
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700258 const RegisterPrefixSuccessCallback& onSuccess,
259 const RegisterPrefixFailureCallback& onFailure,
Alexander Afanasyev0866f512014-08-11 13:25:09 -0700260 const IdentityCertificate& certificate = IdentityCertificate(),
261 uint64_t flags = nfd::ROUTE_FLAG_CHILD_INHERIT);
Jeff Thompson11095142013-10-01 16:20:28 -0700262
263 /**
Alexander Afanasyev1b01c312014-05-26 16:58:10 +0300264 * @brief Set InterestFilter to dispatch incoming matching interest to onInterest
265 * callback and register the filtered prefix with the connected NDN forwarder
266 *
267 * This version of setInterestFilter combines setInterestFilter and registerPrefix
268 * operations and is intended to be used when only one filter for the same prefix needed
269 * to be set. When multiple names sharing the same prefix should be dispatched to
270 * different callbacks, use one registerPrefix call, followed (in onSuccess callback) by
271 * a series of setInterestFilter calls.
272 *
273 * @param interestFilter Interest filter (prefix part will be registered with the forwarder)
274 * @param onInterest A callback to be called when a matching interest is received
275 * @param onFailure A callback to be called when prefixRegister command fails
Alexander Afanasyev0866f512014-08-11 13:25:09 -0700276 * @param flags (optional) RIB flags (not used when direct FIB management is requested)
Alexander Afanasyev1b01c312014-05-26 16:58:10 +0300277 * @param certificate (optional) A certificate under which the prefix registration
Junxiao Shi6a90f372014-10-13 20:29:30 -0700278 * command is signed. When omitted, a default certificate of
279 * the default identity is used to sign the registration command
Alexander Afanasyev1b01c312014-05-26 16:58:10 +0300280 *
281 * @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,
Yingdi Yue66bf2a2014-04-28 17:07:36 -0700286 const OnInterest& onInterest,
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700287 const RegisterPrefixFailureCallback& onFailure,
Alexander Afanasyev0866f512014-08-11 13:25:09 -0700288 const IdentityCertificate& certificate = IdentityCertificate(),
289 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
Junxiao Shi6a90f372014-10-13 20:29:30 -0700305 * @param identity A signing identity. A prefix registration command is signed
306 * under the default certificate of this identity
Alexander Afanasyev0866f512014-08-11 13:25:09 -0700307 * @param flags (optional) RIB flags (not used when direct FIB management is requested)
Yingdi Yue66bf2a2014-04-28 17:07:36 -0700308 *
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700309 * @return Opaque registered prefix ID which can be used with removeRegisteredPrefix
Yingdi Yue66bf2a2014-04-28 17:07:36 -0700310 */
311 const RegisteredPrefixId*
Alexander Afanasyev90164962014-03-06 08:29:59 +0000312 setInterestFilter(const InterestFilter& interestFilter,
Yingdi Yue66bf2a2014-04-28 17:07:36 -0700313 const OnInterest& onInterest,
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700314 const RegisterPrefixSuccessCallback& onSuccess,
315 const RegisterPrefixFailureCallback& onFailure,
Alexander Afanasyev0866f512014-08-11 13:25:09 -0700316 const Name& identity,
317 uint64_t flags = nfd::ROUTE_FLAG_CHILD_INHERIT);
Yingdi Yue66bf2a2014-04-28 17:07:36 -0700318
319 /**
Alexander Afanasyev1b01c312014-05-26 16:58:10 +0300320 * @brief Set InterestFilter to dispatch incoming matching interest to onInterest
321 * callback and register the filtered prefix with the connected NDN forwarder
322 *
323 * This version of setInterestFilter combines setInterestFilter and registerPrefix
324 * operations and is intended to be used when only one filter for the same prefix needed
325 * to be set. When multiple names sharing the same prefix should be dispatched to
326 * different callbacks, use one registerPrefix call, followed (in onSuccess callback) by
327 * a series of setInterestFilter calls.
328 *
329 * @param interestFilter Interest filter (prefix part will be registered with the forwarder)
330 * @param onInterest A callback to be called when a matching interest is received
331 * @param onFailure A callback to be called when prefixRegister command fails
Junxiao Shi6a90f372014-10-13 20:29:30 -0700332 * @param identity A signing identity. A prefix registration command is signed
333 * under the default certificate of this identity
Alexander Afanasyev0866f512014-08-11 13:25:09 -0700334 * @param flags (optional) RIB flags (not used when direct FIB management is requested)
Alexander Afanasyev1b01c312014-05-26 16:58:10 +0300335 *
336 * @return Opaque registered prefix ID which can be used with removeRegisteredPrefix
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700337 */
338 const RegisteredPrefixId*
339 setInterestFilter(const InterestFilter& interestFilter,
340 const OnInterest& onInterest,
341 const RegisterPrefixFailureCallback& onFailure,
Alexander Afanasyev0866f512014-08-11 13:25:09 -0700342 const Name& identity,
343 uint64_t flags = nfd::ROUTE_FLAG_CHILD_INHERIT);
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700344
345 /**
346 * @brief Set InterestFilter to dispatch incoming matching interest to onInterest callback
347 *
348 * @param interestFilter Interest
349 * @param onInterest A callback to be called when a matching interest is received
350 *
351 * This method modifies library's FIB only, and does not register the prefix with the
352 * forwarder. It will always succeed. To register prefix with the forwarder, use
353 * registerPrefix, or use the setInterestFilter overload taking two callbacks.
354 *
355 * @return Opaque interest filter ID which can be used with unsetInterestFilter
356 */
357 const InterestFilterId*
358 setInterestFilter(const InterestFilter& interestFilter,
359 const OnInterest& onInterest);
360
361
362 /**
363 * @brief Register prefix with the connected NDN forwarder
364 *
365 * This method only modifies forwarder's RIB (or FIB) and does not associate any
366 * onInterest callbacks. Use setInterestFilter method to dispatch incoming Interests to
367 * the right callbacks.
368 *
369 * @param prefix A prefix to register with the connected NDN forwarder
370 * @param onSuccess A callback to be called when prefixRegister command succeeds
371 * @param onFailure A callback to be called when prefixRegister command fails
372 * @param certificate (optional) A certificate under which the prefix registration
Junxiao Shi6a90f372014-10-13 20:29:30 -0700373 * command is signed. When omitted, a default certificate of
374 * the default identity is used to sign the registration command
Alexander Afanasyev0866f512014-08-11 13:25:09 -0700375 * @param flags (optional) RIB flags (not used when direct FIB management is requested)
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700376 *
377 * @return The registered prefix ID which can be used with unregisterPrefix
378 */
379 const RegisteredPrefixId*
380 registerPrefix(const Name& prefix,
381 const RegisterPrefixSuccessCallback& onSuccess,
382 const RegisterPrefixFailureCallback& onFailure,
Alexander Afanasyev0866f512014-08-11 13:25:09 -0700383 const IdentityCertificate& certificate = IdentityCertificate(),
384 uint64_t flags = nfd::ROUTE_FLAG_CHILD_INHERIT);
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700385
386 /**
387 * @brief Register prefix with the connected NDN forwarder and call onInterest when a matching
388 * interest is received.
389 *
390 * This method only modifies forwarder's RIB (or FIB) and does not associate any
391 * onInterest callbacks. Use setInterestFilter method to dispatch incoming Interests to
392 * the right callbacks.
393 *
394 * @param prefix A prefix to register with the connected NDN forwarder
395 * @param onSuccess A callback to be called when prefixRegister command succeeds
396 * @param onFailure A callback to be called when prefixRegister command fails
Junxiao Shi6a90f372014-10-13 20:29:30 -0700397 * @param identity A signing identity. A prefix registration command is signed
398 * under the default certificate of this identity
Alexander Afanasyev0866f512014-08-11 13:25:09 -0700399 * @param flags (optional) RIB flags (not used when direct FIB management is requested)
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700400 *
401 * @return The registered prefix ID which can be used with unregisterPrefix
402 */
403 const RegisteredPrefixId*
404 registerPrefix(const Name& prefix,
405 const RegisterPrefixSuccessCallback& onSuccess,
406 const RegisterPrefixFailureCallback& onFailure,
Alexander Afanasyev0866f512014-08-11 13:25:09 -0700407 const Name& identity,
408 uint64_t flags = nfd::ROUTE_FLAG_CHILD_INHERIT);
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700409
410 /**
Alexander Afanasyev1b01c312014-05-26 16:58:10 +0300411 * @brief Remove the registered prefix entry with the registeredPrefixId
Alexander Afanasyev691c3ce2014-04-23 14:28:04 -0700412 *
413 * This does not affect another registered prefix with a different registeredPrefixId,
414 * even it if has the same prefix name. If there is no entry with the
415 * registeredPrefixId, do nothing.
416 *
Alexander Afanasyevee8bb1e2014-05-02 17:39:54 -0700417 * unsetInterestFilter will use the same credentials as original
418 * setInterestFilter/registerPrefix command
419 *
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700420 * @param registeredPrefixId The ID returned from registerPrefix
Jeff Thompson11095142013-10-01 16:20:28 -0700421 */
422 void
Alexander Afanasyev7682ccb2014-02-20 10:29:35 -0800423 unsetInterestFilter(const RegisteredPrefixId* registeredPrefixId);
Alexander Afanasyeva557d5a2013-12-28 21:59:03 -0800424
Alexander Afanasyevee8bb1e2014-05-02 17:39:54 -0700425 /**
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700426 * @brief Remove previously set InterestFilter from library's FIB
427 *
428 * This method always succeeds and will **NOT** send any request to the connected
429 * forwarder.
430 *
431 * @param interestFilterId The ID returned from setInterestFilter.
432 */
433 void
434 unsetInterestFilter(const InterestFilterId* interestFilterId);
435
436 /**
437 * @brief Deregister prefix from RIB (or FIB)
438 *
439 * unregisterPrefix will use the same credentials as original
440 * setInterestFilter/registerPrefix command
441 *
442 * If registeredPrefixId was obtained using setInterestFilter, the corresponding
443 * InterestFilter will be unset too.
444 *
Alexander Afanasyev770827c2014-05-13 17:42:55 -0700445 * @param registeredPrefixId The ID returned from registerPrefix
446 * @param onSuccess Callback to be called when operation succeeds
447 * @param onFailure Callback to be called when operation fails
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700448 */
449 void
450 unregisterPrefix(const RegisteredPrefixId* registeredPrefixId,
451 const UnregisterPrefixSuccessCallback& onSuccess,
452 const UnregisterPrefixFailureCallback& onFailure);
453
454 /**
Alexander Afanasyevee8bb1e2014-05-02 17:39:54 -0700455 * @brief (FOR DEBUG PURPOSES ONLY) Request direct NFD FIB management
456 */
Yingdi Yue66bf2a2014-04-28 17:07:36 -0700457 void
Alexander Afanasyevee8bb1e2014-05-02 17:39:54 -0700458 setDirectFibManagement(bool isDirectFibManagementRequested = false);
Yingdi Yue66bf2a2014-04-28 17:07:36 -0700459
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800460 /**
Alexander Afanasyeva557d5a2013-12-28 21:59:03 -0800461 * @brief Publish data packet
462 *
Alexander Afanasyev691c3ce2014-04-23 14:28:04 -0700463 * This method can be called to satisfy the incoming Interest or to put Data packet into
Alexander Afanasyev6a05b4b2014-07-18 17:23:00 -0700464 * the cache of the local NDN forwarder.
465 *
466 * @param data Data packet to publish. It is highly recommended to use Data packet that
467 * was created using make_shared<Data>(...). Otherwise, put() will make an
468 * extra copy of the Data packet to ensure validity of published Data until
469 * asynchronous put() operation finishes.
Alexander Afanasyev49bb1fb2014-07-21 12:54:01 -0700470 *
471 * @throws Error when Data size exceeds maximum limit (MAX_NDN_PACKET_SIZE)
Alexander Afanasyeva557d5a2013-12-28 21:59:03 -0800472 */
473 void
Alexander Afanasyev7682ccb2014-02-20 10:29:35 -0800474 put(const Data& data);
Alexander Afanasyevfdbfc6d2014-04-14 15:12:11 -0700475
Jeff Thompson86507bc2013-08-23 20:51:38 -0700476 /**
Alexander Afanasyev691c3ce2014-04-23 14:28:04 -0700477 * @brief Process any data to receive or call timeout callbacks.
Alexander Afanasyeva557d5a2013-12-28 21:59:03 -0800478 *
479 * This call will block forever (default timeout == 0) to process IO on the face.
480 * To exit, one expected to call face.shutdown() from one of the callback methods.
481 *
Alexander Afanasyev691c3ce2014-04-23 14:28:04 -0700482 * If positive timeout is specified, then processEvents will exit after this timeout, if
483 * not stopped earlier with face.shutdown() or when all active events finish. The call
484 * can be called repeatedly, if desired.
Alexander Afanasyeva557d5a2013-12-28 21:59:03 -0800485 *
Alexander Afanasyev691c3ce2014-04-23 14:28:04 -0700486 * If negative timeout is specified, then processEvents will not block and process only
487 * pending events.
Alexander Afanasyevf75a0aa2014-01-09 14:29:22 -0800488 *
Alexander Afanasyev984ad192014-05-02 19:11:15 -0700489 * @param timeout maximum time to block the thread
Alexander Afanasyev691c3ce2014-04-23 14:28:04 -0700490 * @param keepThread Keep thread in a blocked state (in event processing), even when
491 * there are no outstanding events (e.g., no Interest/Data is expected)
492 *
493 * @throw This may throw an exception for reading data or in the callback for processing
494 * the data. If you call this from an main event loop, you may want to catch and
495 * log/disregard all exceptions.
Jeff Thompson432c8be2013-08-09 16:16:08 -0700496 */
Alexander Afanasyevfdbfc6d2014-04-14 15:12:11 -0700497 void
Alexander Afanasyevaa0e7da2014-03-17 14:37:33 -0700498 processEvents(const time::milliseconds& timeout = time::milliseconds::zero(),
499 bool keepThread = false);
Jeff Thompson432c8be2013-08-09 16:16:08 -0700500
Alexander Afanasyev691c3ce2014-04-23 14:28:04 -0700501 /**
502 * @brief Shutdown face operations
503 *
504 * This method cancels all pending operations and closes connection to NDN Forwarder.
505 *
506 * Note that this method does not stop IO service and if the same IO service is shared
507 * between multiple Faces or with other IO objects (e.g., Scheduler).
508 */
Alexander Afanasyevfdbfc6d2014-04-14 15:12:11 -0700509 void
Jeff Thompson0050abe2013-09-17 12:50:25 -0700510 shutdown();
Yingdi Yu0d920812014-01-30 14:50:57 -0800511
Alexander Afanasyev691c3ce2014-04-23 14:28:04 -0700512 /**
513 * @brief Get shared_ptr of the IO service object
514 *
515 * @deprecated Use getIoService instead
516 */
Alexander Afanasyev9c578182014-05-14 17:28:28 -0700517 DEPRECATED(
Alexander Afanasyevfdbfc6d2014-04-14 15:12:11 -0700518 shared_ptr<boost::asio::io_service>
Alexander Afanasyev9c578182014-05-14 17:28:28 -0700519 ioService())
Alexander Afanasyev691c3ce2014-04-23 14:28:04 -0700520 {
521 return m_ioService;
522 }
523
524 /**
525 * @brief Get reference to IO service object
526 */
527 boost::asio::io_service&
528 getIoService()
529 {
530 return *m_ioService;
531 }
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800532
533private:
Steve DiBenedettoc07b3a22014-03-19 12:32:52 -0600534 /**
535 * @throws Face::Error on unsupported protocol
536 */
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800537 void
Alexander Afanasyev7682ccb2014-02-20 10:29:35 -0800538 construct(const shared_ptr<Transport>& transport,
Alexander Afanasyev505646e2014-02-24 20:13:37 -0800539 const shared_ptr<boost::asio::io_service>& ioService);
Steve DiBenedettoc07b3a22014-03-19 12:32:52 -0600540
541 bool
542 isSupportedNfdProtocol(const std::string& protocol);
543
544 bool
545 isSupportedNrdProtocol(const std::string& protocol);
546
Alexander Afanasyev691c3ce2014-04-23 14:28:04 -0700547 class ProcessEventsTimeout
548 {
549 };
550
Alexander Afanasyevfdbfc6d2014-04-14 15:12:11 -0700551 void
Alexander Afanasyev6d48bc12014-02-18 00:10:51 -0800552 onReceiveElement(const Block& wire);
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800553
Alexander Afanasyev7dced462014-03-19 15:12:32 -0700554 void
555 asyncShutdown();
Alexander Afanasyevfdbfc6d2014-04-14 15:12:11 -0700556
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800557 static void
558 fireProcessEventsTimeout(const boost::system::error_code& error);
559
Jeff Thompsonb982b6d2013-07-15 18:15:45 -0700560private:
Alexander Afanasyevf39c5372014-02-17 19:42:56 -0800561 shared_ptr<boost::asio::io_service> m_ioService;
Alexander Afanasyevfdbfc6d2014-04-14 15:12:11 -0700562
Alexander Afanasyevf39c5372014-02-17 19:42:56 -0800563 shared_ptr<Transport> m_transport;
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800564
Alexander Afanasyev258ec2b2014-05-14 16:15:37 -0700565 shared_ptr<nfd::Controller> m_nfdController;
Alexander Afanasyevee8bb1e2014-05-02 17:39:54 -0700566 bool m_isDirectNfdFibManagementRequested;
Steve DiBenedettoc07b3a22014-03-19 12:32:52 -0600567
Alexander Afanasyev258ec2b2014-05-14 16:15:37 -0700568 class Impl;
569 shared_ptr<Impl> m_impl;
Jeff Thompsonaa4e6db2013-07-15 17:25:23 -0700570};
571
Steve DiBenedettoc07b3a22014-03-19 12:32:52 -0600572inline bool
573Face::isSupportedNfdProtocol(const std::string& protocol)
574{
575 return protocol == "nfd-0.1";
576}
577
578inline bool
579Face::isSupportedNrdProtocol(const std::string& protocol)
580{
581 return protocol == "nrd-0.1";
582}
583
Alexander Afanasyevee8bb1e2014-05-02 17:39:54 -0700584inline void
585Face::setDirectFibManagement(bool isDirectFibManagementRequested/* = false*/)
Steve DiBenedettoc07b3a22014-03-19 12:32:52 -0600586{
Alexander Afanasyevee8bb1e2014-05-02 17:39:54 -0700587 m_isDirectNfdFibManagementRequested = isDirectFibManagementRequested;
Steve DiBenedettoc07b3a22014-03-19 12:32:52 -0600588}
589
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800590} // namespace ndn
Jeff Thompsonaa4e6db2013-07-15 17:25:23 -0700591
Alexander Afanasyev0222fba2014-02-09 23:16:02 -0800592#endif // NDN_FACE_HPP