getTimeFormatA 函数 (datetimeapi.h)

  • 项目

将时间格式化为由标识符指定的区域设置的时间字符串。 函数设置指定时间或本地系统时间的格式。

注意 出于互操作性原因，应用程序应优先使用 GetTimeFormatEx 函数而不是 GetTimeFormat ，因为 Microsoft 正在迁移到使用区域设置名称而不是新区域设置的区域设置标识符。 将仅在 Windows Vista 和更高版本上运行的任何应用程序都应使用 GetTimeFormatEx。
 

语法

int GetTimeFormatA(
  [in]            LCID             Locale,
  [in]            DWORD            dwFlags,
  [in, optional]  const SYSTEMTIME *lpTime,
  [in, optional]  LPCSTR           lpFormat,
  [out, optional] LPSTR            lpTimeStr,
  [in]            int              cchTime
);

参数

[in] Locale

指定区域设置的区域设置标识符。 可以使用 MAKELCID 宏创建区域设置标识符或使用以下预定义值之一。

[in] dwFlags

指定时间格式选项的标志。 有关详细定义，请参阅 GetTimeFormatEx 的 dwFlags 参数。

[in, optional] lpTime

指向 SYSTEMTIME 结构的指针，该结构包含要设置格式的时间信息。 如果函数要使用当前本地系统时间，则应用程序可以将此参数设置为 NULL 。

[in, optional] lpFormat

指向用于设置时间字符串格式的格式图片的指针。 如果应用程序将此参数设置为 NULL，则该函数会根据指定区域设置的时间格式设置字符串的格式。 如果应用程序未将 参数设置为 NULL，则该函数仅对格式图片字符串中未指定的信息（例如特定于区域设置的时间标记）使用区域设置。 有关格式图片字符串的信息，请参阅“备注”部分。

[out, optional] lpTimeStr

指向缓冲区的指针，此函数在其中检索格式化的时间字符串。

[in] cchTime

lpTimeStr 指示的时间字符串缓冲区的大小（以 TCHAR 值为单位）。 或者，应用程序可以将此参数设置为 0。 在这种情况下，该函数返回时间字符串缓冲区所需的大小，并且不使用 lpTimeStr 参数。

返回值

返回在 lpTimeStr 指示的缓冲区中检索到的 TCHAR 值的数目。 如果 cchTime 参数设置为 0，则该函数将返回保存格式化时间字符串（包括终止 null 字符）所需的缓冲区大小。

如果未成功，则此函数返回 0。 若要获取扩展的错误信息，应用程序可以调用 GetLastError，这会返回以下错误代码之一：

  • ERROR_INSUFFICIENT_BUFFER。 提供的缓冲区大小不够大，或者错误地设置为 NULL。
  • ERROR_INVALID_FLAGS。 为标志提供的值无效。
  • ERROR_INVALID_PARAMETER。 任何参数值都无效。
  • ERROR_OUTOFMEMORY。 没有足够的存储空间来完成此操作。

注解

请参阅 GetTimeFormatEx 的备注。

当此函数的 ANSI 版本与仅限 Unicode 的区域设置标识符一起使用时，该函数可以成功，因为操作系统使用系统代码页。 但是，系统代码页中未定义的字符在字符串中显示为问号 (？) 。

从 Windows 8 开始：GetTimeFormat 在 Datetimeapi.h 中声明。 在Windows 8之前，它在 Winnls.h 中声明。

注意

datetimeapi.h 标头将 GetTimeFormat 定义为别名，该别名根据 UNICODE 预处理器常量的定义自动选择此函数的 ANSI 或 Unicode 版本。 将非特定编码别名与非非特定编码的代码混合使用可能会导致不匹配，从而导致编译或运行时错误。 有关详细信息，请参阅 函数原型的约定。

要求

要求 值
最低受支持的客户端 Windows 2000 Professional [仅限桌面应用]
最低受支持的服务器 Windows 2000 Server [仅限桌面应用]
目标平台 Windows
标头 datetimeapi.h
Library Kernel32.lib
DLL Kernel32.dll

另请参阅

GetDateFormat

GetLocaleInfo

GetTimeFormatEx

国家/地区语言支持

国家/地区语言支持函数