INT FormatTime(
	DWORD dwNetworkTime,
	LPTSTR lpszDateTime,
	INT nMaxLength,
	BOOL bLocalTime
);

INT FormatTime(
	DWORD dwNetworkTime,
	CString& strDateTime,
	BOOL bLocalTime
);

The FormatTime method converts the network time to a string value which contains the date and time formatted for the current locale.

Parameters

dwNetworkTime

An unsigned integer value which specifies the network time. This value should specify the number of seconds since midnight, January 1, 1900 UTC.

lpszDateTime

A null-terminated string buffer which will contain the formatted date and time. This buffer must be large enough to store both date and time values, including the terminating null character. The date is formatted using the current system locale's short date format. The time is formatted to use a 24-hour clock and includes the seconds value. An alternate version of this method accepts a reference to a CString object which will contain the date and time when the method returns.

nMaxLength

The maximum number of characters which can be copied into the string buffer, including the terminating null character. If the buffer is not large enough to contain the entire date and time string, the function will fail and return a value of zero.

bLocalTime

An integer boolean value which specifies if the network time should be adjusted for the local timezone. If this parameter is zero, the date and time are formatted using Coordinated Universal Time (UTC). If this parameter is non-zero, the network time value will be adjusted for the current timezone and will return a localized time value. The current timezone is determined by the configuration of the local system.

Return Value

If successful, the method returns the number of characters copied into the string buffer, not including the terminating null character. If the method fails, it returns a value of zero. Call the GetLastError method for more information about the cause of the failure.

Remarks

The FormatTime method is a convenient way to convert a numeric network time value to a string value which can be displayed to the user. The actual format of the string is determined by the local system configuration and locale. For example, in North America the date string will be returned using a month/day/year format, while European locales may return the date in a day/month/year format.

Example

// Request the time from a server and write it to standard output
CNetworkTime timeClient;
DWORD dwNetworkTime = timeClient.GetTime(_T("time.nist.gov"), TIME_PORT_DEFAULT, TIME_TIMEOUT);

if (dwNetworkTime != 0)
{
    CString strDateTime;
    INT nLength = timeClient.FormatTime(dwNetworkTime, strDateTime, TRUE);
    
    if (nLength > 0)
        _tprintf(_T("The local date and time is %s\n"), (LPCTSTR)strDateTime);
}

Requirements

Minimum Desktop Platform: Windows 7 Service Pack 1
Minimum Server Platform: Windows Server 2008 R2 Service Pack 1
Header File: cstools11.h
Import Library: cstimv11.lib

See Also

ConvertTime, GetTime, SetTime

Copyright © 2025 Catalyst Development Corporation. All rights reserved.