CTraceRoute v1.20

Welcome to CTraceRoute, a freeware C++ class to implement "TraceRoute" functionality on Windows.

Features

• Simple and clean C++ interface.
• The interface provided is synchronous which provides an easier programming model than using asynchronous sockets.
• virtual functions are provided to support callback.
• A configurable timeout can be set through the class API.
• The classes are fully Unicode compliant and include Unicode built options in the workspace file.

Copyright

• You are allowed to include the source code in any product (commercial, shareware, freeware or otherwise) when your product is released in binary form.
• You are allowed to modify the source code in any way you want except you cannot modify the copyright details at the top of each module.
• If you want to distribute source code with your application, then you are only allowed to distribute versions released by the author. This is to maintain a single distribution point for the source code.

Usage

• To use the class in your code simply include tracer.cpp in your project and #include tracer.h in which ever of your modules needs to make calls to the class.
• You will need to download the Author's CPing class from http://www.naughter.com/ping.html as this class is required by the CTraceRoute class and is not included in this distribution.
• The code will work just as well in a GUI or console app.

History

v1.20 (18 March 2022)

• Updated copyright details.
• Updated the code to use C++ uniform initialization for all variable declarations.

v1.19 (28 March 2020)

• Updated copyright details.
• Fixed more Clang-Tidy static code analysis warnings in the code.

v1.18 (29 December 2019)

• Fixed various Clang-Tidy static code analysis warnings in the code.

v1.17 (10 November 2019)

• Updated initialization of various structs to use C++ 11 list initialization
• Replaced BOOL with bool in a number of places throughout the codebase

v1.16 (5 May 2019)

• Updated copyright details.
• Updated the code to clean compile on VC 2019

v1.15 (3 November 2018)

• Updated copyright details.
• Fixed a number of C++ core guidelines compiler warnings. These changes mean that the code will now only compile on VC 2017 or later.
• Removed all code which used GetProcAddress in the sample app.
• Removed code which supported CTRACEROUTE_MFC_EXTENSTIONS code path

v1.14 (26 December 2017)

• Updated copyright details.
• Replaced CString::operator LPC*STR() calls throughout the codebase with CString::GetString calls
• Replaced NULL throughout the codebase with nullptr. This means that the minimum requirement for the code is now VC 2010.

v1.13 (8 May 2016)

• Updated copyright details.
• Updated the sample project settings to more modern default values.
• Updated the code to compile cleanly on VC 2010 - 2015.
• Added support for IPv6 in addition to IPv4. This means that the minimum supported version of VC which supports CTraceRoute is now VC 2008. The sample now ships with a VC 2008 solution.
• Added SAL annotations to all the code.
• Reworked the classes to optionally compile without MFC. By default the classes now use STL classes and idioms but if you define CTRACEROUTE_MFC_EXTENSTIONS the classes will revert back to the MFC behaviour

v1.12 (7 June 2008)

• Updated copyright details
• Addition of TRACEROUTE_EXT_CLASS define to the classes to allow the classes to be more easily incorporated into extension DLLs
• Updated the code to work with latest version of the author's CPing class
• Updated the sample app to compile cleanly in VC 2005
• The code has now been updated to support VC 2005 or later only
• Code now uses newer C++ style casts instead of C style casts
• Code now compiles cleanly using Code Analysis (/analyze)
• Updated the code to clean compile on VC 2008
• Updated documentation to use the same style as the web site

v1.11 (5 May 2002)

• Uses latest CPing class, now by default uses ICMP method in CPing class.
• Sample app provided with tracer now actually observes the "-d" command line option.
• Fixed a bug where a pinging error would cause the tracer loop to exit instead of reporting a non-pingable device

v1.1 (25 February 2002)

• Updated copyright information
• Class now #includes CPing class rather than implementing its own implementation of Ping
• General code tidy up and review

v1.0 (18 November 1998)

• Initial public release.

API Reference

The API consists of the the 3 classes:

CTraceRouteReplyv4 / CTraceRouteReplyv6
CTraceRoute

CTraceRouteReplyv4 / CTraceRouteReplyv6

This is an encapsulation of all the information as returned from a trace route request. The v4 class represents a reply when using IPv4 and the v6 class represents a reply when using IPv6.

The members of CHostTraceMultiReplyv4 / CHostTraceMultiReplyv6 are as follows:

CTraceRoute

Tracev4/Tracev6
OnPingResult
OnSingleHostResult

CTraceRoute::Trace

bool CTraceRoute::Tracev4(LPCTSTR pszHostName, CReplyv4& trr, UCHAR nHopCount = 30, DWORD dwTimeout = 30000, DWORD dwPingsPerHost = 3, WORD wDataSize = 32, UCHAR nTOS = 0, bool bDontFragment = false, bool bFlagReverse = false, LPCTSTR pszLocalBoundAddress = nullptr) const

bool CTraceRoute::Tracev6(LPCTSTR pszHostName, CReplyv6& trr, UCHAR nHopCount = 30, DWORD dwTimeout = 30000, DWORD dwPingsPerHost = 3, WORD wDataSize = 32, UCHAR nTOS = 0, bool bDontFragment = false, bool bFlagReverse = false, LPCTSTR pszLocalBoundAddress = nullptr ) const

Return Value

If the function succeeds, the return value is true. If the function fails, the return value is false. To get extended error information, call ::GetLastError.

Parameters

pszHostName The network address of the socket to connect to: a machine name such as “ftp.yourisp.com”, or a dotted number such as “128.56.22.8” will both work.

trr Upon successful return, this will contain all the information related to the trace route request. See CTraceRouteReply for further details.

nHopCount This is the maximum TTL to use. This corresponds to the farthest router which the ping request will reach.

dwTimeout The timeout for each ping in milliseconds.

dwPingsPerHost The number of pings to perform per host.

wDataSize This is the size of the data to transmit in the ICMP packet.

nTOS The Type of Service IP header field to use

bDontFragment Sets the Don't fragment IP header field

bFlagReverse Sets the Flag Reverse IP header field

pszLocalBoundAddress The local address to bind the request to

Remarks

These functions implements the trace route functionality. The Tracev4 method uses IPv4 while the Tracev6 method uses IPv6.

CTraceRoute::OnPingResult

virtual bool CTraceRoute::OnPingResult(int nPingNum, const CHostTraceSingleReplyv4 htsr);

virtual bool CTraceRoute::OnPingResult(int nPingNum, const CHostTraceSingleReplyv6 htsr);

Return Value

return true to continue the trace route. Returning false will cancel the operation.

Parameters

nPingNum The ping reply which this function is being called for.

htsr Contains the actual results from the ping for this host

Remarks

These functions are called just after each ping reply. You can derive your own class from CTraceRoute and override these functions so that your version is called at the appropriate times

CTraceRoute::OnSingleHostResult

virtual bool CTraceRoute::OnSingleHostResult(int nHostNum, const CHostTraceMultiReplyv4& htmr);

virtual bool CTraceRoute::OnSingleHostResult(int nHostNum, const CHostTraceMultiReplyv6& htmr);

Return Value

return true to continue the trace route. Returning false will cancel the operation.

Parameters

nHostNum The current host which this function is being called for.

htmr Contains the collective results from the ping for this host

Remarks

These functions are called just after all the pings for each host is complete. You can derive your own class from CTraceRoute and override these functions so that your version is called at the appropriate times. See the CMyTraceRoute class in main.cpp for a concrete implementation.

Contacting the Author

PJ Naughter
Email: pjna@naughter.com
Web: http://www.naughter.com
18 March 2022