Export (0) Print
Expand All
Expand Minimize
This topic has not yet been rated - Rate this topic

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.

FDTF_SHORTTIME (0x00000001)

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.

FDTF_SHORTDATE (0x00000002)

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.

FDTF_DEFAULT

Equivalent to FDTF_SHORTDATE | FDTF_SHORTTIME.

FDTF_LONGDATE (0x00000004)

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.

FDTF_LONGTIME (0x00000008)

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.

FDTF_RELATIVE (0x00000010)

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".

FDTF_LTRDATE (0x00000100)

0x00000100. Adds marks for left-to-right reading layout. This flag cannot be combined with FDTF_RTLDATE.

FDTF_RTLDATE (0x00000200)

0x00000200. Adds marks for right-to-left reading layout. This flag cannot be combined with FDTF_LTRDATE.

FDTF_NOAUTOREADINGORDER (0x00000400)

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.

FDTF_SHORTTIME (0x00000001)

The short time was successfully formatted.

FDTF_SHORTDATE (0x00000002)

The short date was successfully formatted.

FDTF_LONGDATE (0x00000004)

The long date was successfully formatted.

FDTF_LONGTIME (0x00000008)

The long time was successfully formatted.

FDTF_RELATIVE (0x00000010)

Relative notation was used for the date.

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

Shlwapi.h

Library

Shlwapi.lib

DLL

Shlwapi.dll (version 5.0 or later)

Unicode and ANSI names

SHFormatDateTimeW (Unicode) and SHFormatDateTimeA (ANSI)

See also

GetDateFormat
GetTimeFormat

 

 

Did you find this helpful?
(1500 characters remaining)
Thank you for your feedback

Community Additions

ADD
Show:
© 2014 Microsoft. All rights reserved.