Fungsi GetDurationFormatEx (winnls.h)
Memformat durasi waktu sebagai string waktu untuk lokal yang ditentukan oleh nama.
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.
[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.
[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.
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 |