A Discrete-Event Network Simulator
API
Loading...
Searching...
No Matches
ns3::Callback< R, UArgs > Class Template Reference

Callback template class. More...

#include "callback.h"

Inherits ns3::CallbackBase.

+ Collaboration diagram for ns3::Callback< R, UArgs >:

Public Member Functions

 Callback ()
 
template<typename... BArgs>
 Callback (const Callback< R, BArgs..., UArgs... > &cb, BArgs... bargs)
 Construct from another callback and bind some arguments (if any)
 
 Callback (const Ptr< CallbackImpl< R, UArgs... > > &impl)
 Construct from a CallbackImpl pointer.
 
template<typename T , typename... BArgs, std::enable_if_t<!std::is_base_of_v< CallbackBase, T > &&std::is_invocable_r_v< R, T, BArgs..., UArgs... >, int > = 0>
 Callback (T func, BArgs... bargs)
 Construct from a function and bind some arguments (if any)
 
bool Assign (const CallbackBase &other)
 Adopt the other's implementation, if type compatible.
 
template<typename... BoundArgs>
auto Bind (BoundArgs &&... bargs)
 Bind a variable number of arguments.
 
bool CheckType (const CallbackBase &other) const
 Check for compatible types.
 
bool IsEqual (const CallbackBase &other) const
 Equality test.
 
bool IsNull () const
 Check for null implementation.
 
void Nullify ()
 Discard the implementation, set it to null.
 
operator() (UArgs... uargs) const
 Functor with varying numbers of arguments.
 
- Public Member Functions inherited from ns3::CallbackBase
 CallbackBase ()
 
Ptr< CallbackImplBaseGetImpl () const
 

Private Member Functions

template<std::size_t... INDEX, typename... BoundArgs>
auto BindImpl (std::index_sequence< INDEX... > seq, BoundArgs &&... bargs)
 Implementation of the Bind method.
 
bool DoCheckType (Ptr< const CallbackImplBase > other) const
 Check for compatible types.
 
CallbackImpl< R, UArgs... > * DoPeekImpl () const
 

Friends

template<typename ROther , typename... UArgsOther>
class Callback
 

Additional Inherited Members

- Protected Member Functions inherited from ns3::CallbackBase
 CallbackBase (Ptr< CallbackImplBase > impl)
 Construct from a pimpl.
 
- Protected Attributes inherited from ns3::CallbackBase
Ptr< CallbackImplBasem_impl
 the pimpl
 

Detailed Description

template<typename R, typename... UArgs>
class ns3::Callback< R, UArgs >

Callback template class.

This class template implements the Functor Design Pattern. It is used to declare the type of a Callback:

  • the first non-optional template argument represents the return type of the callback.
  • the remaining (optional) template arguments represent the type of the subsequent arguments to the callback.

Callback instances are built with the MakeCallback template functions. Callback instances have POD semantics: the memory they allocate is managed automatically, without user intervention which allows you to pass around Callback instances by value.

Sample code which shows how to use this class template as well as the function templates MakeCallback :

