Export (0) Print
Expand All
Expand Minimize

GetDurationFormat function

Formats a duration of time as a time string for a locale specified by identifier.

Note  For interoperability reasons, the application should prefer the GetDurationFormatEx function to GetDurationFormat because Microsoft is migrating toward the use of locale names instead of locale identifiers for new locales. Any application that runs only on Windows Vista and later should use GetDurationFormatEx.

Syntax


int GetDurationFormat(
  _In_       LCID Locale,
  _In_       DWORD dwFlags,
  _In_opt_   const SYSTEMTIME *lpDuration,
  _In_       ULONGLONG ullDuration,
  _In_opt_   LPCWSTR lpFormat,
  _Out_opt_  LPWSTR lpDurationStr,
  _In_       int cchDuration
);

Parameters

Locale [in]

Locale identifier that specifies the locale for which this function formats the duration. You can use the MAKELCID macro to create a locale identifier or use one of the following predefined values.

Windows Vista and later: The following custom locale identifiers are also supported.

dwFlags [in]

Flags specifying function options. If lpFormat is not set to NULL, this parameter must be set to 0. If lpFormat is set to NULL, your application can specify LOCALE_NOUSEROVERRIDE to format the string using the system default duration format for the specified locale.

Caution  Use of LOCALE_NOUSEROVERRIDE is strongly discouraged as it disables user preferences.

lpDuration [in, optional]

Pointer to a SYSTEMTIME structure that contains the time duration information to format. If this pointer is NULL, the function ignores this parameter and uses ullDuration.

ullDuration [in]

64-bit unsigned integer that represents the number of 100-nanosecond intervals in the duration. If both lpDuration and ullDuration are present, lpDuration takes precedence. If lpDuration is set to NULL and ullDuration is set to 0, the duration is zero.

lpFormat [in, optional]

Pointer to the format string. For details, see the lpFormat parameter of GetDurationFormatEx.

lpDurationStr [out, optional]

Pointer to the buffer in which the function retrieves the duration string.

Alternatively, this parameter can contain NULL if cchDuration is set to 0. In this case, the function returns the required size for the duration string buffer.

cchDuration [in]

Size, in characters, of the buffer indicated by lpDurationStr.

Alternatively, the application can set this parameter to 0. In this case, the function retrieves NULL in lpDurationStr and returns the required size for the duration string buffer.

Return value

Returns the number of characters retrieved in the buffer indicated by lpDurationStr if successful. If lpDurationStr is set to NULL and cchDuration is set to 0, the function returns the required size for the duration string buffer, including the null terminating character. For example, if 10 characters are written to the buffer, the function returns 11 to include the terminating null character.

The function returns 0 if it does not succeed. To get extended error information, the application can call GetLastError, which can return one of the following error codes:

  • ERROR_INSUFFICIENT_BUFFER. A supplied buffer size was not large enough, or it was incorrectly set to NULL.
  • ERROR_INVALID_PARAMETER. Any of the parameter values was invalid.

Remarks

See Remarks for GetDurationFormatEx.

Requirements

Minimum supported client

Windows Vista [desktop apps only]

Minimum supported server

Windows Server 2008 [desktop apps only]

Header

Winnls.h (include Windows.h)

Library

Kernel32.lib

DLL

Kernel32.dll

See also

National Language Support
National Language Support Functions
GetDateFormat
GetDurationFormatEx
GetLocaleInfo
GetTimeFormat

 

 

Community Additions

ADD
Show:
© 2014 Microsoft