A Discrete-Event Network Simulator
API
Static Public Member Functions | Static Private Member Functions | List of all members
ns3::Names Class Reference

A directory of name and Ptr<Object> associations that allows us to give any ns3 Object a name. More...

#include "names.h"

Static Public Member Functions

static void Add (std::string name, Ptr< Object > object)
 Add the association between the string "name" and the Ptr<Object> obj. More...
 
static void Add (std::string path, std::string name, Ptr< Object > object)
 An intermediate form of Names::Add allowing you to provide a path to the parent object (under which you want this name to be defined) in the form of a name path string. More...
 
static void Add (Ptr< Object > context, std::string name, Ptr< Object > object)
 A low-level form of Names::Add allowing you to specify the path to the parent object (under which you want this name to be defined) in the form of a previously named object. More...
 
static void Clear (void)
 Clear the list of objects associated with names. More...
 
template<typename T >
static Ptr< T > Find (std::string path)
 Given a name path string, look to see if there's an object in the system with that associated to it. More...
 
template<typename T >
static Ptr< T > Find (std::string path, std::string name)
 Given a path to an object and an object name, look through the names defined under the path to see if there's an object there with the given name. More...
 
template<typename T >
static Ptr< T > Find (Ptr< Object > context, std::string name)
 Given a path to an object and an object name, look through the names defined under the path to see if there's an object there with the given name. More...
 
static std::string FindName (Ptr< Object > object)
 Given a pointer to an object, look to see if that object has a name associated with it and, if so, return the name of the object otherwise return an empty string. More...
 
static std::string FindPath (Ptr< Object > object)
 Given a pointer to an object, look to see if that object has a name associated with it and return the fully qualified name path of the object otherwise return an empty string. More...
 
static void Rename (std::string oldpath, std::string newname)
 Rename a previously associated name. More...
 
static void Rename (std::string path, std::string oldname, std::string newname)
 An intermediate form of Names::Rename allowing you to provide a path to the parent object (under which you want this name to be changed) in the form of a name path string. More...
 
static void Rename (Ptr< Object > context, std::string oldname, std::string newname)
 A low-level form of Names::Rename allowing you to specify the path to the parent object (under which you want this name to be changed) in the form of a previously named object. More...
 

Static Private Member Functions

static Ptr< ObjectFindInternal (std::string path)
 Non-templated internal version of Names::Find. More...
 
static Ptr< ObjectFindInternal (std::string path, std::string name)
 Non-templated internal version of Names::Find. More...
 
static Ptr< ObjectFindInternal (Ptr< Object > context, std::string name)
 Non-templated internal version of Names::Find. More...
 

Detailed Description

A directory of name and Ptr<Object> associations that allows us to give any ns3 Object a name.

Definition at line 38 of file names.h.

Member Function Documentation

◆ Add() [1/3]

void ns3::Names::Add ( std::string  name,
Ptr< Object object 
)
static

Add the association between the string "name" and the Ptr<Object> obj.

The name may begin either with "/Names" to explicitly call out the fact that the name provided is installed under the root of the name space, or it may begin with the name of the first object in the path. For example, Names::Add ("/Names/client", obj) and Names::Add ("client", obj) accomplish exactly the same thing. A name at a given level in the name space path must be unique. In the case of the example above, it would be illegal to try and associate a different object with the same name: "client" at the same level ("/Names") in the path.

As well as specifying a name at the root of the "/Names" namespace, the name parameter can contain a path that fully qualifies the name to be added. For example, if you previously have named an object "client" in the root namespace as above, you could name an object "under" that name by making a call like Names::Add ("/Names/client/eth0", obj). This will define the name "eth0" and make it reachable using the path specified. Note that Names::Add ("client/eth0", obj) would accomplish exactly the same thing.

Duplicate names are not allowed at the same level in a path, however you may associate similar names with different paths. For example, if you define "/Names/Client", you may not define another "/Names/Client" just as you may not have two files with the same name in a classical filesystem. However, you may have "/Names/Client/eth0" and "/Names/Server/eth0" defined at the same time just as you might have different files of the same name under different directories.

Parameters
[in]nameThe name of the object you want to associate; which may be prepended with a path to that object.
[in]objectA smart pointer to the object itself.

Definition at line 770 of file names.cc.

