{"id":105255,"date":"2021-05-27T07:00:00","date_gmt":"2021-05-27T14:00:00","guid":{"rendered":"https:\/\/devblogs.microsoft.com\/oldnewthing\/?p=105255"},"modified":"2021-05-28T10:06:54","modified_gmt":"2021-05-28T17:06:54","slug":"20210527-00","status":"publish","type":"post","link":"https:\/\/devblogs.microsoft.com\/oldnewthing\/20210527-00\/?p=105255","title":{"rendered":"How can I convert between IANA time zones and Windows registry-based time zones?"},"content":{"rendered":"

A customer wanted to be able to convert from IANA time zones and Windows registry-based time zones. Is there a function for doing that?<\/p>\n

Yes, but it’s not somewhere you might think to look.<\/p>\n

The Windows globalization team emphasizes that what you should not<\/i> do is take the information from CLDR<\/a>, use it to produce a translation table, and hard-code that table into your application. Time zones are notoriously fickle, and there’s a team of people inside Microsoft whose full-time job is to keep track of time zone changes worldwide<\/a>.<\/p>\n

What you need to do is delegate the work of updating time zone information to somebody else.<\/p>\n

One such somebody else<\/i> is ICU, the International Components for Unicode<\/a>.<\/p>\n

A copy of ICU has been included with Windows since Windows 10 Version 1703 (build 15063). All you have to do is include icu.h<\/code>, and you’re off to the races. An advantage of using the version that comes with Windows is that it is actively maintained and updated by the Windows team. If you need to run on older systems, you can build your own copy from their fork of the ICU repo<\/a>, but the job of servicing the project is now on you.<\/p>\n

Here’s a proof-of-concept program that shows how to convert between IANA time zones and Windows time zones.<\/p>\n

#include <windows.h>\r\n#define UCHAR_TYPE wchar_t\r\n#include <icu.h>\r\n\r\nint wmain(int argc, wchar_t** argv)\r\n{\r\n    wchar_t buffer[128];\r\n    UErrorCode status = U_ZERO_ERROR;\r\n    if (argc == 2) {\r\n        auto result = ucal_getWindowsTimeZoneID(\r\n            argv[1], -1, buffer, ARRAYSIZE(buffer), &status);\r\n        if (U_SUCCESS(status)) {\r\n            printf(\"result = %d, IANA %ls -> Windows %ls\\n\",\r\n                   result, argv[1], buffer);\r\n        }\r\n    } else if (argc == 3) {\r\n        char region[64];\r\n        if (WideCharToMultiByte(CP_UTF8, 0, argv[2], -1,\r\n                                region, 64, 0, nullptr)) {\r\n            auto result = ucal_getTimeZoneIDForWindowsID(\r\n                argv[1], -1, region, buffer, ARRAYSIZE(buffer), &status);\r\n            if (U_SUCCESS(status)) {\r\n                printf(\"result = %d, Windows %ls:%s -> IANA %ls\\n\",\r\n                       result, argv[1], region, buffer);\r\n            }\r\n        }\r\n    }\r\n    return 0;\r\n}\r\n<\/pre>\n
By default, the icu.h<\/code> header uses char16_t<\/code> to represent UTF-16 code units. Windows, however, uses wchar_t<\/code>, so we define UCHAR_TYPE<\/code> to get the type we want.<\/p>\n
If you run the program with a single command line parameter, then we treat it as an IANA time zone and ask ucal_get\u00adWindows\u00adTime\u00adZone\u00adID<\/code> to convert it to a Windows time zone.<\/p>\n
C:\\> scratch America\/Vancouver\r\nresult = 21, IANA America\/Vancouver -> Windows Pacific Standard Time\r\n<\/pre>\n
If you run it with two command line parameters, then we treat the first as the Windows time zone and the second as the region, and convert the pair to an IANA time zone.<\/p>\n
C:\\> scratch \"Pacific Standard Time\" US\r\nresult = 19, Windows Pacific Standard Time:US -> IANA America\/Los_Angeles\r\n\r\nC:\\> scratch \"Pacific Standard Time\" CA\r\nresult = 17, Windows Pacific Standard Time:CA -> IANA America\/Vancouver\r\n<\/pre>\n
To resolve these calls to the system-provided ICU.DLL<\/code>, link either with icu.lib<\/code> or with the umbrella library windowsapp.lib<\/code>.<\/p>\n
Bonus chatter<\/b>: The Windows globalization team also strongly recommends that programs use IANA time zones and use the Windows registry-based time zones only for legacy interop purposes.<\/p>\n
Important bonus chatter<\/b>: Even though support arrived in Windows 10 Version 1703 (build 15063), using ICU prior to Windows 10 Version 1903 (build 18362) is a little trickier. When it was introduced, the ICU library was added as two system DLLs:<\/p>\n\n\n\n\n\n
Feature<\/th>\nHeader file<\/th>\nLibrary<\/th>\nDLL<\/th>\n<\/tr>\n
Common<\/td>\nicucommon.h<\/code><\/td>\nicuuc.lib<\/code><\/td>\nicuuc.dll<\/code><\/td>\n<\/tr>\n
Internationalization<\/td>\nicui18n.h<\/code><\/td>\nicuin.lib<\/code><\/td>\nicuin.dll<\/code><\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n
In Windows 10 Version 1709, the two header files were combined into a single icu.h<\/code> header file.<\/p>\n\n\n\n\n\n
Feature<\/th>\nHeader file<\/th>\nLibrary<\/th>\nDLL<\/th>\n<\/tr>\n
Common<\/td>\nicu.h<\/code><\/td>\nicuuc.lib<\/code><\/td>\nicuuc.dll<\/code><\/td>\n<\/tr>\n
Internationalization<\/td>\nicuin.lib<\/code><\/td>\nicuin.dll<\/code><\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n
The separate header files still remain for source code backward compatibility, but no new features will be added to the separate header files.<\/p>\n
And in Windows 10 Version 1903, the separate LIBs and DLLs were also combined:<\/p>\n\n\n\n\n\n
Feature<\/th>\nHeader file<\/th>\nLibrary<\/th>\nDLL<\/th>\n<\/tr>\n
Common<\/td>\nicu.h<\/code><\/td>\nicu.lib<\/code><\/td>\nicu.dll<\/code><\/td>\n<\/tr>\n
Internationalization<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n
Again, the old LIBs and DLLs remain for backward compatibility. (The old DLLs are now forwarders to the combined icu.dll<\/code>.)<\/p>\n
This change was triggered by a breaking change in the underlying ICU library that moved one of the functions from Common to Internationalization. Since the ICU team had to do some architectural work to accommodate the breaking change, they took the time to do some other tidying.<\/p>\n
Combining two DLLs into one DLL allowed for a reduction in the overall footprint of ICU. They also removed the requirement that you call Co\u00adInitialize\u00adEx<\/code> before calling any ICU functions. (In earlier versions, if you failed to call Co\u00adInitialize\u00adEx<\/code>, then the default ICU locale is always en_US<\/tt> and the default time zone is always Etc\/UTC<\/tt>.)<\/p>\n
TL;DR: If you want to support versions prior to Windows 10 Version 1903, you should load the appropriate separately-named DLL and make sure to call Co\u00adInitialize\u00adEx<\/code>.<\/p>\n
To be sure you’re getting the one that doesn’t require COM to be initialized, go straight to icu.dll<\/code>. (That’s  what .NET Core does<\/a>.)<\/p>\n","protected":false},"excerpt":{"rendered":"
ICU to the rescue.<\/p>\n","protected":false},"author":1069,"featured_media":111744,"comment_status":"open","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"_acf_changed":false,"footnotes":""},"categories":[1],"tags":[25],"class_list":["post-105255","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-oldnewthing","tag-code"],"acf":[],"blog_post_summary":"
ICU to the rescue.<\/p>\n","_links":{"self":[{"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/posts\/105255","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/users\/1069"}],"replies":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/comments?post=105255"}],"version-history":[{"count":0,"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/posts\/105255\/revisions"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/media\/111744"}],"wp:attachment":[{"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/media?parent=105255"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/categories?post=105255"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/tags?post=105255"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}