CPJNSNTPClient v1.25

Welcome to CPJNSNTPClient, a collection of freeware C++ classes to encapsulate the SNTP protocol.

Features

• Simple and clean C++ interface.
• The interface provided is synchronous which provides an easier programming model than using asynchronous sockets.
• A configurable timeout for the connection can be set through the class API.
• The classes are fully Unicode compliant and include Unicode build configurations in the project solution file.

Usage

• You need to download the CWSocket class separately from my web site at http://www.naughter.com/w3mfc.html as this module is not provided in the download. Then copy in SocMFC.h and SocMFC.cpp into your applications or the CPJNSNTPClient's sample directory.
• To use the class in your code simply include PJNSNTP.cpp and SocMFC.cpp in your project and #include PJNSNTP.h in which ever of your modules needs to make calls to the SNTP class.
• As of v1.17, the classes are now designed for VC 2017 or later. They will not compile on earlier releases of VC.

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.

History

v1.25 (27 April 2022)

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

v1.24 (3 May 2020)

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

v1.23 (12 March 2020)

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

v1.22 (20 December 2019)

• Fixed various Clang-Tidy static code analysis warnings in the code.
• Updated initialization of various structs to use C++ 11 list initialization.

v1.21 (30 October 2019)

• Fixed a compiler warning in the EnableSetTimePrivilege method. Thanks to Mai Duc Hung for reporting this issue.
• Changed macro references of "CWSOCKET_MFC_EXTENSTIONS" to "CWSOCKET_MFC_EXTENSIONS". Thanks to Mai Duc Hung for reporting this issue.

v1.20 (28 October 2019)

• Updated the code to correctly handle SNTP timestamps greater than the first SNTP epoch date of 6:28:16AM on 7 February 2036. Thanks to Mai Duc Hung for reporting this issue.
• Replaced BOOL with bool throughout the code.

v1.19 (16 September 2019)

• Fixed a number of compiler warnings when the code is compiled with VS 2019 Preview

v1.18 (1 June 2019)

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