References ns3::NamesPriv::Add(), ns3::Singleton< NamesPriv >::Get(), NS_ABORT_MSG_UNLESS, and NS_LOG_FUNCTION.

Referenced by Ns2MobilityHelperTest::CreateNodes(), ns3::tests::BasicAddTestCase::DoRun(), ns3::tests::StringContextAddTestCase::DoRun(), ns3::tests::FullyQualifiedAddTestCase::DoRun(), ns3::tests::RelativeAddTestCase::DoRun(), ns3::tests::BasicRenameTestCase::DoRun(), ns3::tests::StringContextRenameTestCase::DoRun(), ns3::tests::FullyQualifiedRenameTestCase::DoRun(), ns3::tests::RelativeRenameTestCase::DoRun(), ns3::tests::FindPathTestCase::DoRun(), ns3::tests::BasicFindTestCase::DoRun(), ns3::tests::StringContextFindTestCase::DoRun(), ns3::tests::FullyQualifiedFindTestCase::DoRun(), ns3::tests::RelativeFindTestCase::DoRun(), and ns3::tests::AlternateFindTestCase::DoRun().

◆ Add() [2/3]

void ns3::Names::Add ( std::string  path,
std::string  name,
Ptr< Object object 
)
static

An intermediate form of Names::Add allowing you to provide a path to the parent object (under which you want this name to be defined) in the form of a name path string.

In some cases, it is desirable to break up the path used to describe an item in the names namespace into a path and a name. This is analogous to a file system operation in which you provide a directory name and a file name.

For example, consider a situation where you have previously named an object "/Names/server". If you further want to create an association for between a Ptr<Object> object that you want to live "under" the server in the name space – perhaps "eth0" – you could do this in two ways, depending on which was more convenient: Names::Add ("/Names/server/eth0", object) or, using the split path and name approach, Names::Add ("/Names/server", "eth0", object).

Duplicate names are not allowed at the same level in a path, however you may associate similar names with different paths. For example, if you define "/Names/Client", you may not define another "/Names/Client" just as you may not have two files with the same name in a classical filesystem. However, you may have "/Names/Client/eth0" and "/Names/Server/eth0" defined at the same time just as you might have different files of the same name under different directories.

Parameters
[in]pathA path name describing a previously named object under which you want this new name to be defined.
[in]nameThe name of the object you want to associate.
[in]objectA smart pointer to the object itself.
See also
Names::Add (Ptr<Object>,std::string,Ptr<Object>);

Definition at line 786 of file names.cc.

References ns3::NamesPriv::Add(), ns3::Singleton< NamesPriv >::Get(), NS_ABORT_MSG_UNLESS, and NS_LOG_FUNCTION.

◆ Add() [3/3]

void ns3::Names::Add ( Ptr< Object context,
std::string  name,
Ptr< Object object 
)
static

A low-level form of Names::Add allowing you to specify the path to the parent object (under which you want this name to be defined) in the form of a previously named object.

In some use cases, it is desirable to break up the path in the names name space into a path and a name. This is analogous to a file system operation in which you provide a directory name and a file name. Recall that the path string actually refers to a previously named object, "under" which you want to accomplish some naming action.

However, the path is sometimes not available, and you only have the object that is represented by the path in the names name space. To support this use-case in a reasonably high-performance way, the path string is can be replaced by the object pointer to which that path would refer. In the spirit of the Config code where this use-case is most prominent, we refer to this object as the "context" for the names operation.

You can think of the context roughly as the inode number of a directory file in Unix. The inode number can be used to look up the directory file which contains the list of file names defined at that directory level. Similarly the context is used to look up an internal name service entry which contains the names defined for that context.

For example, consider a situation where you have previously named an object "/Names/server". If you further want to create an association for between a Ptr<Object> object that you want to live "under" the server in the name space – perhaps "eth0" – you could do this by providing a complete path to the new name: Names::Add ("/Names/server/eth0", object). If, however, somewhere in your code you only had a pointer to the server, say Ptr<Node> node, and not a handy path string, you could also accomplish this by Names::Add (node, "eth0", object).

Duplicate names are not allowed at the same level in a path. In the case of this method, the context object gives the same information as a path string. You may associate similar names with different paths. For example, if you define"/Names/Client", you may not define another "/Names/Client" just as you may not have two files with the same name in a classical filesystem. However, you may have "/Names/Client/eth0" and "/Names/Server/eth0" defined at the same time just as you might have different files of the same name under different directories.

