face.hpp

Go to the documentation of this file.

/* -*- Mode:C++; c-file-style:"gnu"; indent-tabs-mode:nil; -*- */
/*
 * Copyright (c) 2013-2025 Regents of the University of California.
 *
 * This file is part of ndn-cxx library (NDN C++ library with eXperimental eXtensions).
 *
 * ndn-cxx library is free software: you can redistribute it and/or modify it under the
 * terms of the GNU Lesser General Public License as published by the Free Software
 * Foundation, either version 3 of the License, or (at your option) any later version.
 *
 * ndn-cxx library is distributed in the hope that it will be useful, but WITHOUT ANY
 * WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
 * PARTICULAR PURPOSE.  See the GNU Lesser General Public License for more details.
 *
 * You should have received copies of the GNU General Public License and GNU Lesser
 * General Public License along with ndn-cxx, e.g., in COPYING.md file.  If not, see
 * <http://www.gnu.org/licenses/>.
 *
 * See AUTHORS.md for complete list of ndn-cxx authors and contributors.
 */
 
#ifndef NDN_CXX_FACE_HPP
#define NDN_CXX_FACE_HPP
 
#include "ndn-cxx/data.hpp"
#include "ndn-cxx/interest.hpp"
#include "ndn-cxx/interest-filter.hpp"
#include "ndn-cxx/detail/asio-fwd.hpp"
#include "ndn-cxx/detail/cancel-handle.hpp"
#include "ndn-cxx/encoding/nfd-constants.hpp"
#include "ndn-cxx/lp/nack.hpp"
#include "ndn-cxx/security/key-chain.hpp"
#include "ndn-cxx/security/signing-info.hpp"
 
namespace ndn {
 
class Transport;
 
class PendingInterestHandle;
class RegisteredPrefixHandle;
class InterestFilterHandle;
 
namespace detail {
using RecordId = uint64_t;
} // namespace detail
 
using DataCallback = std::function<void(const Interest&, const Data&)>;
 
using NackCallback = std::function<void(const Interest&, const lp::Nack&)>;
 
using TimeoutCallback = std::function<void(const Interest&)>;
 
using InterestCallback = std::function<void(const InterestFilter&, const Interest&)>;
 
using RegisterPrefixSuccessCallback = std::function<void(const Name&)>;
 
using RegisterPrefixFailureCallback = std::function<void(const Name&, const std::string&)>;
 
using UnregisterPrefixSuccessCallback = std::function<void()>;
 
using UnregisterPrefixFailureCallback = std::function<void(const std::string&)>;
 
class Face : noncopyable
{
public:
  class Error : public std::runtime_error
  {
  public:
    using std::runtime_error::runtime_error;
  };
 
  class OversizedPacketError : public Error
  {
  public:
    OversizedPacketError(char pktType, const Name& name, size_t wireSize);
 
  public:
    const char pktType;
    const Name name;
    const size_t wireSize;
  };
 
public: // constructors
  explicit
  Face(shared_ptr<Transport> transport = nullptr);
 
  explicit
  Face(boost::asio::io_context& ioCtx);
 
  explicit
  Face(const std::string& host, const std::string& port = "6363");
 
  Face(shared_ptr<Transport> transport, KeyChain& keyChain);
 
  Face(shared_ptr<Transport> transport, boost::asio::io_context& ioCtx);
 
  Face(shared_ptr<Transport> transport, boost::asio::io_context& ioCtx, KeyChain& keyChain);
 
  virtual
  ~Face();
 
public: // consumer
  PendingInterestHandle
  expressInterest(const Interest& interest,
                  const DataCallback& afterSatisfied,
                  const NackCallback& afterNacked,
                  const TimeoutCallback& afterTimeout);
 
  void
  removeAllPendingInterests();
 
  size_t
  getNPendingInterests() const;
 
public: // producer
  RegisteredPrefixHandle
  setInterestFilter(const InterestFilter& filter, const InterestCallback& onInterest,
                    const RegisterPrefixFailureCallback& onFailure,
                    const security::SigningInfo& signingInfo = security::SigningInfo(),
                    uint64_t flags = nfd::ROUTE_FLAG_CHILD_INHERIT);
 