/*
* Copyright (c) 2006 INRIA
*
* SPDX-License-Identifier: GPL-2.0-only
*
*/
#include "ns3/assert.h"
#include "ns3/callback.h"
#include "ns3/command-line.h"
#include <iostream>
/**
* \file
* \ingroup core-examples
* \ingroup callback
* Example program illustrating use of callback functions and methods.
*
* See \ref callback
*/
using namespace ns3;
namespace
{
/**
* Example Callback function.
*
* \param [in] a The first argument.
* \param [in] b The second argument.
* \returns The first argument.
*/
double
CbOne(double a, double b)
{
std::cout << "invoke cbOne a=" << a << ", b=" << b << std::endl;
return a;
}
/** Example Callback class. */
class MyCb
{
public:
/**
* Example Callback class method.
*
* \param [in] a The argument.
* \returns -5
*/
int CbTwo(double a)
{
std::cout << "invoke cbTwo a=" << a << std::endl;
return -5;
}
};
} // unnamed namespace
int
main(int argc, char* argv[])
{
CommandLine cmd(__FILE__);
cmd.Parse(argc, argv);
// return type: double
// first arg type: double
// second arg type: double
// build callback instance which points to cbOne function
one = MakeCallback(&CbOne);
// this is not a null callback
NS_ASSERT(!one.IsNull());
// invoke cbOne function through callback instance
double retOne;
retOne = one(10.0, 20.0);
// callback returned expected value
NS_ASSERT(retOne == 10.0);
// return type: int
// first arg type: double
MyCb cb;
// build callback instance which points to MyCb::cbTwo
two = MakeCallback(&MyCb::CbTwo, &cb);
// this is not a null callback
NS_ASSERT(!two.IsNull());
// invoke MyCb::cbTwo through callback instance
int retTwo;
retTwo = two(10.0);
// callback returned expected value
NS_ASSERT(retTwo == -5);
two = MakeNullCallback<int, double>();
// invoking a null callback is just like
// invoking a null function pointer:
// it will crash.
// int retTwoNull = two (20.0);
NS_ASSERT(two.IsNull());
#if 0
// The below type mismatch between CbOne() and callback two will fail to
// compile if enabled in this program.
two = MakeCallback (&CbOne);
#endif
#if 0
// This is a slightly different example, in which the code will compile
// but because callbacks are type-safe, will cause a fatal error at runtime
// (the difference here is that Assign() is called instead of operator=)
three.Assign (MakeCallback (&CbOne));
#endif
return 0;
}
Callback template class.
Definition callback.h:422
bool IsNull() const
Check for null implementation.
Definition callback.h:555
bool Assign(const CallbackBase &other)
Adopt the other's implementation, if type compatible.
Definition callback.h:605
Parse command-line arguments.
#define NS_ASSERT(condition)
At runtime, in debugging builds, if this condition is not true, the program prints the source file,...
Definition assert.h:55
Every class exported by the ns3 library is enclosed in the ns3 namespace.
Callback< R, Args... > MakeCallback(R(T::*memPtr)(Args...), OBJ objPtr)
Build Callbacks for class method members which take varying numbers of arguments and potentially retu...
Definition callback.h:684
-ray-to-three-gpp-ch-calibration
Internal:
This code was originally written based on the techniques described in http://www.codeproject.com/cpp/TTLFunction.asp It was subsequently rewritten to follow the architecture outlined in "Modern C++ Design" by Andrei Alexandrescu in chapter 5, "Generalized Functors".

This code uses:

  • default template parameters to saves users from having to specify empty parameters when the number of parameters is smaller than the maximum supported number
  • the pimpl idiom: the Callback class is passed around by value and delegates the crux of the work to its pimpl pointer.
  • a reference list implementation to implement the Callback's value semantics.

This code most notably departs from the alexandrescu implementation in that it does not use type lists to specify and pass around the types of the callback arguments. Of course, it also does not use copy-destruction semantics and relies on a reference list rather than autoPtr to hold the pointer.

See also
attribute_Callback
Template Parameters
R[explicit] The return type of the Callback.
UArgs[explicit] The types of any arguments to the Callback.

Definition at line 421 of file callback.h.

Constructor & Destructor Documentation

◆ Callback() [1/4]

template<typename R , typename... UArgs>
template ns3::Callback< R, UArgs >::Callback ( )
inline

Definition at line 427 of file callback.h.

◆ Callback() [2/4]

template<typename R , typename... UArgs>
ns3::Callback< R, UArgs >::Callback ( const Ptr< CallbackImpl< R, UArgs... > > & impl)
inline

Construct from a CallbackImpl pointer.

Parameters
[in]implThe CallbackImpl Ptr

Definition at line 436 of file callback.h.

◆ Callback() [3/4]

template<typename R , typename... UArgs>
template<typename... BArgs>
ns3::Callback< R, UArgs >::Callback ( const Callback< R, BArgs..., UArgs... > & cb,
BArgs... bargs )
inline

Construct from another callback and bind some arguments (if any)

Template Parameters
BArgs[deduced] The types of the bound arguments
Parameters
[in]cbThe existing callback
[in]bargsThe values of the bound arguments

Definition at line 449 of file callback.h.

References ns3::Create(), ns3::Callback< R, UArgs >::DoPeekImpl(), and ns3::CallbackBase::m_impl.

+ Here is the call graph for this function:

◆ Callback() [4/4]