Parameters
[in]contextA smart pointer to an object that is used in place of the path under which you want this new name to be defined.
[in]nameThe name of the object you want to associate.
[in]objectA smart pointer to the object itself.

Definition at line 802 of file names.cc.

References ns3::NamesPriv::Add(), ns3::Singleton< NamesPriv >::Get(), NS_ABORT_MSG_UNLESS, and NS_LOG_FUNCTION.

◆ Clear()

void ns3::Names::Clear ( void  )
static

◆ Find() [1/3]

template<typename T >
Ptr< T > ns3::Names::Find ( std::string  path)
static

Given a name path string, look to see if there's an object in the system with that associated to it.

If there is, do a GetObject on the resulting object to convert it to the requested typename and return it.

An object can be referred to in two ways. Either you can talk about it using its fully qualified path name, for example, "/Names/client/eth0" or you can refer to it by its name, in this case "eth0".

This method requires that the name path of the object be provided, e.g., "Names/client/eth0".

Parameters
[in]pathA string containing a name space path used to locate the object.
Returns
A smart pointer to the named object converted to the requested type.

Definition at line 456 of file names.h.

References FindInternal(), and ns3::Object::GetObject().

◆ Find() [2/3]

template<typename T >
Ptr< T > ns3::Names::Find ( std::string  path,
std::string  name 
)
static

Given a path to an object and an object name, look through the names defined under the path to see if there's an object there with the given name.

In some cases, it is desirable to break up the path used to describe an item in the names namespace into a path and a name. This is analogous to a file system operation in which you provide a directory name and a file name.

For example, consider a situation where you have previously named an object "/Names/server/eth0". If you want to discover the object which you associated with this path, you could do this in two ways, depending on which was more convenient: Names::Find ("/Names/server/eth0") or, using the split path and name approach, Names::Find ("/Names/server", "eth0").

Parameters
[in]pathA path name describing a previously named object under which you want to look for the specified name.
[in]nameA string containing a name to search for.
Returns
A smart pointer to the named object converted to the requested type.

Definition at line 472 of file names.h.

References FindInternal(), and ns3::Object::GetObject().

◆ Find() [3/3]

template<typename T >
Ptr< T > ns3::Names::Find ( Ptr< Object context,
std::string  name 
)
static

Given a path to an object and an object name, look through the names defined under the path to see if there's an object there with the given name.

In some cases, it is desirable to break up the path used to describe an item in the names namespace into a path and a name. This is analogous to a file system operation in which you provide a directory name and a file name.

For example, consider a situation where you have previously named an object "/Names/server/eth0". If you want to discover the object which you associated with this path, you could do this in two ways, depending on which was more convenient: Names::Find ("/Names/server/eth0") or, using the split path and name approach, Names::Find ("/Names/server", "eth0").

However, the path is sometimes not available, and you only have the object that is represented by the path in the names name space. To support this use-case in a reasonably high-performance way, the path string is can be replaced by the object pointer to which that path would refer. In the spirit of the Config code where this use-case is most prominent, we refer to this object as the "context" for the names operation.

You can think of the context roughly as the inode number of a directory file in Unix. The inode number can be used to look up the directory file which contains the list of file names defined at that directory level. Similarly the context is used to look up an internal name service entry which contains the names defined for that context.

Parameters
[in]contextA smart pointer to an object that is used in place of the path under which you want this new name to be defined.
[in]nameA string containing a name to search for.
Returns
A smart pointer to the named object converted to the requested type.

Definition at line 488 of file names.h.

References FindInternal(), and ns3::Object::GetObject().

◆ FindInternal() [1/3]

Ptr< Object > ns3::Names::FindInternal ( std::string  path)
staticprivate

Non-templated internal version of Names::Find.

Parameters
[in]pathA string containing the path of the object to look for.
Returns
A smart pointer to the named object.

Definition at line 840 of file names.cc.

References ns3::NamesPriv::Find(), ns3::Singleton< NamesPriv >::Get(), and NS_LOG_FUNCTION.

Referenced by Find().

◆ FindInternal() [2/3]

Ptr< Object > ns3::Names::FindInternal ( std::string  path,
std::string  name 
)
staticprivate

