Fungsi GetTimeFormatEx (datetimeapi.h)

Artikel
04/06/2023

Memformat waktu sebagai string waktu untuk lokal yang ditentukan oleh nama. Fungsi memformat waktu yang ditentukan atau waktu sistem lokal.

Catatan Aplikasi harus memanggil fungsi ini disukai ke GetTimeFormat jika dirancang untuk berjalan hanya di Windows Vista dan yang lebih baru.

Catatan Fungsi ini dapat memformat data yang berubah antar rilis, misalnya, karena lokal kustom. Jika aplikasi Anda harus mempertahankan atau mengirimkan data, lihat Menggunakan Data Lokal Persisten.

Sintaks

int GetTimeFormatEx(
  [in, optional]  LPCWSTR          lpLocaleName,
  [in]            DWORD            dwFlags,
  [in, optional]  const SYSTEMTIME *lpTime,
  [in, optional]  LPCWSTR          lpFormat,
  [out, optional] LPWSTR           lpTimeStr,
  [in]            int              cchTime
);

Parameter

[in, optional] lpLocaleName

Arahkan ke nama lokal, atau salah satu nilai yang telah ditentukan sebelumnya berikut ini.

[in] dwFlags

Bendera yang menentukan opsi format waktu. Aplikasi dapat menentukan kombinasi nilai dan LOCALE_USE_CP_ACP atau LOCALE_NOUSEROVERRIDE berikut.

Hati Penggunaan LOCALE_NOUSEROVERRIDE sangat tidak disarankan karena menonaktifkan preferensi pengguna.

Nilai	Makna
TIME_NOMINUTESORSECONDS	Jangan gunakan menit atau detik.
TIME_NOSECONDS	Jangan gunakan detik.
TIME_NOTIMEMARKER	Jangan gunakan penanda waktu.
TIME_FORCE24HOURFORMAT	Selalu gunakan format waktu 24 jam.

[in, optional] lpTime

Penunjuk ke struktur SYSTEMTIME yang berisi informasi waktu untuk diformat. Aplikasi dapat mengatur parameter ini ke NULL jika fungsinya adalah menggunakan waktu sistem lokal saat ini.

[in, optional] lpFormat

Penunjuk ke gambar format yang akan digunakan untuk memformat string waktu. Jika aplikasi mengatur parameter ini ke NULL, fungsi memformat string sesuai dengan format waktu lokal yang ditentukan. Jika aplikasi tidak mengatur parameter ke NULL, fungsi hanya menggunakan lokal untuk informasi yang tidak ditentukan dalam format string gambar, misalnya, penanda waktu khusus lokal. Untuk informasi tentang format string gambar, lihat bagian Keterangan.

[out, optional] lpTimeStr

Penunjuk ke buffer tempat fungsi ini mengambil string waktu yang diformat.

[in] cchTime

Ukuran, dalam karakter, untuk buffer string waktu yang ditunjukkan oleh lpTimeStr. Atau, aplikasi dapat mengatur parameter ini ke 0. Dalam hal ini, fungsi mengembalikan ukuran yang diperlukan untuk buffer string waktu, dan tidak menggunakan parameter lpTimeStr .

Nilai kembali

Mengembalikan jumlah karakter yang diambil dalam buffer yang ditunjukkan oleh lpTimeStr. Jika parameter cchTime diatur ke 0, fungsi mengembalikan ukuran buffer yang diperlukan untuk menahan string waktu yang diformat, termasuk karakter null yang mengakhiri.

Fungsi ini mengembalikan 0 jika tidak berhasil. Untuk mendapatkan informasi kesalahan yang diperluas, aplikasi dapat memanggil GetLastError, yang dapat mengembalikan salah satu kode kesalahan berikut:

ERROR_INSUFFICIENT_BUFFER. Ukuran buffer yang disediakan tidak cukup besar, atau salah diatur ke NULL.
ERROR_INVALID_FLAGS. Nilai yang diberikan untuk bendera tidak valid.
ERROR_INVALID_PARAMETER. Salah satu nilai parameter tidak valid.
ERROR_OUTOFMEMORY. Penyimpanan tidak cukup tersedia untuk menyelesaikan operasi ini.

Keterangan

