Windows API Guide - Reference - Volume 1: Version 3.0 For the MS-DOS and PC-DOS Operating Systems

2017-07-07 02:10:07

Declare Function GetTimeFormat Lib "kernel32.dll" Alias "GetTimeFormatA" (ByVal Locale As Long, ByVal dwFlags As Long, lpTime As SYSTEMTIME, ByVal lpFormat As Any, ByVal lpTimeStr As String, ByVal cchTime As Long) As Long

Platforms

Windows 95: Supported.
Windows 98: Supported.
Windows NT: Requires Windows NT 3.5 or later.
Windows 2000: Supported.
Windows CE: Requires Windows CE 1.0 or later.

Description & Usage

GetTimeFormat formats a string to display a time according to a locale's settings. The time can be formatted using either a predefined format or a custom format specified in the parameter list. The string generated by this function can be used to present a more human-readable way to display a time.

Return Value

If an error occured, the function returns 0 (use GetLastError to get the error code). If successful, the function returns the size in bytes of the string placed into the variable passed as lpTimeStr.

Visual Basic-Specific Issues

When passing 0 for the lpFormat parameter, the expression CLng(0) must be used.

Parameters

Locale

The identifier of the locale to use to format the string as necessary. If this is 0, the locale of the calling thread is used. This can also be one of the following flags specifying a default locale:

LOCALE_SYSTEM_DEFAULT: The system's default locale.
LOCALE_USER_DEFAULT: The user's default locale.

dwFlags

A combination of the following flags specifying how to format the time string. If a format string is passed as lpFormat, this parameter must be set to 0.

LOCALE_NOUSEROVERRIDE: Use the system's default time format for the specified locale, ignoring any changes to those defaults which the user may have selected.
LOCALE_USE_CP_ACP: Use the system's ANSI code page for string translation instead of the locale's code page.
TIME_NOMINUTESORSECONDS: Do not display minutes or seconds.
TIME_NOSECONDS: Do not display seconds.
TIME_NOTIMEMARKER: Do not display an AM/PM marker.
TIME_FORCE24HOURFORMAT: Use a 24-hour time format.

lpTime

The time to format as a string. The members of the structure which specify the date are ignored.

lpFormat

The format template string used to generate the time string. To use one of the predefined formats, this parameter must be 0. In a format template string, the following series of characters stand for the following components of the time:

h: Hours without a leading zero for single-digit hours, using a 12-hour clock.
hh: Hours with a leading zero for single-digit hours, using a 12-hour clock.
H: Hours without a leading zero for single-digit hours, using a 24-hour clock.
HH: Hours with a leading zero for single-digit hours, using a 24-hour clock.
m: Minutes without a leading zero for single-digit minutes.
mm: Minutes with a leading zero for single-digit minutes.
s: Seconds without a leading zero for single-digit seconds.
ss: Seconds with a leading zero for single-digit seconds.
t: A one-character AM/PM indicator.
tt: A two-character AM/PM indicator.

Any spaces appearing in the template string appear verbatim in the formatted string. To place any other "fixed" characters or text in the format string, you must enclose the literal text in single quotation marks.

lpTimeStr

Receives the formatted time string. This must initally be sufficiently long to receive the string.

cchTime

The length of the string passed as lpTimeStr.

Constant Definitions

Const LOCALE_SYSTEM_DEFAULT = &H400 Const LOCALE_USER_DEFAULT = &H800 Const LOCALE_NOUSEROVERRIDE = &H80000000 Const LOCALE_USE_CP_ACP = &H40000000 Const TIME_NOMINUTESORSECONDS = &H1 Const TIME_NOSECONDS = &H2 Const TIME_NOTIMEMARKER = &H4 Const TIME_FORCE24HOURFORMAT = &H8

Example

' This code is licensed according to the terms and conditions listed here. ' Display today's time first using a "regular" hours-minutes- ' AM/PM string and then using a "military hours" format (e.g., 8:27 AM is 0827 hours). Dim today As SYSTEMTIME ' today's date and time Dim timestr As String ' receives the formatted time string Dim strlen As Long ' length of the buffer for the formatted time string ' Get today's date and time in the local time zone. GetLocalTime today ' Make sufficient room in the buffer to receive the time string. timestr = Space(255) ' Format today's time as hours-minutes-AM/PM. strlen = GetTimeFormat(0, TIME_NOSECONDS, today, CLng(0), timestr, Len(timestr)) ' Remove the empty space from the formatted time string. timestr = Left(timestr, strlen) ' Display today's time using that format. Debug.Print "It is currently "; timestr ' Now make sufficient room once again. timestr = Space(255) ' Format today's time in the military-esque format. strlen = GetTimeFormat(0, 0, today, "HHmm 'hours'", timestr, Len(timestr)) ' Remove the empty space from the formatted string. timestr = Left(timestr, strlen) ' Display today's time in aforementioned format. Debug.Print "It is currently "; timestr