Non-templated internal version of Names::Find.

Parameters
[in]pathA string containing the path to search for the object in.
[in]nameA string containing the name of the object to look for.
Returns
A smart pointer to the named object.

Definition at line 847 of file names.cc.

References ns3::NamesPriv::Find(), ns3::Singleton< NamesPriv >::Get(), and NS_LOG_FUNCTION.

◆ FindInternal() [3/3]

Ptr< Object > ns3::Names::FindInternal ( Ptr< Object context,
std::string  name 
)
staticprivate

Non-templated internal version of Names::Find.

Parameters
[in]contextA smart pointer to an object under which you want to look for the provided name.
[in]nameA string containing the name to look for.
Returns
A smart pointer to the named object.

Definition at line 854 of file names.cc.

References ns3::NamesPriv::Find(), ns3::Singleton< NamesPriv >::Get(), and NS_LOG_FUNCTION.

◆ FindName()

std::string ns3::Names::FindName ( Ptr< Object object)
static

Given a pointer to an object, look to see if that object has a name associated with it and, if so, return the name of the object otherwise return an empty string.

An object can be referred to in two ways. Either you can talk about it using its fully qualified path name, for example, "/Names/client/eth0" or you can refer to it by its name, in this case "eth0".

This method returns the name of the object, e.g., "eth0".

Parameters
[in]objectA smart pointer to an object for which you want to find its name.
Returns
A string containing the name of the object if found, otherwise the empty string.

Definition at line 819 of file names.cc.

References ns3::NamesPriv::FindName(), ns3::Singleton< NamesPriv >::Get(), and NS_LOG_FUNCTION.

Referenced by Ns2MobilityHelperTest::CourseChange(), ns3::tests::BasicAddTestCase::DoRun(), ns3::tests::StringContextAddTestCase::DoRun(), ns3::tests::FullyQualifiedAddTestCase::DoRun(), ns3::tests::RelativeAddTestCase::DoRun(), ns3::tests::BasicRenameTestCase::DoRun(), ns3::tests::StringContextRenameTestCase::DoRun(), ns3::tests::FullyQualifiedRenameTestCase::DoRun(), ns3::tests::RelativeRenameTestCase::DoRun(), ns3::PcapHelper::GetFilenameFromDevice(), ns3::AsciiTraceHelper::GetFilenameFromDevice(), ns3::PcapHelper::GetFilenameFromInterfacePair(), ns3::AsciiTraceHelper::GetFilenameFromInterfacePair(), ns3::ArpCache::PrintArpCache(), ns3::Ipv4RoutingHelper::PrintArpCache(), ns3::Ipv4RoutingHelper::PrintArpCacheEvery(), ns3::NdiscCache::PrintNdiscCache(), ns3::Ipv6RoutingHelper::PrintNdiscCache(), ns3::Ipv6RoutingHelper::PrintNdiscCacheEvery(), ns3::Ipv4StaticRouting::PrintRoutingTable(), ns3::Ipv4GlobalRouting::PrintRoutingTable(), ns3::Rip::PrintRoutingTable(), ns3::RipNg::PrintRoutingTable(), ns3::Ipv6StaticRouting::PrintRoutingTable(), and ns3::olsr::RoutingProtocol::PrintRoutingTable().

◆ FindPath()

std::string ns3::Names::FindPath ( Ptr< Object object)
static

Given a pointer to an object, look to see if that object has a name associated with it and return the fully qualified name path of the object otherwise return an empty string.

An object can be referred to in two ways. Either you can talk about it using its fully qualified path name, for example, "/Names/client/eth0" or you can refer to it by its name, in this case "eth0".

This method returns the name path of the object, e.g., "Names/client/eth0".

Parameters
[in]objectA smart pointer to an object for which you want to find its fullname.
Returns
A string containing the name path of the object, otherwise the empty string.

Definition at line 826 of file names.cc.

References ns3::NamesPriv::FindPath(), ns3::Singleton< NamesPriv >::Get(), and NS_LOG_FUNCTION.