Jika penanda waktu ada dan bendera TIME_NOTIMEMARKER tidak diatur, fungsi melokalisasi penanda waktu berdasarkan pengidentifikasi lokal yang ditentukan. Contoh penanda waktu adalah "AM" dan "PM" untuk bahasa Inggris (Amerika Serikat).

Nilai waktu dalam struktur yang ditunjukkan oleh lpTime harus valid. Fungsi ini memeriksa setiap nilai waktu untuk menentukan bahwa nilai berada dalam rentang nilai yang sesuai. Jika salah satu nilai waktu berada di luar rentang yang benar, fungsi gagal, dan mengatur kesalahan terakhir ke ERROR_INVALID_PARAMETER.

Fungsi mengabaikan anggota tanggal struktur SYSTEMTIME . Ini termasuk: wYear, wMonth, wDayOfWeek, dan wDay.

Jika TIME_NOMINUTESORSECONDS atau TIME_NOSECONDS ditentukan, fungsi akan menghapus pemisah setelah anggota menit dan/atau detik.

Jika TIME_NOTIMEMARKER ditentukan, fungsi akan menghapus pemisah sebelumnya dan mengikuti penanda waktu.

Jika TIME_FORCE24HOURFORMAT ditentukan, fungsi menampilkan penanda waktu yang ada, kecuali bendera TIME_NOTIMEMARKER juga diatur.

Fungsi ini tidak menyertakan milidetik sebagai bagian dari string waktu yang diformat.

Fungsi ini tidak mengembalikan kesalahan untuk string format yang buruk, tetapi hanya membentuk string waktu terbaik. Jika lebih dari dua jam, menit, kedua, atau gambar format penanda waktu diteruskan, fungsi default ke dua. Misalnya, satu-satunya gambar penanda waktu yang valid adalah "t" dan "tt". Jika "ttt" diteruskan, fungsi mengasumsikan "tt".

Untuk mendapatkan format waktu tanpa melakukan pemformatan aktual, aplikasi harus menggunakan fungsi GetLocaleInfoEx , menentukan LOCALE_STIMEFORMAT.

Aplikasi dapat menggunakan elemen berikut untuk membuat string gambar format. Jika spasi digunakan untuk memisahkan elemen dalam string format, spasi ini muncul di lokasi yang sama dalam string output. Huruf harus dalam huruf besar atau huruf kecil seperti yang ditunjukkan, misalnya, "ss", bukan "SS". Karakter dalam string format yang diapit dalam tanda kutip tunggal muncul di lokasi yang sama dan tidak berubah dalam string output.

Gambar	Makna
h	Jam tanpa nol di depan untuk jam satu digit; Jam 12 jam
hh	Jam dengan nol di depan untuk jam satu digit; Jam 12 jam
H	Jam tanpa nol di depan untuk jam satu digit; Jam 24 jam
HH	Jam dengan nol di depan untuk jam satu digit; Jam 24 jam
m	Menit tanpa nol di depan untuk menit satu digit
mm	Menit dengan nol di depan untuk menit satu digit
s	Detik tanpa nol di depan untuk detik satu digit
ss	Detik dengan nol di depan untuk detik satu digit
t	String penanda waktu satu karakter, seperti A atau P
tt	String penanda waktu multi-karakter, seperti AM atau PM

Misalnya, untuk mendapatkan string waktu

"11:29:40 PM"

aplikasi harus menggunakan string gambar

"hh':'mm':'ss tt"

Fungsi ini dapat mengambil data dari lokal kustom. Data tidak dijamin sama dari komputer ke komputer atau antara eksekusi aplikasi. Jika aplikasi Anda harus mempertahankan atau mengirimkan data, lihat Menggunakan Data Lokal Persisten.

Dimulai di Windows 8: Jika aplikasi Anda meneruskan tag bahasa ke fungsi ini dari namespace Windows.Globalization, aplikasi harus terlebih dahulu mengonversi tag dengan memanggil ResolveLocaleName.

Mulai Windows 8: GetTimeFormatEx dideklarasikan dalam Datetimeapi.h. Sebelum Windows 8, itu dinyatakan di Winnls.h.

Persyaratan


Klien minimum yang didukung	Windows Vista [aplikasi desktop \| Aplikasi UWP]
Server minimum yang didukung	Windows Server 2008 [aplikasi desktop \| Aplikasi UWP]
Target Platform	Windows
Header	datetimeapi.h
Pustaka	Kernel32.lib
DLL	Kernel32.dll