Fungsi GetDurationFormatEx (winnls.h)

Artikel
06/01/2023

Memformat durasi waktu sebagai string waktu untuk lokal yang ditentukan oleh nama.

Catatan Aplikasi harus memanggil fungsi ini sebagai preferensi ke GetDurationFormat jika dirancang untuk berjalan hanya pada Windows Vista dan yang lebih baru.

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

Sintaks

int GetDurationFormatEx(
  [in, optional]  LPCWSTR          lpLocaleName,
  [in]            DWORD            dwFlags,
  [in, optional]  const SYSTEMTIME *lpDuration,
  [in]            ULONGLONG        ullDuration,
  [in, optional]  LPCWSTR          lpFormat,
  [out, optional] LPWSTR           lpDurationStr,
  [in]            int              cchDuration
);

Parameter

[in, optional] lpLocaleName

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

[in] dwFlags

Bendera yang menentukan opsi fungsi. Jika lpFormat tidak diatur ke NULL, parameter ini harus diatur ke 0. Jika lpFormat diatur ke NULL, aplikasi Anda dapat menentukan LOCALE_NOUSEROVERRIDE untuk memformat string menggunakan format durasi default sistem untuk lokal yang ditentukan.

Hati Penggunaan LOCALE_NOUSEROVERRIDE sangat tidak disarankan karena menonaktifkan preferensi pengguna.

[in, optional] lpDuration

Penunjuk ke struktur SYSTEMTIME yang berisi informasi durasi waktu untuk diformat. Aplikasi mengatur parameter ini ke NULL jika fungsinya adalah mengabaikannya dan menggunakan ullDuration.

[in] ullDuration

Bilangan bulat tidak bertanda 64-bit yang menunjukkan jumlah interval 100 nanodetik dalam durasi. Jika lpDuration dan ullDuration diatur, parameter lpDuration lebih diutamakan. Jika lpDuration diatur ke NULL dan ullDuration diatur ke 0, durasinya adalah 0.

[in, optional] lpFormat

Arahkan ke string format dengan karakter seperti yang ditunjukkan di bawah ini. Aplikasi dapat mengatur parameter ini ke NULL jika fungsinya adalah memformat string sesuai dengan format durasi untuk lokal yang ditentukan. Jika lpFormat tidak diatur ke NULL, fungsi menggunakan lokal hanya untuk informasi yang tidak ditentukan dalam format string gambar.

Nilai	Makna
-d	hari
h atau H	jam
hh atau HH	Jam; jika kurang dari sepuluh, tambahkan awalan nol di depannya
m	menit
mm	Menit; jika kurang dari sepuluh, tambahkan awalan nol di depannya
s	detik
ss	Detik; jika kurang dari sepuluh, tambahkan awalan nol di depannya
f	pecahan detik Catatan Karakter "f" dapat terjadi hingga sembilan kali berturut-turut (fffffffff), meskipun dukungan untuk timer frekuensi dibatasi hingga 100 nanodetik. Dengan demikian, jika ada sembilan karakter, dua digit terakhir selalu 0.

[out, optional] lpDurationStr

Arahkan ke buffer tempat fungsi mengambil string durasi.

Atau, parameter ini mengambil NULL jika cchDuration diatur ke 0. Dalam hal ini, fungsi mengembalikan ukuran yang diperlukan untuk buffer string durasi.

[in] cchDuration

Ukuran, dalam karakter, dari buffer yang ditunjukkan oleh lpDurationStr.

Atau, aplikasi dapat mengatur parameter ini ke 0. Dalam hal ini, fungsi mengambil NULL di lpDurationStr dan mengembalikan ukuran yang diperlukan untuk buffer string durasi.

Nilai kembali

Mengembalikan jumlah karakter yang diambil dalam buffer yang ditunjukkan oleh lpDurationStr jika berhasil. Jika lpDurationStr diatur ke NULL dan cchDuration diatur ke 0, fungsi mengembalikan ukuran yang diperlukan untuk buffer string durasi, termasuk karakter null yang mengakhiri. Misalnya, jika 10 karakter ditulis ke buffer, fungsi mengembalikan 11 untuk menyertakan karakter null yang mengakhiri.

Fungsi 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_PARAMETER. Salah satu nilai parameter tidak valid.

Keterangan

Fungsi ini dapat digunakan dengan aplikasi multimedia yang menampilkan waktu file dan aplikasi acara olahraga yang menampilkan waktu selesai.

Fungsi ini mengabaikan tiga anggota pertama dari struktur SYSTEMTIME : wYear, wMonth, dan wDayOfWeek.

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.

Berikut ini adalah karakteristik string format durasi:

Karakter pemformatan adalah huruf kecil.
Catatan Pengecualian dibuat agar (H) konsisten dengan GetTimeFormatEx.
String format dua digit untuk jam, menit, dan detik menambahkan nol di depannya jika nilainya kurang dari 10.
Bidang output pertama tidak tunduk pada pengujian batas apa pun (jam<24, menit<60, detik<60, milidetik<1000). Hari tidak tunduk pada pengujian terikat.
Fungsi ini mengasumsikan bahwa semua string format berada dalam ukuran bidang yang menurun, misalnya, jam, menit, detik, milidetik.
Bidang pertama yang akan ditampilkan dinormalisasi, seperti yang didefinisikan oleh string format. Misalnya, jika aplikasi menentukan 310 detik dan string formatnya adalah m:ss, outputnya adalah 5:10. Namun, jika string format menentukan menit dan detik tetapi aplikasi menentukan jam, bidang menit disesuaikan sesuai.
Jika pecahan bukan bidang pertama, jumlah karakter "f" dalam string format menunjukkan jumlah desimal yang akan ditampilkan (batas 9). Jika pecahan adalah bidang pertama, jumlah karakter "f" menunjukkan jumlah digit signifikan di bawah satu detik.
Round-off terjadi dengan pemotongan, bukan dengan aturan lima membulatkan ke atas dan empat membulatkan ke bawah.
Tanda kutip tunggal digunakan untuk karakter escape.

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.

Contoh

Berikut ini adalah contoh format durasi dan output yang sesuai untuk durasi waktu yang ditentukan.

SYSTEMTIME = 14 hari, 2 jam, 45 menit, 12 detik, dan 247 milidetik

Format	Output
d:hh:mm:ss	14:02:45:12
hh:mm:ss:ff	338:45:12:24
hh:mm:ss:fff	338:45:12:247
h' h 'mm' m 'ss' s'	338 h 45 m 12 dtk

SYSTEMTIME = 345 detik

Format	Output
hh:mm:ss	00:05:45
h:mm:ss	0:05:45
mm:ss	05:45
m:ss	5:45
mm' m 'ss' s'	05 m 45 dtk
ss	345
detik ss'	345 detik

uulDuration = 51234567 (5,1234567 detik)

Format	Output
s.fff	5.123
s.ffffff	5.123456
s.fffffffff	5.123456700 (tambahkan nol berikutnya)
fff 'ms'	5123 mdtk
ffffff 'microseconds'	5123456 mikrostik
fffffffff 'ns'	5123456700 ns

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	winnls.h (termasuk Windows.h)
Pustaka	Kernel32.lib
DLL	Kernel32.dll