blob: 6e47ff767795432dbaa54a747285a379844db66c [file] [log] [blame]
Jeff Thompsonaa4e6db2013-07-15 17:25:23 -07001/**
Jeff Thompson7687dc02013-09-13 11:54:07 -07002 * Copyright (C) 2013 Regents of the University of California.
3 * @author: Jeff Thompson <jefft0@remap.ucla.edu>
Jeff Thompsonaa4e6db2013-07-15 17:25:23 -07004 * See COPYING for copyright and distribution information.
5 */
6
Jeff Thompsonb9e3c8e2013-08-02 11:42:51 -07007#ifndef NDN_FACE_HPP
Jeff Thompsona0d18c92013-08-06 13:55:32 -07008#define NDN_FACE_HPP
Jeff Thompsonaa4e6db2013-07-15 17:25:23 -07009
Jeff Thompsonbf50a1a2013-08-20 18:01:01 -070010#include "node.hpp"
Jeff Thompsonfb29cda2013-08-24 10:26:54 -070011#include "transport/tcp-transport.hpp"
Jeff Thompsonbeb8b7d2013-07-16 15:49:21 -070012
Jeff Thompsonaa4e6db2013-07-15 17:25:23 -070013namespace ndn {
14
Jeff Thompsonfe08e5a2013-08-13 11:15:59 -070015/**
16 * The Face class provides the main methods for NDN communication.
17 */
Jeff Thompsonbf50a1a2013-08-20 18:01:01 -070018class Face {
Jeff Thompsonaa4e6db2013-07-15 17:25:23 -070019public:
Jeff Thompsonfe08e5a2013-08-13 11:15:59 -070020 /**
Jeff Thompson10e34382013-08-22 13:34:46 -070021 * Create a new Face for communication with an NDN hub with the given Transport object and connectionInfo.
22 * @param transport A shared_ptr to a Transport object used for communication.
23 * @param transport A shared_ptr to a Transport::ConnectionInfo to be used to connect to the transport.
Jeff Thompsonfe08e5a2013-08-13 11:15:59 -070024 */
Jeff Thompson1656e6a2013-08-29 18:01:48 -070025 Face(const ptr_lib::shared_ptr<Transport>& transport, const ptr_lib::shared_ptr<const Transport::ConnectionInfo>& connectionInfo)
Jeff Thompson10e34382013-08-22 13:34:46 -070026 : node_(transport, connectionInfo)
Jeff Thompsonb982b6d2013-07-15 18:15:45 -070027 {
Jeff Thompsonb982b6d2013-07-15 18:15:45 -070028 }
29
Jeff Thompsonfe08e5a2013-08-13 11:15:59 -070030 /**
Jeff Thompson86507bc2013-08-23 20:51:38 -070031 * Create a new Face for communication with an NDN hub at host:port using the default TcpTransport.
Jeff Thompsonfe08e5a2013-08-13 11:15:59 -070032 * @param host The host of the NDN hub.
Jeff Thompsonfb29cda2013-08-24 10:26:54 -070033 * @param port The port of the NDN hub. If omitted. use 9695.
Jeff Thompsonfe08e5a2013-08-13 11:15:59 -070034 */
Jeff Thompsonfb29cda2013-08-24 10:26:54 -070035 Face(const char *host, unsigned short port = 9695)
36 : node_(ptr_lib::make_shared<TcpTransport>(),
37 ptr_lib::make_shared<TcpTransport::ConnectionInfo>(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.
48 */
Jeff Thompson0050abe2013-09-17 12:50:25 -070049 void
50 expressInterest(const Interest& interest, const OnData& onData, const OnTimeout& onTimeout = OnTimeout())
Jeff Thompson4fe45512013-08-23 14:06:38 -070051 {
52 node_.expressInterest(interest, onData, onTimeout);
53 }
54
55 /**
Jeff Thompsonc172be32013-07-16 15:08:05 -070056 * Encode name as an Interest. If interestTemplate is not 0, use its interest selectors.
Jeff Thompson7aec0252013-08-22 17:29:57 -070057 * Send the interest through the transport, read the entire response and call onData(interest, data).
Jeff Thompson4fe45512013-08-23 14:06:38 -070058 * @param name A reference to a Name for the interest. This copies the Name.
Jeff Thompsonc172be32013-07-16 15:08:05 -070059 * @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 -070060 * @param onData A function object to call when a matching data packet is received. This copies the function object, so you may need to
61 * use func_lib::ref() as appropriate.
62 * @param onTimeout A function object to call if the interest times out. If onTimeout is an empty OnTimeout(), this does not use it.
63 * This copies the function object, so you may need to use func_lib::ref() as appropriate.
Jeff Thompsonc172be32013-07-16 15:08:05 -070064 */
Jeff Thompson0050abe2013-09-17 12:50:25 -070065 void
66 expressInterest(const Name& name, const Interest *interestTemplate, const OnData& onData, const OnTimeout& onTimeout = OnTimeout());
Jeff Thompson7aec0252013-08-22 17:29:57 -070067
68 /**
69 * Encode name as an Interest, using a default interest lifetime.
70 * Send the interest through the transport, read the entire response and call onData(interest, data).
Jeff Thompson4fe45512013-08-23 14:06:38 -070071 * @param name A reference to a Name for the interest. This copies the Name.
Jeff Thompson7aec0252013-08-22 17:29:57 -070072 * @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.
76 */
Jeff Thompson0050abe2013-09-17 12:50:25 -070077 void
78 expressInterest(const Name& name, const OnData& onData, const OnTimeout& onTimeout = OnTimeout())
Jeff Thompson7aec0252013-08-22 17:29:57 -070079 {
Jeff Thompsonfb29cda2013-08-24 10:26:54 -070080 expressInterest(name, 0, onData, onTimeout);
Jeff Thompsoncdf7e252013-07-31 12:41:47 -070081 }
82
Jeff Thompson432c8be2013-08-09 16:16:08 -070083 /**
Jeff Thompson86507bc2013-08-23 20:51:38 -070084 * Register prefix with the connected NDN hub and call onInterest when a matching interest is received.
85 * @param prefix A reference to a Name for the prefix to register. This copies the Name.
86 * @param onInterest A function object to call when a matching interest is received. This copies the function object, so you may need to
87 * use func_lib::ref() as appropriate.
Jeff Thompson590ec232013-09-18 15:55:56 -070088 * @param onRegisterFailed A function object to call if failed to retrieve the connected hub’s ID or failed to register the prefix.
89 * This calls onRegisterFailed(prefix) where prefix is the prefix given to registerPrefix.
90 * @param keyChain The KeyChain object whose signData is called to sign the Data packet with the ForwardingEntry to register the prefix.
91 * @param signerName The signing identity or certificate name, depending on byKeyName. This is used to sign the Data packet
92 * with the ForwardingEntry to register the prefix.This copies the function object, so you may need to use func_lib::ref() as appropriate.
93 * @param byKeyName If true, the signerName is the key name, otherwise it is the certificate name. If omitted, the default is true.
Jeff Thompson86507bc2013-08-23 20:51:38 -070094 * @param flags The flags for finer control of which interests are forward to the application.
Jeff Thompson590ec232013-09-18 15:55:56 -070095 * @param wireFormat A WireFormat object used to encode the input. If omitted, use WireFormat getDefaultWireFormat().
Jeff Thompson86507bc2013-08-23 20:51:38 -070096 */
Jeff Thompson0050abe2013-09-17 12:50:25 -070097 void
Jeff Thompson590ec232013-09-18 15:55:56 -070098 registerPrefix
99 (const Name& prefix, const OnInterest& onInterest, const OnRegisterFailed& onRegisterFailed, KeyChain &keyChain,
100 const Name& signerName, bool byKeyName = true, int flags = 0, WireFormat& wireFormat = *WireFormat::getDefaultWireFormat())
Jeff Thompson86507bc2013-08-23 20:51:38 -0700101 {
Jeff Thompson590ec232013-09-18 15:55:56 -0700102 node_.registerPrefix(prefix, onInterest, onRegisterFailed, keyChain, signerName, byKeyName, flags, wireFormat);
Jeff Thompson86507bc2013-08-23 20:51:38 -0700103 }
Jeff Thompson86507bc2013-08-23 20:51:38 -0700104
105 /**
Jeff Thompsonbf50a1a2013-08-20 18:01:01 -0700106 * Process any data to receive or call timeout callbacks.
Jeff Thompsonc7e07442013-08-19 15:25:43 -0700107 * This is non-blocking and will return immediately if there is no data to receive.
108 * 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 -0700109 * @throw This may throw an exception for reading data or in the callback for processing the data. If you
110 * call this from an main event loop, you may want to catch and log/disregard all exceptions.
111 */
Jeff Thompson0050abe2013-09-17 12:50:25 -0700112 void
113 processEvents()
Jeff Thompsonbf50a1a2013-08-20 18:01:01 -0700114 {
115 // Just call Node's processEvents.
116 node_.processEvents();
117 }
Jeff Thompson432c8be2013-08-09 16:16:08 -0700118
Jeff Thompsonbf50a1a2013-08-20 18:01:01 -0700119 /**
120 * Shut down and disconnect this Face.
121 */
Jeff Thompson0050abe2013-09-17 12:50:25 -0700122 void
123 shutdown();
Jeff Thompson517ffa82013-08-05 16:04:34 -0700124
Jeff Thompsonb982b6d2013-07-15 18:15:45 -0700125private:
Jeff Thompsonbf50a1a2013-08-20 18:01:01 -0700126 Node node_;
Jeff Thompsonaa4e6db2013-07-15 17:25:23 -0700127};
128
129}
130
131#endif