CSNTPClient - An SNTP Implementation

Welcome to CSNTPClient, a collection of freeware MFC 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.
• Raw sockets are used instead of MFC sockets. This means that the code will work in a console application without any problems.
• A configurable timeout for the connection can be set through the class API.
• The classes are fully Unicode compliant and include Unicode built options in the workspace file.

Usage

• To use the class in your code simply include sntp.cpp in your project and #include sntp.h in which ever of your modules needs to make calls to the class.
• Your code will need to include MFC either statically or dynamically.
• You will need to have a functioning winsock stack installed as the code links to winsock.dll.
• You will also need to have winsock.h or afxsock.h and afxpriv.h in your precompiled header. The code should also work in a multithreaded application, although it has not be explicitly tested in this scenario.

History

• Initial public release.

V1.01 (16th November 1998)

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

API Reference

CNtpTime:

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.

CNtpTime
operator=
operator-
operator+
operator SYSTEMTIME
operator CNtpTimePacket
operator unsigned __int64
Seconds
Fraction
GetCurrentTime
MsToNtpFraction
NtpFractionToMs
NtpFractionToSecond

NtpServerResponse

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

CSNTPClient

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

CSNTPClient
GetServerTime
GetTimeout
SetTimeout
SetClientTime

CNtpTime::CNtpTime

CNtpTime();
CNtpTime(const CNtpTime& time);
CNtpTime(CNtpTimePacket& packet);
CNtpTime(const SYSTEMTIME& st);

Parameters:

• time -- Another CNtpTime instance.
• packet -- An CNtpTimePacket instance. This is a simple struct representing the data as sent over the wire.
• st -- A Win32 SDK SYSTEMTIME instance.

Remarks:
Standard C++ constructor.

CNtpTime::operator=

CNtpTime& operator=(const CNtpTime& time);

Remarks:
Standard operator= for the class.

CNtpTime::operator-

double operator-(const CNtpTime& time) const;

Remarks:
Standard operator- for the class.

CNtpTime::operator+

CNtpTime operator+(const double& timespan) const;

Remarks:
Standard operator+ for the class.

CNtpTime::operator SYSTEMTIME

operator SYSTEMTIME() const;

Remarks:
Returns a SDK SYSTEMTIME representation of the Ntp time.

CNtpTime::operator CNtpTimePacket

operator CNtpTimePacket() const;

Remarks:
Returns a CNtpTimePacket representation of an Ntp time. This structure is the actual value which gets transmitted to the SNTP server.

CNtpTime::operator unsigned __int64

operator unsigned __int64() const;

Remarks:
Returns an unsigned int64 representation of the Ntp time.

CNtpTime::Seconds

DWORD Seconds() const;

Remarks:
Returns the total number of seconds which this Ntp time represents.

CNtpTime::Fraction

DWORD Fraction() const;

Remarks:
Returns the fractional part of seconds which this Ntp time represents.

CNtpTime::GetCurrentTime

static CNtpTime GetCurrentTime();

Remarks:
Constructs an NtpTime instance which represents the current UTC time of the machine.

CNtpTime::MsToNtpFraction

static DWORD MsToNtpFraction(WORD wMilliSeconds);

Remarks:
Converts a count of milliseconds to an Ntp fractional.

CNtpTime::NtpFractionToMs

static WORD NtpFractionToMs(DWORD dwFraction);

Remarks:
Converts an Ntp fractional to a count of milliseconds.

CNtpTime::NtpFractionToSecond

static double NtpFractionToSecond(DWORD dwFraction);

Remarks:
Converts an Ntp fractional to a fraction of a second as a floating point value.

CNtpTime::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

CNtpTime::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

CNtpTime::m_nOriginateTime

CNtpTime m_OriginateTime;

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

CNtpTime::m_ReceiveTime

CNtpTime m_ReceiveTime;

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

CNtpTime::m_TransmitTime

CNtpTime m_TransmitTime;

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

CNtpTime::m_DestinationTime

CNtpTime m_DestinationTime;

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

CNtpTime::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);

CNtpTime::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;

This value can then be used to set the local time by a simple call as follows:
CNtpTime newSynchronizedTime(CNtpTime::GetCurrentTime() + m_LocalClockOffset);

CSNTPClient::CSNTPClient

CSNTPClient();

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

CSNTPClient::GetServerTime

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

Return Value:
If the function succeeds, the return value is nonzero. If the function fails, the return value is zero. To get extended error information, call GetLastError().

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.

CSNTPClient::GetTimeout

DWORD GetTimeout() const;

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

CSNTPClient::SetTimeout

void SetTimeout(DWORD dwTimeout);

Parameters:

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

CSNTPClient::SetClientTime

BOOL SetClientTime(const CNtpTime& NewTime);

Return Value:
If the function succeeds, the return value is nonzero. If the function fails, the return value is zero. To get extended error information, call GetLastError().

Parameters:

• NewTime -- An Ntp time representation of the time to be use to set the client time.

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.

Planned Enhancements

• If you have any other suggested improvements, please let me know so that I can incorporate them into the next release.

Contacting the Author