template<typename R , typename... UArgs>
template<typename T , typename... BArgs, std::enable_if_t<!std::is_base_of_v< CallbackBase, T > &&std::is_invocable_r_v< R, T, BArgs..., UArgs... >, int > = 0>
ns3::Callback< R, UArgs >::Callback ( T func,
BArgs... bargs )
inline

Construct from a function and bind some arguments (if any)

Template Parameters
T[deduced] The type of the function
BArgs[deduced] The types of the bound arguments
Parameters
[in]funcThe function
[in]bargsThe values of the bound arguments
Internal:
We leverage SFINAE to have the compiler discard this constructor when the type of the first argument is a class derived from CallbackBase (i.e., a Callback).

Definition at line 481 of file callback.h.

References ns3::Create(), and ns3::CallbackBase::m_impl.

+ Here is the call graph for this function:

Member Function Documentation

◆ Assign()

template<typename R , typename... UArgs>
bool ns3::Callback< R, UArgs >::Assign ( const CallbackBase & other)
inline

Adopt the other's implementation, if type compatible.

Parameters
[in]otherCallback
Returns
true if other was type-compatible and could be adopted.

Definition at line 605 of file callback.h.

References ns3::Callback< R, UArgs >::DoCheckType(), ns3::CallbackImpl< R, UArgs >::DoGetTypeid(), ns3::CallbackBase::GetImpl(), ns3::CallbackBase::m_impl, NS_FATAL_ERROR_CONT, and ns3::PeekPointer().

+ Here is the call graph for this function:

◆ Bind()

template<typename R , typename... UArgs>
template<typename... BoundArgs>
auto ns3::Callback< R, UArgs >::Bind ( BoundArgs &&... bargs)
inline

Bind a variable number of arguments.

Template Parameters
BoundArgs[deduced] The types of the arguments to bind
Parameters
[in]bargsThe values of the arguments to bind
Returns
The bound callback

Definition at line 543 of file callback.h.

References ns3::Callback< R, UArgs >::BindImpl().

Referenced by ns3::TracedCallback< Ts >::Connect(), ns3::TracedCallback< Ts >::Disconnect(), CallbackEqualityTestCase::DoRun(), ns3::QosTxop::SetDroppedMpduCallback(), and ns3::Txop::SetDroppedMpduCallback().

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ BindImpl()

template<typename R , typename... UArgs>
template<std::size_t... INDEX, typename... BoundArgs>
auto ns3::Callback< R, UArgs >::BindImpl ( std::index_sequence< INDEX... > seq,
BoundArgs &&... bargs )
inlineprivate

Implementation of the Bind method.

Template Parameters
BoundArgsThe types of the arguments to bind
Parameters
[in]seqA compile-time integer sequence
[in]bargsThe values of the arguments to bind
Returns
The bound callback
Internal:
The integer sequence is 0..N-1, where N is the number of arguments left unbound.

Definition at line 515 of file callback.h.

References ns3::Create(), and ns3::Callback< R, UArgs >::DoPeekImpl().

Referenced by ns3::Callback< R, UArgs >::Bind().

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ CheckType()

template<typename R , typename... UArgs>
bool ns3::Callback< R, UArgs >::CheckType ( const CallbackBase & other) const
inline

Check for compatible types.

Parameters
[in]otherCallback Ptr
Returns
true if other can be dynamic_cast to my type

Definition at line 594 of file callback.h.

References ns3::Callback< R, UArgs >::DoCheckType(), and ns3::CallbackBase::GetImpl().

+ Here is the call graph for this function:

◆ DoCheckType()

template<typename R , typename... UArgs>
bool ns3::Callback< R, UArgs >::DoCheckType ( Ptr< const CallbackImplBase > other) const
inlineprivate

Check for compatible types.

Parameters
[in]otherCallback Ptr
Returns
true if other can be dynamic_cast to my type

Definition at line 635 of file callback.h.

References ns3::PeekPointer().

Referenced by ns3::Callback< R, UArgs >::Assign(), and ns3::Callback< R, UArgs >::CheckType().

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ DoPeekImpl()

template<typename R , typename... UArgs>
CallbackImpl< R, UArgs... > * ns3::Callback< R, UArgs >::DoPeekImpl ( ) const
inlineprivate
Returns
The pimpl pointer