  RegisteredPrefixHandle
  setInterestFilter(const InterestFilter& filter, const InterestCallback& onInterest,
                    const RegisterPrefixSuccessCallback& onSuccess,
                    const RegisterPrefixFailureCallback& onFailure,
                    const security::SigningInfo& signingInfo = security::SigningInfo(),
                    uint64_t flags = nfd::ROUTE_FLAG_CHILD_INHERIT);
 
  InterestFilterHandle
  setInterestFilter(const InterestFilter& filter, const InterestCallback& onInterest);
 
  RegisteredPrefixHandle
  registerPrefix(const Name& prefix,
                 const RegisterPrefixSuccessCallback& onSuccess,
                 const RegisterPrefixFailureCallback& onFailure,
                 const security::SigningInfo& signingInfo = security::SigningInfo(),
                 uint64_t flags = nfd::ROUTE_FLAG_CHILD_INHERIT);
 
  void
  put(const Data& data);
 
  void
  put(const lp::Nack& nack);
 
public: // event loop routines
  void
  processEvents(time::milliseconds timeout = 0_ms, bool keepRunning = false)
  {
    this->doProcessEvents(timeout, keepRunning);
  }
 
  void
  shutdown();
 
  boost::asio::io_context&
  getIoContext() const noexcept
  {
    return m_ioCtx;
  }
 
NDN_CXX_PUBLIC_WITH_TESTS_ELSE_PROTECTED:
  Transport&
  getTransport() const
  {
    return *m_transport;
  }
 
protected:
  virtual void
  doProcessEvents(time::milliseconds timeout, bool keepRunning);
 
private:
  void
  construct(shared_ptr<Transport> transport, KeyChain& keyChain);
 
  void
  onReceiveElement(const Block& blockFromDaemon);
 
private:
  unique_ptr<boost::asio::io_context> m_internalIoCtx;
  boost::asio::io_context& m_ioCtx;
 
  shared_ptr<Transport> m_transport;
 
  unique_ptr<KeyChain> m_internalKeyChain;
 
  class Impl;
  shared_ptr<Impl> m_impl;
 
  friend PendingInterestHandle;
  friend RegisteredPrefixHandle;
  friend InterestFilterHandle;
};
 
class PendingInterestHandle : public detail::CancelHandle
{
public:
  PendingInterestHandle() noexcept = default;
 
private:
  PendingInterestHandle(weak_ptr<Face::Impl> impl, detail::RecordId id);
 
  friend Face;
};
 
using ScopedPendingInterestHandle = detail::ScopedCancelHandle<PendingInterestHandle>;
 
class RegisteredPrefixHandle : public detail::CancelHandle
{
public:
  RegisteredPrefixHandle() noexcept = default;
 
  void
  unregister(const UnregisterPrefixSuccessCallback& onSuccess = nullptr,
             const UnregisterPrefixFailureCallback& onFailure = nullptr);
 
private:
  RegisteredPrefixHandle(weak_ptr<Face::Impl> impl, detail::RecordId id);
 
  static void
  unregister(const weak_ptr<Face::Impl>& impl, detail::RecordId id,
             const UnregisterPrefixSuccessCallback& onSuccess,
             const UnregisterPrefixFailureCallback& onFailure);
 
private:
  weak_ptr<Face::Impl> m_weakImpl;
  detail::RecordId m_id = 0;
 
  friend Face;
};
 
using ScopedRegisteredPrefixHandle = detail::ScopedCancelHandle<RegisteredPrefixHandle>;
 
class InterestFilterHandle : public detail::CancelHandle
{
public:
  InterestFilterHandle() noexcept = default;
 
private:
  InterestFilterHandle(weak_ptr<Face::Impl> impl, detail::RecordId id);
 
  friend Face;
};
 
using ScopedInterestFilterHandle = detail::ScopedCancelHandle<InterestFilterHandle>;
 
} // namespace ndn
 
#endif // NDN_CXX_FACE_HPP