{"id":1306,"date":"2011-10-30T21:55:52","date_gmt":"2011-10-30T19:55:52","guid":{"rendered":"https:\/\/alax.info\/blog\/?p=1306"},"modified":"2011-10-30T21:55:52","modified_gmt":"2011-10-30T19:55:52","slug":"common-controls-versions-compatibility-wtl","status":"publish","type":"post","link":"https:\/\/alax.info\/blog\/1306","title":{"rendered":"Common Controls: Versions, Compatibility, WTL"},"content":{"rendered":"

An application appears to be not working in Windows XP in a weird way: rebar control<\/a> appeared to fail showing up.<\/p>\n

\"\"<\/p>\n

Where the application is expected to look much nicer with rebar control as a container for menu (implemented as command bar WTL control) and toolbar with buttons:<\/p>\n

\"\"<\/p>\n

A WTL sample project generated by a Visual Studio wizard would never give such effect, and the bug was a combination of factors:<\/p>\n

    \n
  1. An application built with a newer version of Windows SDK, which includes support for features (Windows Vista+ Common Controls) that are more recent than production environment (Windows XP); the application targets to Windows Vista+ environment too (_WIN32_WINNT<\/em> >= 0x0600<\/em>)<\/li>\n
  2. Compatibility issues of Common Controls library<\/li>\n
  3. WTL version (7.5), which did not yet include a workaround for the problem<\/li>\n<\/ol>\n

    The problem, which caused the bug directly was the REBARBANDINFO structure<\/a> and its use as an argument with Common Controls API. As MSDN shows, the structure was amended twice with additional fields.<\/p>\n

    One of the way to support multiple versions of the structure definition, and to resolve compatibility issues, is to embed structure size into structure payload. In fact, REBARBANDINFO::cbSize<\/em> member is there exactly for this reason.<\/p>\n

    The application is normally filling cbSize<\/em> with the maximal known structure size and fills the rest of the fields respectively. The API is expected to be checking cbSize<\/em> member and be detecting API version compatibility scenarios:<\/p>\n

      \n
    1. cbSize<\/em> holds exactly the value the API expects (that is, the maximal value known\/defined to the API) – the simplest scenario where the API and the application are on the same page, both are using the same versions of the “protocol”\/interface.<\/li>\n
    2. cbSize<\/em> is smaller than API can support – the API sees that it is dealing with a sort of legacy application which cannot utilize all available features, and the API acts respectively supporting the older part of the protocol, and keeping defaults or “old look” for the rest of implementation. This addresses backward compatibility: the newer API works with apps designed for older version of the API<\/li>\n
    3. cbSize<\/em> is greater then API can support – the API sees that the application is already aware of newer version API and is possibly requesting some of the missing features. The API might be ignoring the unsupported part in assumption that API evolution tool place keeping some compatibility in mind, and still do the best it can with the existing implementation. Or, the API might just fail to work.<\/li>\n<\/ol>\n

      The latter item #3 is the scenario here with rebar control. The application is using Windows Vista version of REBARBANDINFO<\/em> structure and Windows XP implementation choses to completely fail.<\/p>\n

      While it does not seem to be directly a bug, this attitude is definitely not developer friendly: there is no reason for the control to not work in its best and default way. Having API acting this way, each developer using the API needs to take care of the situation explicitly: whenever Windows Vista enabled application needs to be able to run in Windows XP system, the code around\u00c2\u00a0REBARBANDINFO<\/em> would look like this:<\/p>\n

      REBARBANDINFO BandInformation =<\/span> {<\/span> sizeof<\/span> BandInformation,<\/span> RBBIM_LPARAM }<\/span>;<\/span>\r\n#<\/span>if<\/span> _WIN32_WINNT <\/span>><\/span>=<\/span> 0x0600<\/span>\r\nif<\/span>(<\/span>GetOsVersion(<\/span>)<\/span> <<\/span> 0x00060000<\/span> |<\/span>|<\/span> GetCommCtrlVersion(<\/span>)<\/span> <<\/span> 0x00060000<\/span>)<\/span> \/\/ pre-Vista, Common Controls pre-6.0<\/span>\r\n    BandInformation.<\/span>cbSize =<\/span> REBARBANDINFO_V6_SIZE;<\/span>\r\n#<\/span>endif<\/span>\/\/ _WIN32_WINNT >= 0x0600<\/span>\r\nconst<\/span> BOOL<\/span> bGetBandInfoResult =<\/span> Rebar.<\/span>GetBandInfo(<\/span>0<\/span>,<\/span> &<\/span>BandInformation)<\/span>;<\/span><\/pre>\n
      If the API was nicer to developers, the code would be plain and simple:<\/p>\n
      REBARBANDINFO BandInformation =<\/span> {<\/span> sizeof<\/span> BandInformation,<\/span> RBBIM_LPARAM }<\/span>;<\/span>\r\nconst<\/span> BOOL<\/span> bGetBandInfoResult =<\/span> Rebar.<\/span>GetBandInfo(<\/span>0<\/span>,<\/span> &<\/span>BandInformation)<\/span>;<\/span><\/pre>\n
      To address this problem, WTL<\/a> 8.0 comes up with RunTimeHelper<\/em> namespace and its SizeOf_REBARBANDINFO<\/em> function. It takes care of details for the developer choosing the proper size of the structure on runtime. The code is being taken back to a simpler shape:<\/p>\n
      REBARBANDINFO BandInformation =<\/span> {<\/span> RunTimeHelper::<\/span>SizeOf_REBARBANDINFO(<\/span>)<\/span>,<\/span> RBBIM_LPARAM }<\/span>;<\/span>\r\nconst<\/span> BOOL<\/span> bGetBandInfoResult =<\/span> Rebar.<\/span>GetBandInfo(<\/span>0<\/span>,<\/span> &<\/span>BandInformation)<\/span>;<\/span><\/pre>\n
      All in all:<\/p>\n