Definition at line 624 of file callback.h.

References ns3::CallbackBase::m_impl, and ns3::PeekPointer().

Referenced by ns3::Callback< R, UArgs >::Callback(), ns3::Callback< R, UArgs >::BindImpl(), ns3::Callback< R, UArgs >::IsNull(), and ns3::Callback< R, UArgs >::operator()().

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ IsEqual()

template<typename R , typename... UArgs>
bool ns3::Callback< R, UArgs >::IsEqual ( const CallbackBase & other) const
inline

Equality test.

Parameters
[in]otherCallback
Returns
true if we are equal

Definition at line 583 of file callback.h.

References ns3::CallbackBase::GetImpl(), and ns3::CallbackBase::m_impl.

Referenced by CallbackEqualityTestCase::DoRun(), ns3::aodv::QueueEntryTest::DoRun(), and ns3::operator!=().

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ IsNull()

template<typename R , typename... UArgs>
bool ns3::Callback< R, UArgs >::IsNull ( ) const
inline

Check for null implementation.

Returns
true if I don't have an implementation

Definition at line 555 of file callback.h.

References ns3::Callback< R, UArgs >::DoPeekImpl().

Referenced by ns3::Ipv4EndPoint::~Ipv4EndPoint(), ns3::Ipv6EndPoint::~Ipv6EndPoint(), TcpSocketAdvertisedWindowProxy::AdvertisedWindowSize(), ns3::lrwpan::LrWpanPhy::CancelEd(), ns3::lrwpan::LrWpanCsmaCa::CanProceed(), ns3::TcpTxBuffer::DiscardUpTo(), ns3::WifiRadioEnergyModelHelper::DoInstall(), NullifyCallbackTestCase::DoRun(), ns3::lrwpan::LrWpanPhy::EndCca(), ns3::lrwpan::LrWpanMac::EndChannelEnergyScan(), ns3::lrwpan::LrWpanMac::EndChannelScan(), ns3::lrwpan::LrWpanPhy::EndEd(), ns3::lorawan::SimpleEndDeviceLoraPhy::EndReceive(), ns3::lorawan::SimpleGatewayLoraPhy::EndReceive(), ns3::HalfDuplexIdealPhy::EndRx(), ns3::lrwpan::LrWpanPhy::EndRx(), ns3::LteSpectrumPhy::EndRxData(), ns3::LteSpectrumPhy::EndRxDlCtrl(), ns3::lrwpan::LrWpanPhy::EndSetTRXState(), ns3::lrwpan::LrWpanMac::EndStartRequest(), ns3::HalfDuplexIdealPhy::EndTx(), ns3::lrwpan::LrWpanPhy::EndTx(), ns3::lrwpan::LrWpanMac::EnqueueInd(), ns3::lrwpan::LrWpanMac::EnqueueTxQElement(), ns3::WifiTxTimer::FeedTraceSource(), ns3::WifiTxTimer::FeedTraceSource(), ns3::WifiTxTimer::FeedTraceSource(), ns3::dsr::DsrRouting::ForwardErrPacket(), ns3::dsr::DsrRouting::ForwardPacket(), ns3::FdNetDevice::ForwardUp(), ns3::WifiNetDevice::ForwardUp(), ns3::WifiMode::GetNonHtReferenceRate(), ns3::AcousticModemEnergyModel::HandleEnergyDepletion(), ns3::lorawan::LoraRadioEnergyModel::HandleEnergyDepletion(), ns3::WifiRadioEnergyModel::HandleEnergyDepletion(), ns3::AcousticModemEnergyModel::HandleEnergyRecharged(), ns3::lorawan::LoraRadioEnergyModel::HandleEnergyRecharged(), ns3::WifiRadioEnergyModel::HandleEnergyRecharged(), ns3::BlockAckManager::HandleInFlightMpdu(), ns3::Icmpv6L4Protocol::HandleRA(), AttributeObjectTest::InvokeCbValue(), CallbackValueTestCase::InvokeCbValue(), RandomVariableStreamAttributeTestCase::InvokeCbValue(), ns3::WimaxNetDevice::IsPromisc(), ns3::lrwpan::LrWpanMac::LostAssocRespCommand(), ns3::lrwpan::LrWpanMac::McpsDataRequest(), ns3::lrwpan::LrWpanMac::MlmeAssociateRequest(), ns3::lrwpan::LrWpanMac::MlmeGetRequest(), ns3::lrwpan::LrWpanMac::MlmeScanRequest(), ns3::lrwpan::LrWpanMac::MlmeSetRequest(), ns3::lrwpan::LrWpanMac::MlmeStartRequest(), ns3::WifiRadioEnergyModelPhyListener::NotifyCcaBusyStart(), ns3::SpectrumWifiPhy::NotifyChannelSwitched(), ns3::BlockAckManager::NotifyDiscardedMpdu(), ns3::HePhy::NotifyEndOfHeSigA(), ns3::BlockAckManager::NotifyGotBlockAck(), ns3::Icmpv4L4Protocol::NotifyNewAggregate(), ns3::Icmpv6L4Protocol::NotifyNewAggregate(), ns3::TcpL4Protocol::NotifyNewAggregate(), ns3::UdpL4Protocol::NotifyNewAggregate(), ns3::WifiRadioEnergyModelPhyListener::NotifyOff(), ns3::WifiRadioEnergyModelPhyListener::NotifyOn(), ns3::FrameExchangeManager::NotifyPacketDiscarded(), ns3::FrameExchangeManager::NotifyReceivedNormalAck(), ns3::AlohaNoackNetDevice::NotifyReceptionEndOk(), ns3::WifiRadioEnergyModelPhyListener::NotifyRxEndError(), ns3::WifiRadioEnergyModelPhyListener::NotifyRxEndOk(), ns3::WifiPhyStateHelper::NotifyRxMpdu(), ns3::WifiPhyStateHelper::NotifyRxPsduFailed(), ns3::WifiPhyStateHelper::NotifyRxPsduSucceeded(), ns3::lorawan::LoraRadioEnergyModelPhyListener::NotifyRxStart(), ns3::WifiRadioEnergyModelPhyListener::NotifyRxStart(), ns3::lorawan::LoraRadioEnergyModelPhyListener::NotifySleep(), ns3::WifiRadioEnergyModelPhyListener::NotifySleep(), ns3::lorawan::LoraRadioEnergyModelPhyListener::NotifyStandby(), ns3::WifiRadioEnergyModelPhyListener::NotifySwitchingStart(), ns3::NetDeviceQueue::NotifyTransmittedBytes(), ns3::lorawan::LoraRadioEnergyModelPhyListener::NotifyTxStart(), ns3::WifiRadioEnergyModelPhyListener::NotifyTxStart(), ns3::WifiRadioEnergyModelPhyListener::NotifyWakeup(), ns3::lrwpan::LrWpanMac::PdDataConfirm(), ns3::lrwpan::LrWpanMac::PdDataIndication(), ns3::lrwpan::LrWpanPhy::PdDataRequest(), ns3::QosTxop::PeekNextMpdu(), ns3::lrwpan::LrWpanCsmaCa::PlmeCcaConfirm(), ns3::lrwpan::LrWpanPhy::PlmeCcaRequest(), ns3::lrwpan::LrWpanPhy::PlmeEdRequest(), ns3::lrwpan::LrWpanPhy::PlmeGetAttributeRequest(), ns3::lrwpan::LrWpanMac::PlmeSetAttributeConfirm(), ns3::lrwpan::LrWpanPhy::PlmeSetAttributeRequest(), ns3::lrwpan::LrWpanPhy::PlmeSetTRXStateRequest(), ns3::lrwpan::LrWpanMac::PrepareRetransmission(), ns3::Packet::Print(), ns3::Packet::PrintByteTags(), ns3::Packet::PrintPacketTags(), ns3::lrwpan::LrWpanMac::PurgeInd(), ns3::CsmaNetDevice::Receive(), ns3::LoopbackNetDevice::Receive(), ns3::MockNetDevice::Receive(), ns3::MpiReceiver::Receive(), ns3::PointToPointNetDevice::Receive(), ns3::SimpleNetDevice::Receive(), ns3::VirtualNetDevice::Receive(), ns3::StaWifiMac::ReceiveAssocResp(), ns3::lrwpan::LrWpanMac::ReceiveBeacon(), ns3::TcpSocketMsgBase::ReceivedAck(), ns3::BridgeNetDevice::ReceiveFromDevice(), ns3::MeshPointDevice::ReceiveFromDevice(), ns3::OpenFlowSwitchNetDevice::ReceiveFromDevice(), ns3::SixLowPanNetDevice::ReceiveFromDevice(), ns3::aodv::RoutingProtocol::RouteInput(), ns3::dsdv::RoutingProtocol::RouteInput(), ns3::Ipv4GlobalRouting::RouteInput(), ns3::Ipv4StaticRouting::RouteInput(), ns3::Ipv6StaticRouting::RouteInput(), ns3::NixVectorRouting< T >::RouteInput(), ns3::olsr::RoutingProtocol::RouteInput(), ns3::Rip::RouteInput(), ns3::RipNg::RouteInput(), ns3::UanPhyGen::RxEndEvent(), ns3::dsr::DsrRouting::Send(), ns3::dsr::DsrRouting::SendAck(), ns3::dsr::DsrRouting::SendErrorRequest(), ns3::MockNetDevice::SendFrom(), ns3::dsr::DsrRouting::SendInitialRequest(), ns3::dsr::DsrRouting::SendPacketFromBuffer(), ns3::dsr::DsrRouting::SendReply(), ns3::dsr::DsrRouting::SendRequest(), ns3::TcpSocketMsgBase::SetAfterRetransmitCb(), ns3::SubscriberStationNetDevice::SetBasicConnection(), ns3::TcpSocketMsgBase::SetBeforeRetransmitCb(), ns3::lorawan::LoraRadioEnergyModelPhyListener::SetChangeStateCallback(), ns3::WifiRadioEnergyModelPhyListener::SetChangeStateCallback(), ns3::AcousticModemEnergyModel::SetEnergyDepletionCallback(), ns3::lorawan::LoraRadioEnergyModel::SetEnergyDepletionCallback(), ns3::WifiRadioEnergyModel::SetEnergyDepletionCallback(), ns3::AcousticModemEnergyModel::SetEnergyRechargeCallback(), ns3::lorawan::LoraRadioEnergyModel::SetEnergyRechargedCallback(), ns3::WifiRadioEnergyModel::SetEnergyRechargedCallback(), TcpSocketAdvertisedWindowProxy::SetInvalidAwndCb(), ns3::lrwpan::LrWpanMac::SetLrWpanMacState(), ns3::SubscriberStationNetDevice::SetPrimaryConnection(), ns3::TcpSocketMsgBase::SetProcessedAckCb(), ns3::TcpSocketMsgBase::SetRcvAckCb(), ns3::UanPhyGen::SetSleepMode(), ns3::TcpSocketMsgBase::SetUpdateRttHistoryCb(), ns3::lorawan::LoraRadioEnergyModelPhyListener::SetUpdateTxCurrentCallback(), ns3::WifiRadioEnergyModelPhyListener::SetUpdateTxCurrentCallback(), ns3::HalfDuplexIdealPhy::StartRx(), ns3::LteSpectrumPhy::StartRxDlCtrl(), ns3::WifiRadioEnergyModelPhyListener::SwitchToIdle(), ns3::lorawan::LoraRadioEnergyModelPhyListener::SwitchToStandby(), ns3::lorawan::EndDeviceLoraPhy::TxFinished(), ns3::TcpTxBuffer::Update(), ns3::UanPhyGen::UpdatePowerConsumption(), ns3::TcpSocketMsgBase::UpdateRttHistory(), and ns3::NetDeviceQueue::Wake().

+ Here is the call graph for this function:

◆ Nullify()

◆ operator()()

template<typename R , typename... UArgs>
R ns3::Callback< R, UArgs >::operator() ( UArgs... uargs) const
inline

Functor with varying numbers of arguments.

Parameters
uargsThe arguments to the callback
Returns
Callback value

Definition at line 572 of file callback.h.

References ns3::Callback< R, UArgs >::DoPeekImpl().

+ Here is the call graph for this function:

Friends And Related Symbol Documentation

◆ Callback

template<typename R , typename... UArgs>
template<typename ROther , typename... UArgsOther>
friend class Callback
friend

Definition at line 424 of file callback.h.


The documentation for this class was generated from the following files: