SHFormatDateTime function
[SHFormatDateTime is available for use in the operating systems specified in the Requirements section. It may be altered or unavailable in subsequent versions.]
Produces a string representation of a time specified as a FILETIME structure.
Syntax
int SHFormatDateTime( _In_ const FILETIME UNALIGNED *pft, _Inout_opt_ DWORD *pdwFlags, _Out_ LPTSTR pszBuf, UINT cchBuf );
Parameters
- pft [in]
-
Type: const FILETIME UNALIGNED*
A pointer to the FILETIME structure whose time is to be converted to a string.
- pdwFlags [in, out, optional]
-
Type: DWORD*
A pointer to a DWORD value that contains bitwise flags that specify the date and time format.
When you call the function, you can combine zero or more of the following flags, with exceptions as noted. You can also set this parameter to NULL, in which case the function assumes that the FDTF_DEFAULT flag is set.
-
0x00000001. Formats the time of day as specified by the Regional and Language Options application in Control Panel, but without seconds. This flag cannot be combined with FDTF_LONGTIME.
-
0x00000002. Formats the date as specified by the short date format in the Regional and Language Options application in Control Panel. This flag cannot be combined with FDTF_LONGDATE.
-
Equivalent to FDTF_SHORTDATE | FDTF_SHORTTIME.
-
0x00000004. Formats the date as specified by the long date format in the Regional and Language Options application in Control Panel. This flag cannot be combined with FDTF_SHORTDATE.
-
0x00000008. Formats the time of day as specified by the Regional and Language Options application in Control Panel, including seconds. This flag cannot be combined with FDTF_SHORTTIME.
-
0x00000010. If the FDTF_LONGDATE flag is set and the date in the FILETIME structure is the same date that SHFormatDateTime is called, then the day of the week (if present) is changed to "Today". If the date in the structure is the previous day, then the day of the week (if present) is changed to "Yesterday".
-
0x00000100. Adds marks for left-to-right reading layout. This flag cannot be combined with FDTF_RTLDATE.
-
0x00000200. Adds marks for right-to-left reading layout. This flag cannot be combined with FDTF_LTRDATE.
-
0x00000400. No reading order marks are inserted. Normally, in the absence of the FDTF_LTRDATE or FDTF_RTLDATE flag, SHFormatDateTime determines the reading order from the user's default locale, inserts reading order marks, and updates the pdwFlags output value appropriately. This flag prevents that process from occurring. It is used most commonly by legacy callers of SHFormatDateTime. This flag cannot be combined with FDTF_RTLDATE or FDTF_LTRDATE.
Windows Server 2003 and Windows XP: This value is not available.
When the function returns, the DWORD value pointed to by this parameter can contain zero or more of the following flags.
- pszBuf [out]
-
Type: LPTSTR
A pointer to a buffer that receives the formatted date and time. The buffer must be large enough to contain the number of TCHAR characters specified by the cchBuf parameter, including a terminating null character.
- cchBuf
-
Type: UINT
The number of TCHARs that can be contained by the buffer pointed to by pszBuf.
Return value
Type: int
Returns the number of TCHARs written to the buffer, including the terminating null character. On failure, this value is 0.
Examples
The following code example demonstrates the use of SHFormatDateTime.
#include <windows.h> #include <shlwapi.h> #include <stdio.h> #include <tchar.h> void sample(LPCTSTR pszName, DWORD dwFlags) { FILETIME ft; GetSystemTimeAsFileTime(&ft); TCHAR szBuf[256]; int cch = SHFormatDateTime(&ft, &dwFlags, szBuf, 256); _tprintf(TEXT("%s\n\t%s\n"), pszName, cch ? szBuf : TEXT("<failed>")); } #define trysample(f) sample(TEXT(#f), f) int __cdecl main() { trysample(FDTF_DEFAULT); trysample(FDTF_LONGDATE | FDTF_SHORTTIME); trysample(FDTF_LONGDATE | FDTF_LONGTIME | FDTF_RELATIVE); return 0; } ..................... A typical run of this sample might produce the following output for these flags: FDTF_DEFAULT 5/13/2059 4:36 AM FDTF_LONGDATE | FDTF_SHORTTIME Tuesday, May 13, 2059, 4:36 AM FDTF_LONGDATE | FDTF_LONGTIME | FDTF_RELATIVE Today, May 13, 2059, 4:36:06 AM
Requirements
|
Minimum supported client |
Windows XP [desktop apps only] |
|---|---|
|
Minimum supported server |
Windows Server 2003 [desktop apps only] |
|
End of client support |
Windows XP |
|
End of server support |
Windows Server 2003 |
|
Header |
|
|
Library |
|
|
DLL |
|
|
Unicode and ANSI names |
SHFormatDateTimeW (Unicode) and SHFormatDateTimeA (ANSI) |
See also