blob: 61d872fbf61fd4dd1f56bbe41eb47f094d3f23b0 [file] [log] [blame]
Jeff Thompson25b4e612013-10-10 16:03:24 -07001/* -*- Mode:C++; c-file-style:"gnu"; indent-tabs-mode:nil -*- */
Jeff Thompsonaa4e6db2013-07-15 17:25:23 -07002/**
Jeff Thompson7687dc02013-09-13 11:54:07 -07003 * Copyright (C) 2013 Regents of the University of California.
4 * @author: Jeff Thompson <jefft0@remap.ucla.edu>
Jeff Thompsonaa4e6db2013-07-15 17:25:23 -07005 * See COPYING for copyright and distribution information.
6 */
7
Jeff Thompsonb9e3c8e2013-08-02 11:42:51 -07008#ifndef NDN_FACE_HPP
Jeff Thompsona0d18c92013-08-06 13:55:32 -07009#define NDN_FACE_HPP
Jeff Thompsonaa4e6db2013-07-15 17:25:23 -070010
Jeff Thompsonbf50a1a2013-08-20 18:01:01 -070011#include "node.hpp"
Alexander Afanasyeve2e0d752014-01-03 13:30:30 -080012#include "transport/transport.hpp"
13#include "transport/unix-transport.hpp"
Alexander Afanasyev20d2c582014-01-26 15:32:51 -080014#include "transport/tcp-transport.hpp"
Jeff Thompsonbeb8b7d2013-07-16 15:49:21 -070015
Jeff Thompsonaa4e6db2013-07-15 17:25:23 -070016namespace ndn {
17
Jeff Thompsonfe08e5a2013-08-13 11:15:59 -070018/**
19 * The Face class provides the main methods for NDN communication.
20 */
Jeff Thompsonbf50a1a2013-08-20 18:01:01 -070021class Face {
Jeff Thompsonaa4e6db2013-07-15 17:25:23 -070022public:
Jeff Thompsonfe08e5a2013-08-13 11:15:59 -070023 /**
Alexander Afanasyevb790d952014-01-24 12:07:53 -080024 * @brief Create a new Face for communication with an NDN hub using the default TcpTransport.
Alexander Afanasyeve2e0d752014-01-03 13:30:30 -080025 */
26 Face()
Alexander Afanasyevb790d952014-01-24 12:07:53 -080027 : node_(ptr_lib::shared_ptr<UnixTransport>(new UnixTransport()))
28 {
29 }
30
31 /**
32 * @brief Create a new Face for communication with an NDN hub using the default Transport.
33 * @param ioService A shared pointer to boost::io_service object that should control all IO operations
34 */
35 Face(const ptr_lib::shared_ptr<boost::asio::io_service> &ioService)
36 : node_(ptr_lib::shared_ptr<UnixTransport>(new UnixTransport()), ioService)
37 {
38 }
39
40 /**
41 * Create a new Face for communication with an NDN hub with the given Transport object and connectionInfo.
42 * @param transport A shared_ptr to a Transport object used for communication.
43 */
44 Face(const ptr_lib::shared_ptr<Transport>& transport)
45 : node_(transport)
Alexander Afanasyeve2e0d752014-01-03 13:30:30 -080046 {
47 }
48
49 /**
Jeff Thompson10e34382013-08-22 13:34:46 -070050 * Create a new Face for communication with an NDN hub with the given Transport object and connectionInfo.
51 * @param transport A shared_ptr to a Transport object used for communication.
Alexander Afanasyevb790d952014-01-24 12:07:53 -080052 * @param ioService A shared pointer to boost::io_service object that should control all IO operations
Jeff Thompsonfe08e5a2013-08-13 11:15:59 -070053 */
Alexander Afanasyevb790d952014-01-24 12:07:53 -080054 Face(const ptr_lib::shared_ptr<Transport>& transport, const ptr_lib::shared_ptr<boost::asio::io_service> &ioService)
55 : node_(transport, ioService)
Jeff Thompsonb982b6d2013-07-15 18:15:45 -070056 {
Jeff Thompsonb982b6d2013-07-15 18:15:45 -070057 }
58
Jeff Thompsonfe08e5a2013-08-13 11:15:59 -070059 /**
Jeff Thompson86507bc2013-08-23 20:51:38 -070060 * Create a new Face for communication with an NDN hub at host:port using the default TcpTransport.
Jeff Thompsonfe08e5a2013-08-13 11:15:59 -070061 * @param host The host of the NDN hub.
Alexander Afanasyev20d2c582014-01-26 15:32:51 -080062 * @param port The port or service name of the NDN hub. If omitted. use 6363.
Jeff Thompsonfe08e5a2013-08-13 11:15:59 -070063 */
Alexander Afanasyev20d2c582014-01-26 15:32:51 -080064 Face(const std::string &host, const std::string &port = "6363")
65 : node_(ptr_lib::shared_ptr<TcpTransport>(new TcpTransport(host, port)))
66 {
67 }
68
Jeff Thompson4fe45512013-08-23 14:06:38 -070069 /**
70 * Send the Interest through the transport, read the entire response and call onData(interest, data).
71 * @param interest A reference to the Interest. This copies the Interest.
72 * @param onData A function object to call when a matching data packet is received. This copies the function object, so you may need to
73 * use func_lib::ref() as appropriate.
74 * @param onTimeout A function object to call if the interest times out. If onTimeout is an empty OnTimeout(), this does not use it.
75 * This copies the function object, so you may need to use func_lib::ref() as appropriate.
Jeff Thompson11095142013-10-01 16:20:28 -070076 * @return The pending interest ID which can be used with removePendingInterest.
Jeff Thompson4fe45512013-08-23 14:06:38 -070077 */
Alexander Afanasyevb790d952014-01-24 12:07:53 -080078 const PendingInterestId*
Jeff Thompson978c1522013-11-12 23:03:10 -080079 expressInterest
Alexander Afanasyeve2e0d752014-01-03 13:30:30 -080080 (const Interest& interest, const OnData& onData, const OnTimeout& onTimeout = OnTimeout())
Jeff Thompson4fe45512013-08-23 14:06:38 -070081 {
Alexander Afanasyeve2e0d752014-01-03 13:30:30 -080082 return node_.expressInterest(interest, onData, onTimeout);
Jeff Thompson4fe45512013-08-23 14:06:38 -070083 }
84
85 /**
Jeff Thompsonc172be32013-07-16 15:08:05 -070086 * Encode name as an Interest. If interestTemplate is not 0, use its interest selectors.
Jeff Thompson7aec0252013-08-22 17:29:57 -070087 * Send the interest through the transport, read the entire response and call onData(interest, data).
Jeff Thompson4fe45512013-08-23 14:06:38 -070088 * @param name A reference to a Name for the interest. This copies the Name.
Jeff Thompsonc172be32013-07-16 15:08:05 -070089 * @param interestTemplate if not 0, copy interest selectors from the template. This does not keep a pointer to the Interest object.
Jeff Thompson7aec0252013-08-22 17:29:57 -070090 * @param onData A function object to call when a matching data packet is received. This copies the function object, so you may need to
Alexander Afanasyevb790d952014-01-24 12:07:53 -080091 * use func_lib::ref() as appropriate.
Jeff Thompson7aec0252013-08-22 17:29:57 -070092 * @param onTimeout A function object to call if the interest times out. If onTimeout is an empty OnTimeout(), this does not use it.
Alexander Afanasyevb790d952014-01-24 12:07:53 -080093 * This copies the function object, so you may need to use func_lib::ref() as appropriate.
Jeff Thompsonc172be32013-07-16 15:08:05 -070094 */
Alexander Afanasyevb790d952014-01-24 12:07:53 -080095 const PendingInterestId*
Jeff Thompson978c1522013-11-12 23:03:10 -080096 expressInterest
Alexander Afanasyeve2e0d752014-01-03 13:30:30 -080097 (const Name& name, const Interest *interestTemplate, const OnData& onData, const OnTimeout& onTimeout = OnTimeout());
Jeff Thompson7aec0252013-08-22 17:29:57 -070098
99 /**
100 * Encode name as an Interest, using a default interest lifetime.
101 * Send the interest through the transport, read the entire response and call onData(interest, data).
Jeff Thompson4fe45512013-08-23 14:06:38 -0700102 * @param name A reference to a Name for the interest. This copies the Name.
Jeff Thompson7aec0252013-08-22 17:29:57 -0700103 * @param onData A function object to call when a matching data packet is received. This copies the function object, so you may need to
104 * use func_lib::ref() as appropriate.
105 * @param onTimeout A function object to call if the interest times out. If onTimeout is an empty OnTimeout(), this does not use it.
106 * This copies the function object, so you may need to use func_lib::ref() as appropriate.
Jeff Thompson978c1522013-11-12 23:03:10 -0800107 * @param wireFormat A WireFormat object used to encode the message. If omitted, use WireFormat getDefaultWireFormat().
Jeff Thompson11095142013-10-01 16:20:28 -0700108 * @return The pending interest ID which can be used with removePendingInterest.
Jeff Thompson7aec0252013-08-22 17:29:57 -0700109 */
Alexander Afanasyevb790d952014-01-24 12:07:53 -0800110 const PendingInterestId*
Jeff Thompson978c1522013-11-12 23:03:10 -0800111 expressInterest
Alexander Afanasyeve2e0d752014-01-03 13:30:30 -0800112 (const Name& name, const OnData& onData, const OnTimeout& onTimeout = OnTimeout())
Jeff Thompson7aec0252013-08-22 17:29:57 -0700113 {
Alexander Afanasyeve2e0d752014-01-03 13:30:30 -0800114 return expressInterest(name, 0, onData, onTimeout);
Jeff Thompson11095142013-10-01 16:20:28 -0700115 }
116
117 /**
118 * Remove the pending interest entry with the pendingInterestId from the pending interest table.
119 * This does not affect another pending interest with a different pendingInterestId, even it if has the same interest name.
120 * If there is no entry with the pendingInterestId, do nothing.
121 * @param pendingInterestId The ID returned from expressInterest.
122 */
123 void
Alexander Afanasyevb790d952014-01-24 12:07:53 -0800124 removePendingInterest(const PendingInterestId* pendingInterestId)
Jeff Thompson11095142013-10-01 16:20:28 -0700125 {
126 node_.removePendingInterest(pendingInterestId);
Jeff Thompsoncdf7e252013-07-31 12:41:47 -0700127 }
128
Jeff Thompson432c8be2013-08-09 16:16:08 -0700129 /**
Jeff Thompson86507bc2013-08-23 20:51:38 -0700130 * Register prefix with the connected NDN hub and call onInterest when a matching interest is received.
131 * @param prefix A reference to a Name for the prefix to register. This copies the Name.
132 * @param onInterest A function object to call when a matching interest is received. This copies the function object, so you may need to
133 * use func_lib::ref() as appropriate.
Jeff Thompson590ec232013-09-18 15:55:56 -0700134 * @param onRegisterFailed A function object to call if failed to retrieve the connected hub’s ID or failed to register the prefix.
135 * This calls onRegisterFailed(prefix) where prefix is the prefix given to registerPrefix.
Jeff Thompson1f8a31a2013-09-30 16:18:47 -0700136 * @param flags The flags for finer control of which interests are forward to the application. If omitted, use
137 * the default flags defined by the default ForwardingFlags constructor.
Jeff Thompson978c1522013-11-12 23:03:10 -0800138 * @param wireFormat A WireFormat object used to encode the message. If omitted, use WireFormat getDefaultWireFormat().
Jeff Thompson11095142013-10-01 16:20:28 -0700139 * @return The registered prefix ID which can be used with removeRegisteredPrefix.
Jeff Thompson86507bc2013-08-23 20:51:38 -0700140 */
Alexander Afanasyevb790d952014-01-24 12:07:53 -0800141 const RegisteredPrefixId*
Alexander Afanasyevde2f6b52014-01-02 21:42:26 -0800142 setInterestFilter
Alexander Afanasyeve2e0d752014-01-03 13:30:30 -0800143 (const Name& prefix, const OnInterest& onInterest, const OnRegisterFailed& onRegisterFailed, const ForwardingFlags& flags = ForwardingFlags())
Jeff Thompson86507bc2013-08-23 20:51:38 -0700144 {
Alexander Afanasyeve2e0d752014-01-03 13:30:30 -0800145 return node_.registerPrefix(prefix, onInterest, onRegisterFailed, flags);
Jeff Thompson11095142013-10-01 16:20:28 -0700146 }
147
148 /**
149 * Remove the registered prefix entry with the registeredPrefixId from the pending interest table.
150 * This does not affect another registered prefix with a different registeredPrefixId, even it if has the same prefix name.
151 * If there is no entry with the registeredPrefixId, do nothing.
152 * @param registeredPrefixId The ID returned from registerPrefix.
153 */
154 void
Alexander Afanasyevb790d952014-01-24 12:07:53 -0800155 unsetInterestFilter(const RegisteredPrefixId *registeredPrefixId)
Jeff Thompson11095142013-10-01 16:20:28 -0700156 {
157 node_.removeRegisteredPrefix(registeredPrefixId);
Jeff Thompson86507bc2013-08-23 20:51:38 -0700158 }
Alexander Afanasyeva557d5a2013-12-28 21:59:03 -0800159
160 /**
161 * @brief Publish data packet
162 *
163 * This method can be called to satisfy the incoming Interest or to put Data packet into the cache
164 * of the local NDN forwarder
165 */
166 void
167 put(const Data &data)
168 {
169 node_.put(data);
170 }
Jeff Thompson86507bc2013-08-23 20:51:38 -0700171
172 /**
Jeff Thompsonbf50a1a2013-08-20 18:01:01 -0700173 * Process any data to receive or call timeout callbacks.
Alexander Afanasyeva557d5a2013-12-28 21:59:03 -0800174 *
175 * This call will block forever (default timeout == 0) to process IO on the face.
176 * To exit, one expected to call face.shutdown() from one of the callback methods.
177 *
Alexander Afanasyevf75a0aa2014-01-09 14:29:22 -0800178 * If positive timeout is specified, then processEvents will exit after this timeout,
179 * if not stopped earlier with face.shutdown() or when all active events finish.
Alexander Afanasyeva557d5a2013-12-28 21:59:03 -0800180 * The call can be called repeatedly, if desired.
181 *
Alexander Afanasyevf75a0aa2014-01-09 14:29:22 -0800182 * If negative timeout is specified, then processEvents will not block and process only pending
183 * events.
184 *
Jeff Thompson432c8be2013-08-09 16:16:08 -0700185 * @throw This may throw an exception for reading data or in the callback for processing the data. If you
186 * call this from an main event loop, you may want to catch and log/disregard all exceptions.
187 */
Jeff Thompson0050abe2013-09-17 12:50:25 -0700188 void
Alexander Afanasyevf75a0aa2014-01-09 14:29:22 -0800189 processEvents(Milliseconds timeout = 0, bool keepThread = false)
Jeff Thompsonbf50a1a2013-08-20 18:01:01 -0700190 {
191 // Just call Node's processEvents.
Alexander Afanasyevf75a0aa2014-01-09 14:29:22 -0800192 node_.processEvents(timeout, keepThread);
Jeff Thompsonbf50a1a2013-08-20 18:01:01 -0700193 }
Jeff Thompson432c8be2013-08-09 16:16:08 -0700194
Jeff Thompsonbf50a1a2013-08-20 18:01:01 -0700195 /**
196 * Shut down and disconnect this Face.
197 */
Jeff Thompson0050abe2013-09-17 12:50:25 -0700198 void
199 shutdown();
Jeff Thompson517ffa82013-08-05 16:04:34 -0700200
Jeff Thompsonb982b6d2013-07-15 18:15:45 -0700201private:
Jeff Thompsonbf50a1a2013-08-20 18:01:01 -0700202 Node node_;
Jeff Thompsonaa4e6db2013-07-15 17:25:23 -0700203};
204
205}
206
207#endif