v1.17 (19 August 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 PJNSNTP_NO_PRIVILEGE_CODE preprocessor from codebase

v1.16 (18 January 2016)

• Updated copyright details.
• Verified the code compiles cleanly in VC 2015
• Added SAL annotations to all the code

v1.15 (6 April 2015)

• Updated the code to clean compile on VC 2010 and later
• Updated the code to compile with the latest version of the CWSocket class
• Removed all the code which refers to a proxy connection
• Updated the code to operate optionally independent of MFC. If the preprocessor value "CWSOCKET_MFC_EXTENSTIONS" is not defined then the SNTP code will not use MFC, while if it is defined then the code will use MFC. This preprocessor value is used to control the MFC mode of the CWSocket class.
• CPJNSNTPClient::SetClientTime now preserves the last error value and the sample app now reports this value.
• Optimized the implementation of CPJNNTPTime::MsToNtpFraction, NtpFractionToMs & NtpFractionToSecond methods. These optimizations have got rid of the the need for the previous m_MsToNTP lookup table.
• Reworked the CPJNNTPTime::CPJNNTPTime(const SYSTEMTIME& st) constructor to use SystemTimeToFileTime Windows API
• Reworked the CPJNNTPTime::operator SYSTEMTIME() method to use FileTimeToSystemTime Windows API
• The sample app now displays the stratum and leap indicator values from the received SNTP response.

v1.14 (16 March 2009)

• Updated copyright details.
• Included missing VC 2005 solution and project files in the download. Thanks to Michael Haephrati for reporting this issue.

v1.13 (11 July 2008)

• Updated copyright details.
• Updated sample app to clean compile on VC 2008
• Removed VC 6 style classwizard comments from the code.
• The code has now been updated to support VC 2005 or later only.
• Code now compiles cleanly using Code Analysis (/analyze)

v1.12 (5 July 2006)

• Updated copyright details.
• Updated the documentation to use the same style as the web site.
• Code now uses newer C++ style casts instead of C style casts.
• Optimized CPJNNTPTime constructor code.
• Optimized CPJNSNTPClient constructor code
• Replaced calls to ZeroMemory with memset
• Updated code to work with latest version of CWSocket class.
• Made the code more robust in its handling of the m_hToken variable
• Optimized the privilege handling code to avoid the need for the m_bTakenPrivilege variable.
• Verified all code compiles cleanly on VC 2005
• Renamed PJNSNTP_NO_PRIVILEDGE_CODE macro to PJNSNTP_NO_PRIVILEGE_CODE

v1.11 (12 September 2005)

• Fixed problem where code did not handle graceful disconnects when reading the SNTP response.
• Reworked the class to now pass exceptions rather than use a Win32 style return value.
• Renamed the classes to use a prefix of PJN. This is in line with the SMTP class I also provide.

v1.10 (10 July 2005)

• Undone the change made on 04-04-2005 as the calculation of the round trip time calculation was correct. For details on the formulae used, please check out RFC 2030. Thanks to Thomas Fejes for reporting this problem.

18 May 2005

• Updated usage section for the code.

V1.09 (4 April 2005)

• Fix for a bug in the calculation of the m_RoundTripDelay value. Thanks to Euan Lee for reporting this bug.

V1.08 (17 March 2005)

• Updated to work with the latest release of CWSocket. Thanks to Alex Dron for reporting this issue.
• Addition of a preprocessor macro "PJNSNTP_EXT_CLASS" which allows the code to be easily added to an extension DLL.
• General tidy up of the code in CSNTPClient::GetServerTime
• Replaced the macro _WIN32_WCE with PJNSNTP_NO_PRIVILEDGE_CODE. This allows the priviledge code to also be excluded on desktop versions of Windows if so desired.
• Reviewed and updated all the TRACE statements for correctness.

V1.07 (21 September 2003)

• Class now uses CWSocket class (which you will need to download separately) to provide sockets capability. This now allows the class to support connecting via a Socks 5 proxy.

V1.06 (13 March 2003)

• Fixed a bug in CNtpSocket::IsReadible in the setup of the timeval structure. Thanks to "InBloom Support" for reporting this.

V1.05 (25 August 2002)

• Updated sample app to work correctly for the Unicode configurations
• Sample app now uses CWinApp instance in sample app
• Sample app now uses MFC support for initializing Winsock stack
• Sample app now uses MFC support for parsing its command line.

V1.04 (29 March 2001)

• Updated copyright message
• Fixed a handle leak RevertSetTimePriviledge where the process token was not been closed

V1.03 (23 July 2000)

• Added Windows CE 2.11 compatibility. Thanks to Andre Rippstein for the work.

V1.02 (25 June 2000)

• Fixed an issue where the packing order of the NtpBasicInfo struct was causing problems. Now packing is set to 1 byte for this struct.

V1.01 (16 November 1998)

• m_nOriginateTime was getting set incorrectly in the SNTP response. Has now been fixed.
• GetLastError now works when a timeout occurs.

V1.0 (8 August 1998)

• Initial public release.

API Reference

The API consists of the classes:

CPJNNTPTime

This is an encapsulation of a time instance as used in the SNTP protocol. This consists of a 64 bit unsigned integer with the top 32 bits containing the number of seconds since 1st January 1900 and the lower 32 bits contain the fraction of seconds.

CPJNNTPTime
AsSYSTEMTIME
AsFILETIME
operator CPJNNTPTimePacket
operator unsigned __int64
Seconds
SecondsAsDouble
Milliseconds
Fraction
GetCurrentTime
MsToNtpFraction
NtpFractionToMs

CPJNNTPServerResponse

This is a simple encapsulation of the information retrieved from the SNTP server. It contains:

m_nLeapIndicator
m_nStratum
m_OriginateTime
m_ReceiveTime
m_TransmitTime
m_DestinationTime
m_RoundTripDelay
m_LocalClockOffset

CPJNSNTPClient

The actual class to call to perform a time lookup is CPJNSNTPClient and it consists of:

CPJNSNTPClient
GetServerTime
GetTimeout
SetTimeout
SetClientTime

CPJNNTPTime::CPJNNTPTime

CPJNNTPTime();
CPJNNTPTime(const CPJNNTPTime& time);
CPJNNTPTime(CPJNNTPTime&& time);
CPJNNTPTime(const CPJNNTPTimePacket& packet);
CPJNNTPTime(const SYSTEMTIME& st);

Parameters

time Another CPJNNTPTime instance.

packet An CPJNNTPTimePacket instance. This is a simple struct representing the data as sent over the wire.

st A Win32 SDK SYSTEMTIME instance.

Remarks

Standard C++ constructor.

CPJNNTPTime::AsSYSTEMTIME

SYSTEMTIME AsSYSTEMTIME() const;

Remarks

Returns a SDK SYSTEMTIME representation of the NTP time.

CPJNNTPTime::AsFILETIME

FILETIME AsFILETIME() const;

Remarks

Returns a SDK FILETIME representation of the NTP time.

CPJNNTPTime::operator CPJNNTPTimePacket

operator CPJNNTPTimePacket() const;

Remarks

Returns a CPJNNTPTimePacket representation of an NTP time. This structure is the actual value which gets transmitted to the SNTP server.

CPJNNTPTime::operator unsigned __int64

operator unsigned __int64() const;

Remarks

Returns an unsigned int64 representation of the NTP time.

CPJNNTPTime::Seconds

DWORD Seconds() const;

Remarks

Returns the total number of seconds which this NTP time represents

CPJNNTPTime::SecondsAsDouble

double SecondsAsDouble() const;

Remarks

Returns the total number of seconds and fractions of a second which this NTP time represents

CPJNNTPTime::Milliseconds

DWORD Milliseconds() const;

Remarks

Returns the fractional part of seconds which this NTP time represents as milliseconds

CPJNNTPTime::Fraction

DWORD Fraction() const;

Remarks

Returns the fractional part of seconds which this NTP time represents.

CPJNNTPTime::GetCurrentTime

static CPJNNTPTime GetCurrentTime();

Remarks

Returns an NTP time instance which represents the current UTC time of the machine.

CPJNNTPTime::MsToNtpFraction

static DWORD MsToNtpFraction(WORD wMilliSeconds);

Remarks

Converts a count of milliseconds to an NTP fractional.

CPJNNTPTime::NtpFractionToMs

static WORD NtpFractionToMs(DWORD dwFraction);

Remarks

Converts an NTP fractional to a count of milliseconds.

PJNNTPServerResponse::m_nLeapIndicator

int m_nLeapIndicator;

Remarks

This value will contain one of the following values:

0: no warning
1: last minute in day has 61 seconds
2: last minute has 59 seconds
3: clock not synchronized

PJNNTPServerResponse::m_nStratum

int m_nStratum;

Remarks

This value will contain the stratum level of the server. It will be one of the following values:

0: unspecified or unavailable
1: primary reference (e.g., radio clock)
2-15: secondary reference (via NTP or SNTP)
16-255: reserved

PJNNTPServerResponse::m_nOriginateTime

CPJNNTPTime m_OriginateTime;

Remarks

This is the client time when the request was sent from the client to the SNTP server.

PJNNTPServerResponse::m_ReceiveTime

CPJNNTPTime m_ReceiveTime;

Remarks

This is the server time when the request was received by the SNTP server from the client.

PJNNTPServerResponse::m_TransmitTime

CPJNNTPTime m_TransmitTime;

Remarks

This is the server time when the server sent the request back to the client.

PJNNTPServerResponse::m_DestinationTime

CPJNNTPTime m_DestinationTime;

Remarks

This is the client time when the reply was received by the client.

PJNNTPServerResponse::m_RoundTripDelay

double m_RoundTripDelay;

Remarks

This is the round trip time in seconds for the NTP request. It is calculated as:

m_RoundTripDelay = (m_DestinationTime - m_OriginateTime) - (m_ReceiveTime - m_TransmitTime);

PJNNTPServerResponse::m_LocalClockOffset

double m_LocalClockOffset;

Remarks

This is the local clock offset relative to the server. This is calculated as:

LocalClockOffset = ((m_ReceiveTime - m_OriginateTime) + (m_TransmitTime - m_DestinationTime)) / 2.

CPJNSNTPClient::CPJNSNTPClient

CPJNSNTPClient();

Remarks

Standard C++ constructor which initializes the timeout to a default value of 5 seconds.

CPJNSNTPClient::GetServerTime

void GetServerTime(LPCTSTR pszHostName, NtpServerResponse& response, int nPort = 123);

Parameters

pszHostName The network address of the SNTP server to connect to: a machine name such as “ntp.maths.tcd.ie”, or a dotted number such as “128.56.22.8” will both work.

response Upon a successful call to this function, this will contain all the information relating to the SNTP server.

nPort This is the port number of which to make a SNTP request. The default value is 123.

Remarks

This performs the actual SNTP query and returns the relevant information back in the response structure. You are then free to decide if you want to set the local time using the values retrieved. Please note that this method can and will throw CWSocketException exceptions and client code should be prepared to handle this.

CPJNSNTPClient::GetTimeout

DWORD GetTimeout() const;

Return Value

The current timeout to use for socket calls which will block while doing the SNTP query.

CPJNSNTPClient::SetTimeout

void SetTimeout(DWORD dwTimeout);

Parameters

dwTimeout The new timeout to use for socket calls which will block while doing the SNTP query.

CPJNSNTPClient::SetClientTime

bool SetClientTime(const SYSTEMTIME& st, bool bEnableSetTimePrivilege = true);

Parameters

st The time to be set.

bEnableSetTimePrivlege true to call the AdjustTokenPrivileges API to enable the SE_SYSTEMTIME_NAME privilege prior to setting the time.

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.

Remarks

Given a time, this function will set the client system time. Internally it looks after setting privileges which is required on NT because of its security mode..

Contacting the Author

PJ Naughter
Email: pjna@naughter.com
Web: http://www.naughter.com
27 April 2022