blob: a0b3f0e57eacd6ccbc5b64748d163fd51a0d435c [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"
Jeff Thompsonfb29cda2013-08-24 10:26:54 -070012#include "transport/tcp-transport.hpp"
Jeff Thompsonbeb8b7d2013-07-16 15:49:21 -070013
Jeff Thompsonaa4e6db2013-07-15 17:25:23 -070014namespace ndn {
15
Jeff Thompsonfe08e5a2013-08-13 11:15:59 -070016/**
17 * The Face class provides the main methods for NDN communication.
18 */
Jeff Thompsonbf50a1a2013-08-20 18:01:01 -070019class Face {
Jeff Thompsonaa4e6db2013-07-15 17:25:23 -070020public:
Jeff Thompsonfe08e5a2013-08-13 11:15:59 -070021 /**
Jeff Thompson10e34382013-08-22 13:34:46 -070022 * Create a new Face for communication with an NDN hub with the given Transport object and connectionInfo.
23 * @param transport A shared_ptr to a Transport object used for communication.
24 * @param transport A shared_ptr to a Transport::ConnectionInfo to be used to connect to the transport.
Jeff Thompsonfe08e5a2013-08-13 11:15:59 -070025 */
Alexander Afanasyev0b688dc2013-12-18 16:43:37 -080026 Face(const ptr_lib::shared_ptr<Transport>& transport)
27 : node_(transport)
Jeff Thompsonb982b6d2013-07-15 18:15:45 -070028 {
Jeff Thompsonb982b6d2013-07-15 18:15:45 -070029 }
30
Jeff Thompsonfe08e5a2013-08-13 11:15:59 -070031 /**
Jeff Thompson86507bc2013-08-23 20:51:38 -070032 * Create a new Face for communication with an NDN hub at host:port using the default TcpTransport.
Jeff Thompsonfe08e5a2013-08-13 11:15:59 -070033 * @param host The host of the NDN hub.
Jeff Thompsonb629ddb2013-10-03 13:58:43 -070034 * @param port The port of the NDN hub. If omitted. use 6363.
Jeff Thompsonfe08e5a2013-08-13 11:15:59 -070035 */
Jeff Thompsonb629ddb2013-10-03 13:58:43 -070036 Face(const char *host, unsigned short port = 6363)
Alexander Afanasyev0b688dc2013-12-18 16:43:37 -080037 : node_(ptr_lib::shared_ptr<TcpTransport>(new TcpTransport(host, port)))
Jeff Thompsonb7d059d2013-07-31 10:59:51 -070038 {
39 }
Jeff Thompsonfb29cda2013-08-24 10:26:54 -070040
Jeff Thompson4fe45512013-08-23 14:06:38 -070041 /**
42 * Send the Interest through the transport, read the entire response and call onData(interest, data).
43 * @param interest A reference to the Interest. This copies the Interest.
44 * @param onData A function object to call when a matching data packet is received. This copies the function object, so you may need to
45 * use func_lib::ref() as appropriate.
46 * @param onTimeout A function object to call if the interest times out. If onTimeout is an empty OnTimeout(), this does not use it.
47 * This copies the function object, so you may need to use func_lib::ref() as appropriate.
Jeff Thompson978c1522013-11-12 23:03:10 -080048 * @param wireFormat A WireFormat object used to encode the message. If omitted, use WireFormat getDefaultWireFormat().
Jeff Thompson11095142013-10-01 16:20:28 -070049 * @return The pending interest ID which can be used with removePendingInterest.
Jeff Thompson4fe45512013-08-23 14:06:38 -070050 */
Jeff Thompson62992e42013-10-07 18:50:51 -070051 uint64_t
Jeff Thompson978c1522013-11-12 23:03:10 -080052 expressInterest
53 (const Interest& interest, const OnData& onData, const OnTimeout& onTimeout = OnTimeout(),
54 WireFormat& wireFormat = *WireFormat::getDefaultWireFormat())
Jeff Thompson4fe45512013-08-23 14:06:38 -070055 {
Jeff Thompson978c1522013-11-12 23:03:10 -080056 return node_.expressInterest(interest, onData, onTimeout, wireFormat);
Jeff Thompson4fe45512013-08-23 14:06:38 -070057 }
58
59 /**
Jeff Thompsonc172be32013-07-16 15:08:05 -070060 * Encode name as an Interest. If interestTemplate is not 0, use its interest selectors.
Jeff Thompson7aec0252013-08-22 17:29:57 -070061 * Send the interest through the transport, read the entire response and call onData(interest, data).
Jeff Thompson4fe45512013-08-23 14:06:38 -070062 * @param name A reference to a Name for the interest. This copies the Name.
Jeff Thompsonc172be32013-07-16 15:08:05 -070063 * @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 -070064 * @param onData A function object to call when a matching data packet is received. This copies the function object, so you may need to
65 * use func_lib::ref() as appropriate.
66 * @param onTimeout A function object to call if the interest times out. If onTimeout is an empty OnTimeout(), this does not use it.
67 * This copies the function object, so you may need to use func_lib::ref() as appropriate.
Jeff Thompson978c1522013-11-12 23:03:10 -080068 * @param wireFormat A WireFormat object used to encode the message. If omitted, use WireFormat getDefaultWireFormat().
Jeff Thompson11095142013-10-01 16:20:28 -070069 * @return The pending interest ID which can be used with removePendingInterest.
Jeff Thompsonc172be32013-07-16 15:08:05 -070070 */
Jeff Thompson62992e42013-10-07 18:50:51 -070071 uint64_t
Jeff Thompson978c1522013-11-12 23:03:10 -080072 expressInterest
73 (const Name& name, const Interest *interestTemplate, const OnData& onData, const OnTimeout& onTimeout = OnTimeout(),
74 WireFormat& wireFormat = *WireFormat::getDefaultWireFormat());
Jeff Thompson7aec0252013-08-22 17:29:57 -070075
76 /**
77 * Encode name as an Interest, using a default interest lifetime.
78 * Send the interest through the transport, read the entire response and call onData(interest, data).
Jeff Thompson4fe45512013-08-23 14:06:38 -070079 * @param name A reference to a Name for the interest. This copies the Name.
Jeff Thompson7aec0252013-08-22 17:29:57 -070080 * @param onData A function object to call when a matching data packet is received. This copies the function object, so you may need to
81 * use func_lib::ref() as appropriate.
82 * @param onTimeout A function object to call if the interest times out. If onTimeout is an empty OnTimeout(), this does not use it.
83 * This copies the function object, so you may need to use func_lib::ref() as appropriate.
Jeff Thompson978c1522013-11-12 23:03:10 -080084 * @param wireFormat A WireFormat object used to encode the message. If omitted, use WireFormat getDefaultWireFormat().
Jeff Thompson11095142013-10-01 16:20:28 -070085 * @return The pending interest ID which can be used with removePendingInterest.
Jeff Thompson7aec0252013-08-22 17:29:57 -070086 */
Jeff Thompson62992e42013-10-07 18:50:51 -070087 uint64_t
Jeff Thompson978c1522013-11-12 23:03:10 -080088 expressInterest
89 (const Name& name, const OnData& onData, const OnTimeout& onTimeout = OnTimeout(),
90 WireFormat& wireFormat = *WireFormat::getDefaultWireFormat())
Jeff Thompson7aec0252013-08-22 17:29:57 -070091 {
Jeff Thompson978c1522013-11-12 23:03:10 -080092 return expressInterest(name, 0, onData, onTimeout, wireFormat);
Jeff Thompson11095142013-10-01 16:20:28 -070093 }
94
95 /**
96 * Remove the pending interest entry with the pendingInterestId from the pending interest table.
97 * This does not affect another pending interest with a different pendingInterestId, even it if has the same interest name.
98 * If there is no entry with the pendingInterestId, do nothing.
99 * @param pendingInterestId The ID returned from expressInterest.
100 */
101 void
Jeff Thompson62992e42013-10-07 18:50:51 -0700102 removePendingInterest(uint64_t pendingInterestId)
Jeff Thompson11095142013-10-01 16:20:28 -0700103 {
104 node_.removePendingInterest(pendingInterestId);
Jeff Thompsoncdf7e252013-07-31 12:41:47 -0700105 }
106
Jeff Thompson432c8be2013-08-09 16:16:08 -0700107 /**
Jeff Thompson86507bc2013-08-23 20:51:38 -0700108 * Register prefix with the connected NDN hub and call onInterest when a matching interest is received.
109 * @param prefix A reference to a Name for the prefix to register. This copies the Name.
110 * @param onInterest A function object to call when a matching interest is received. This copies the function object, so you may need to
111 * use func_lib::ref() as appropriate.
Jeff Thompson590ec232013-09-18 15:55:56 -0700112 * @param onRegisterFailed A function object to call if failed to retrieve the connected hub’s ID or failed to register the prefix.
113 * This calls onRegisterFailed(prefix) where prefix is the prefix given to registerPrefix.
Jeff Thompson1f8a31a2013-09-30 16:18:47 -0700114 * @param flags The flags for finer control of which interests are forward to the application. If omitted, use
115 * the default flags defined by the default ForwardingFlags constructor.
Jeff Thompson978c1522013-11-12 23:03:10 -0800116 * @param wireFormat A WireFormat object used to encode the message. If omitted, use WireFormat getDefaultWireFormat().
Jeff Thompson11095142013-10-01 16:20:28 -0700117 * @return The registered prefix ID which can be used with removeRegisteredPrefix.
Jeff Thompson86507bc2013-08-23 20:51:38 -0700118 */
Jeff Thompson62992e42013-10-07 18:50:51 -0700119 uint64_t
Alexander Afanasyevde2f6b52014-01-02 21:42:26 -0800120 setInterestFilter
Jeff Thompson1f8a31a2013-09-30 16:18:47 -0700121 (const Name& prefix, const OnInterest& onInterest, const OnRegisterFailed& onRegisterFailed, const ForwardingFlags& flags = ForwardingFlags(),
Jeff Thompson6d7369b2013-09-19 14:40:21 -0700122 WireFormat& wireFormat = *WireFormat::getDefaultWireFormat())
Jeff Thompson86507bc2013-08-23 20:51:38 -0700123 {
Jeff Thompson11095142013-10-01 16:20:28 -0700124 return node_.registerPrefix(prefix, onInterest, onRegisterFailed, flags, wireFormat);
125 }
126
127 /**
128 * Remove the registered prefix entry with the registeredPrefixId from the pending interest table.
129 * This does not affect another registered prefix with a different registeredPrefixId, even it if has the same prefix name.
130 * If there is no entry with the registeredPrefixId, do nothing.
131 * @param registeredPrefixId The ID returned from registerPrefix.
132 */
133 void
Alexander Afanasyevde2f6b52014-01-02 21:42:26 -0800134 unsetInterestFilter(uint64_t registeredPrefixId)
Jeff Thompson11095142013-10-01 16:20:28 -0700135 {
136 node_.removeRegisteredPrefix(registeredPrefixId);
Jeff Thompson86507bc2013-08-23 20:51:38 -0700137 }
Jeff Thompson86507bc2013-08-23 20:51:38 -0700138
139 /**
Jeff Thompsonbf50a1a2013-08-20 18:01:01 -0700140 * Process any data to receive or call timeout callbacks.
Jeff Thompsonc7e07442013-08-19 15:25:43 -0700141 * This is non-blocking and will return immediately if there is no data to receive.
142 * You should repeatedly call this from an event loop, with calls to sleep as needed so that the loop doesn't use 100% of the CPU.
Jeff Thompson432c8be2013-08-09 16:16:08 -0700143 * @throw This may throw an exception for reading data or in the callback for processing the data. If you
144 * call this from an main event loop, you may want to catch and log/disregard all exceptions.
145 */
Jeff Thompson0050abe2013-09-17 12:50:25 -0700146 void
147 processEvents()
Jeff Thompsonbf50a1a2013-08-20 18:01:01 -0700148 {
149 // Just call Node's processEvents.
150 node_.processEvents();
151 }
Jeff Thompson432c8be2013-08-09 16:16:08 -0700152
Jeff Thompsonbf50a1a2013-08-20 18:01:01 -0700153 /**
154 * Shut down and disconnect this Face.
155 */
Jeff Thompson0050abe2013-09-17 12:50:25 -0700156 void
157 shutdown();
Jeff Thompson517ffa82013-08-05 16:04:34 -0700158
Jeff Thompsonb982b6d2013-07-15 18:15:45 -0700159private:
Jeff Thompsonbf50a1a2013-08-20 18:01:01 -0700160 Node node_;
Jeff Thompsonaa4e6db2013-07-15 17:25:23 -0700161};
162
163}
164
165#endif