GetDurationFormatEx 関数 (winnls.h)
時間の期間を、名前で指定されたロケールの時刻文字列として書式設定します。
構文
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
);
パラメーター
[in, optional] lpLocaleName
ロケール名へのポインター、または次の定義済みの値のいずれか。
[in] dwFlags
関数オプションを指定するフラグ。 lpFormat が NULL に設定されていない場合、このパラメーターは 0 に設定する必要があります。 lpFormat が NULL に設定されている場合、アプリケーションでは、指定したロケールのシステムの既定の期間形式を使用して文字列を書式設定するLOCALE_NOUSEROVERRIDEを指定できます。
[in, optional] lpDuration
書式設定する期間情報を含む SYSTEMTIME 構造体へのポインター。 アプリケーションは、このパラメーターを無視して ullDuration を使用する場合に、このパラメーターを NULL に設定します。
[in] ullDuration
期間の 100 ナノ秒間隔の数を表す 64 ビット符号なし整数。 lpDuration と ullDuration の両方が設定されている場合は、lpDuration パラメーターが優先されます。 lpDuration が NULL に設定され、ullDuration が 0 に設定されている場合、期間は 0 になります。
[in, optional] lpFormat
次に示すように、文字を含む書式指定文字列へのポインター。 関数が指定したロケールの期間形式に従って文字列を書式設定する場合、アプリケーションはこのパラメーターを NULL に設定できます。 lpFormat が NULL に設定されていない場合、関数は書式指定図文字列で指定されていない情報に対してのみロケールを使用します。
[out, optional] lpDurationStr
関数が期間文字列を取得するバッファーへのポインター。
または、cchDuration が 0 に設定されている場合、このパラメーターは NULL を取得します。 この場合、関数は期間文字列バッファーに必要なサイズを返します。
[in] cchDuration
lpDurationStr で示されるバッファーのサイズ (文字単位)。
または、アプリケーションでこのパラメーターを 0 に設定することもできます。 この場合、この関数は lpDurationStr で NULL を取得し、期間文字列バッファーに必要なサイズを返します。
戻り値
成功した場合に lpDurationStr によって示されるバッファー内で取得された文字数を返します。 lpDurationStr が NULL に設定され、cchDuration が 0 に設定されている場合、この関数は期間文字列バッファーに必要なサイズ (終端の null 文字を含む) を返します。 たとえば、バッファーに 10 文字が書き込まれる場合、関数は 11 を返して終端の null 文字を含めます。
成功しなかった場合、関数は 0 を返します。 拡張エラー情報を取得するために、アプリケーションは GetLastError を呼び出すことができます。これにより、次のいずれかのエラー コードが返されます。
- ERROR_INSUFFICIENT_BUFFER。 指定されたバッファー サイズが十分に大きくなかったか、 正しく NULL に設定されていませんでした。
- ERROR_INVALID_PARAMETER。 パラメーター値のいずれかが無効です。
解説
この関数は、ファイル時刻を表示するマルチメディア アプリケーションと、終了時刻を表示するスポーツ イベント アプリケーションで使用できます。
この関数は、 SYSTEMTIME 構造体の最初の 3 つのメンバー (wYear、 wMonth、 wDayOfWeek) を無視します。
この関数は、 カスタム ロケールからデータを取得できます。 データは、コンピューター間、またはアプリケーションの実行間で同じになることは保証されません。 アプリケーションでデータを永続化または送信する必要がある場合は、「 永続的なロケール データの使用」を参照してください。
期間書式指定文字列の特性を次に示します。
-
書式設定文字は小文字です。
メモ (H) が GetTimeFormatEx と一致するように例外が発生します。
- 時間、分、秒の 2 桁の書式指定文字列は、値が 10 未満の場合に先頭に 0 を付けます。
- 最初の出力フィールドは、境界テストの対象になりません (時間<24、分<60、秒<60、ミリ秒<1000)。 日数は境界テストの対象になりません。
- 関数は、すべての書式指定文字列が、時間、分、秒、ミリ秒などのフィールド サイズを小さくすることを前提としています。
- 表示される最初のフィールドは、書式指定文字列で定義されているように正規化されます。 たとえば、アプリケーションで 310 秒を指定し、書式指定文字列が m:ss の場合、出力は 5:10 になります。 ただし、書式指定文字列で分と秒を指定し、アプリケーションで時間が指定されている場合は、minutes フィールドはそれに応じて調整されます。
- 分数が最初のフィールドでない場合、書式指定文字列の "f" 文字の数は、表示する小数点以下の桁数 (9 の制限) を示します。 分数が最初のフィールドの場合、"f" 文字の数は 1 秒未満の有効桁数を示します。
- 切り捨ては切り捨てによって行われ、5 回切り上げと 4 回切り下げのルールではありません。
- 文字をエスケープするには、単一引用符を使用します。
使用例
指定した期間の期間形式と対応する出力の例を次に示します。
SYSTEMTIME = 14 日、2 時間、45 分、12 秒、247 ミリ秒
| フォーマット | 出力 |
|---|---|
| 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 s |
SYSTEMTIME = 345 秒
| フォーマット | 出力 |
|---|---|
| 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 s |
| ss | 345 |
| ss'seconds' | 345 秒 |
uulDuration = 51234567 (5.1234567 秒)
| フォーマット | 出力 |
|---|---|
| s.fff | 5.123 |
| s.ffffff | 5.123456 |
| s.fffffffffff | 5.123456700 (末尾にゼロを追加) |
| fff 'ms' | 5123 ミリ秒 |
| ffffff 'microseconds' | 5123456 マイクロ秒 |
| fffffffff 'ns' | 5123456700 ns |
要件
| サポートされている最小のクライアント | Windows Vista [デスクトップ アプリ |UWP アプリ] |
| サポートされている最小のサーバー | Windows Server 2008 [デスクトップ アプリ |UWP アプリ] |
| 対象プラットフォーム | Windows |
| ヘッダー | winnls.h (Windows.h を含む) |
| Library | Kernel32.lib |
| [DLL] | Kernel32.dll |