From e2cad12b0311628b8acab8086af97abda8871ec8 Mon Sep 17 00:00:00 2001 From: Raghav Goyal Date: Mon, 4 Aug 2025 12:29:47 -0700 Subject: [PATCH 1/2] Add DST ambiguity note to TzSpecificLocalTimeToSystemTime documentation MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit This PR updates the Remarks section of the TzSpecificLocalTimeToSystemTime API documentation to clarify behavior around Daylight Saving Time (DST) transitions. Specifically, it adds a note explaining that: Certain local times near DST transitions may be ambiguous (e.g., repeated during fall back) or invalid (e.g., skipped during spring forward). The API may not return the "correct" UTC value in these cases due to the lack of a DST indicator in the SYSTEMTIME structure. Developers should be aware of this limitation and consider alternative approaches for time-sensitive operations. This clarification is based on internal bug reports and developer feedback, and aims to prevent confusion and misinterpretation of API behavior during DST transitions. ✅ Motivation: Improve developer understanding of edge cases in time conversion. Reduce misuses and incorrect assumptions about API behavior near DST boundaries. Align documentation with observed behavior and internal guidance. --- .../nf-timezoneapi-tzspecificlocaltimetosystemtime.md | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/sdk-api-src/content/timezoneapi/nf-timezoneapi-tzspecificlocaltimetosystemtime.md b/sdk-api-src/content/timezoneapi/nf-timezoneapi-tzspecificlocaltimetosystemtime.md index 0d4997f35154..664e0782310c 100644 --- a/sdk-api-src/content/timezoneapi/nf-timezoneapi-tzspecificlocaltimetosystemtime.md +++ b/sdk-api-src/content/timezoneapi/nf-timezoneapi-tzspecificlocaltimetosystemtime.md @@ -88,6 +88,13 @@ If the function fails, the return value is zero. To get extended error informati TzSpecificLocalTimeToSystemTime takes into account whether daylight saving time (DST) is in effect for the local time to be converted. +> [!IMPORTANT] +> Certain local times near DST transitions may be ambiguous or invalid. Specifying such a time can result in unexpected behavior as there is no guaranteed "correct" result. +> - During the transition from daylight time to standard time, the local clock repeats. A local time within the repeated window is ambiguous because it occurs twice, once in daylight time and once in standard time. +> - During the transition from standard time to daylight time, the local clock jumps forward. A local time within the skipped window does not have a valid UTC conversion. +> +> Applications requiring continuity or precision should avoid relying on this function and look to use UTC time directly instead. + ## -see-also GetSystemTime @@ -114,4 +121,4 @@ If the function fails, the return value is zero. To get extended error informati -Time Functions \ No newline at end of file +Time Functions From 98eb1ed6f36c006d91b0cb96c18ea9b49e6a9481 Mon Sep 17 00:00:00 2001 From: Raghav Goyal Date: Mon, 4 Aug 2025 13:04:39 -0700 Subject: [PATCH 2/2] Update TzSpecificLocalTimeToSystemTimeEx to add same updated remarks as the non-Ex version --- ...timezoneapi-tzspecificlocaltimetosystemtimeex.md | 13 ++++++++++++- 1 file changed, 12 insertions(+), 1 deletion(-) diff --git a/sdk-api-src/content/timezoneapi/nf-timezoneapi-tzspecificlocaltimetosystemtimeex.md b/sdk-api-src/content/timezoneapi/nf-timezoneapi-tzspecificlocaltimetosystemtimeex.md index 7f4a7120b2ad..3c6750ee9a03 100644 --- a/sdk-api-src/content/timezoneapi/nf-timezoneapi-tzspecificlocaltimetosystemtimeex.md +++ b/sdk-api-src/content/timezoneapi/nf-timezoneapi-tzspecificlocaltimetosystemtimeex.md @@ -74,4 +74,15 @@ A pointer to a ## -returns If the function fails, the return value is zero. To get extended error information, call -GetLastError. \ No newline at end of file +GetLastError. + +## -remarks + +TzSpecificLocalTimeToSystemTimeEx takes into account whether daylight saving time (DST) is in effect for the local time to be converted. + +> [!IMPORTANT] +> Certain local times near DST transitions may be ambiguous or invalid. Specifying such a time can result in unexpected behavior as there is no guaranteed "correct" result. +> - During the transition from daylight time to standard time, the local clock repeats. A local time within the repeated window is ambiguous because it occurs twice, once in daylight time and once in standard time. +> - During the transition from standard time to daylight time, the local clock jumps forward. A local time within the skipped window does not have a valid UTC conversion. +> +> Applications requiring continuity or precision should avoid relying on this function and look to use UTC time directly instead.