Referenced by ns3::Uinteger16Probe::ConnectByObject(), ns3::Uinteger32Probe::ConnectByObject(), ns3::Uinteger8Probe::ConnectByObject(), ns3::PacketProbe::ConnectByObject(), ns3::BooleanProbe::ConnectByObject(), ns3::DoubleProbe::ConnectByObject(), ns3::TimeProbe::ConnectByObject(), ns3::ApplicationPacketProbe::ConnectByObject(), ns3::Ipv4PacketProbe::ConnectByObject(), ns3::Ipv6PacketProbe::ConnectByObject(), and ns3::tests::FindPathTestCase::DoRun().

◆ Rename() [1/3]

static void ns3::Names::Rename ( std::string  oldpath,
std::string  newname 
)
static

Rename a previously associated name.

The name may begin either with "/Names" to explicitly call out the fact that the name provided is installed under the root of the name space, or it may begin with the name of the first object in the path. For example, Names::Rename ("/Names/client", "server") and Names::Rename ("client", "server") accomplish exactly the same thing. Names at a given level in the name space path must be unique. In the case of the example above, it would be illegal to try and rename a different object to the same name: "server" at the same level ("/Names") in the path.

As well as specifying a name at the root of the "/Names" namespace, the name parameter can contain a path that fully qualifies the name to be changed. For example, if you previously have (re)named an object "server" in the root namespace as above, you could then rename an object "under" that name by making a call like Names::Rename ("/Names/server/csma", "eth0"). This will rename the object previously associated with "/Names/server/csma" to "eth0" and make leave it reachable using the path "/Names/server/eth0". Note that Names::Rename ("server/csma", "eth0") would accomplish exactly the same thing.

Parameters
[in]oldpathThe current path name to the object you want to change.
[in]newnameThe new name of the object you want to change.
See also
Names::Add (std::string name, Ptr<Object> obj)

Referenced by ns3::tests::BasicRenameTestCase::DoRun(), ns3::tests::StringContextRenameTestCase::DoRun(), ns3::tests::FullyQualifiedRenameTestCase::DoRun(), and ns3::tests::RelativeRenameTestCase::DoRun().

◆ Rename() [2/3]

static void ns3::Names::Rename ( std::string  path,
std::string  oldname,
std::string  newname 
)
static

An intermediate form of Names::Rename allowing you to provide a path to the parent object (under which you want this name to be changed) in the form of a name path string.

In some cases, it is desirable to break up the path used to describe an item in the names namespace into a path and a name. This is analogous to a file system operation in which you provide a directory name and a file name.

For example, consider a situation where you have previously named an object "/Names/server/csma". If you want to change the name "csma" to "eth0", you could do this in two ways, depending on which was more convenient: Names::Rename ("/Names/server/csma", "eth0") or, using the split path and name approach, Names::Rename ("/Names/server", "csma", "eth0").

Parameters
[in]pathA path name describing a previously named object under which you want this name change to occur (cf. directory).
[in]oldnameThe currently defined name of the object.
[in]newnameThe new name you want the object to have.

◆ Rename() [3/3]

static void ns3::Names::Rename ( Ptr< Object context,
std::string  oldname,
std::string  newname 
)
static

A low-level form of Names::Rename allowing you to specify the path to the parent object (under which you want this name to be changed) in the form of a previously named object.

In some use cases, it is desirable to break up the path in the names name space into a path and a name. This is analogous to a file system operation in which you provide a directory name and a file name. Recall that the path string actually refers to a previously named object, "under" which you want to accomplish some naming action.

However, the path is sometimes not available, and you only have the object that is represented by the path in the names name space. To support this use-case in a reasonably high-performance way, the path string is can be replaced by the object pointer to which that path would refer. In the spirit of the Config code where this use-case is most prominent, we refer to this object as the "context" for the names operation.

You can think of the context roughly as the inode number of a directory file in Unix. The inode number can be used to look up the directory file which contains the list of file names defined at that directory level. Similarly the context is used to look up an internal name service entry which contains the names defined for that context.

For example, consider a situation where you have previously named an object "/Names/server/csma". If you later decide to rename the csma object to say "eth0" – you could do this by providing a complete path as in Names::Rename ("/Names/server/csma", "eth0"). If, however, somewhere in your code you only had a pointer to the server, and not a handy path string, say Ptr<Node> node, you could also accomplish this by Names::Rename (node, "csma", "eth0").

Parameters
[in]contextA smart pointer to an object that is used in place of the path under which you want this new name to be defined.
[in]oldnameThe current shortname of the object you want to change.
[in]newnameThe new shortname of the object you want to change.

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