https://devblogs.microsoft.com/oldnewthing/20240216-00/?p=109409 Skip to main content [RE1Mu3b] Microsoft The Old New Thing The Old New Thing The Old New Thing * Home * DevBlogs * Developer + Visual Studio + Visual Studio Code + Visual Studio for Mac + DevOps + Windows Developer + Developer support + ISE Developer + Engineering@Microsoft + Azure SDK + Command Line + Perf and Diagnostics + Math in Office + React Native * Technology + DirectX + PIX + Semantic Kernel + SurfaceDuo + Windows AI Platform * Languages + C++ + C# + F# + TypeScript + PowerShell Community + PowerShell Team + Python + Q# + JavaScript + Java + Java Blog in Chinese * .NET + All .NET posts + .NET MAUI + ASP.NET Core + Blazor + Entity Framework + AI + Machine Learning + Servicing + Xamarin + .NET Blog in Chinese * Platform Development + #ifdef Windows + Azure Government + Azure VM Runtime Team + Bing Dev Center + Microsoft Edge Dev + Microsoft Azure + Microsoft 365 Developer + Microsoft Entra Identity Developer Blog + Old New Thing + Power Platform + Windows MIDI and Music dev * Data Development + Azure Cosmos DB + Azure Data Studio + Azure SQL Database + OData + Revolutions R + SQL Server Data Tools * More [ ] Search Search * No results Cancel If you're just going to sit there doing nothing, at least do nothing correctly [png] Raymond Chen February 16th, 20240 0 There may be times where you need to make an API do nothing. It's important to have it do nothing in the correct way. For example, Windows has an extensive printing infrastructure. But that infrastructure does not exist on Xbox. What should happen if an app tries to print on an Xbox? Well, the wrong thing to do is to have the printing functions throw a NotSupportedException. The app that the user installed on the Xbox was probably tested primarily, if not exclusively, on a PC, where printing is always available. When run on an Xbox, the exception will probably go unhandled, and the app will crash. Even if the app tried to catch the exception, it would probably display a message like "Oops. That went badly. Call support and provide this incident code." A better design for "supporting" printing on Xbox is to have the printing functions succeed, but report that there are no printers installed. With this behavior, when the app tries to print, it will ask the user to select a printer, and show an empty list. The user realizes, "Oh, there are no printers," and cancels the printing request. To deal with apps that get fancy and say "Oh, you have no printers installed, let me help you install one," the function for installing a printer can return immediately with a result code that means "The user cancelled the operation." The idea here is to have the printing functions all behave in a manner perfectly consistent with printing being fully supported, yet mysteriously there is never a printer to print to. Now, you probably also want to add a function to check whether printing even works at all. Apps can use this function to hide the Print button from their UI if they are running on a system that doesn't support printing at all. But naive apps that assume that printing works will still behave in a reasonable manner: You're just on a system that doesn't have any printers and all attempts to install a printer are ineffective. The name we use to describe this "do nothing" behavior is "inert". The API surface still exists and functions according to its specification, but it also does nothing. The important thing is that it does nothing in a way that is consistent with its documentation and is least likely to create problems with existing code. Another example is the retirement of an API that has a variety of functions for creating widget handles, other functions that accept widget handles, and a function for closing widget handles. The team that was doing the retirement originally proposed making the API inert as follows: HRESULT CreateWidget(_Out_ HWIDGET* widget) { *widget = nullptr; return S_OK; } // Every widget is documented to have at least one alias, // so we have to produce one dummy alias (empty string). HRESULT GetWidgetAliases( _Out_writes_to_(capacity, *actual) PWSTR* aliases, UINT capacity, _Out_ UINT* actual) { *actual = 0; RETURN_HR_IF( HRESULT_FROM_WIN32(ERROR_MORE_DATA), capacity < 1); aliases[0] = make_cotaskmem_string_nothrow(L"").release(); RETURN_IF_NULL_ALLOC(aliases[0]); *actual = 1; return S_OK; } // Inert widgets cannot be enabled or disabled. HRESULT EnableWidget(HWIDGET widget, BOOL value) { return E_HANDLE; } HRESULT Close(HWIDGET widget) { RETURN_HR_IF(E_INVALIDARG, widget != nullptr); return S_OK; } I pointed out that having CreateWidget succeed but return a null pointer is going to confuse apps. "The call succeeded, but I didn't get a valid handle back?" I even found some of their own test code that checked whether the handle was null to determine whether the call succeeded, rather than checking the return value. I also pointed out that having EnableWidget return "invalid handle" is also going to create confusion. An app calls CreateWidget, and it succeeds, and it takes that handle (which is presumably valid) and tries to use it to enable a widget, and it's told "That handle isn't valid." How can that be? "I asked for a widget, and you gave me one, and then when I showed it to you, you said, 'That's not a widget.' This API is gaslighting me!" I looked through the existing documentation for their API and found that a documented return value is ERROR_CANCELLED to mean that the user cancelled the creation of the widget. Therefore, apps are already dealing with the possibility of widgets not being created due to conditions outside their control, so we can take advantage of that: Any time the app tries to create a widget, just say "Nope, the, uh, user cancelled, yeah, that's what happened." HRESULT CreateWidget(_Out_ HWIDGET* widget) { *widget = nullptr; return HRESULT_FROM_WIN32(ERROR_CANCELLED); } HRESULT GetWidgetAliases( _Out_writes_to_(capacity, *actual) PWSTR* aliases, UINT capacity, _Out_ UINT* actual) { *actual = 0; return E_HANDLE; } HRESULT EnableWidget(HWIDGET widget, BOOL value) { return E_HANDLE; } HRESULT Close(HWIDGET widget) { return E_HANDLE; } Now we have a proper inert API surface. If you try to create a widget, we tell you that we couldn't because the user cancelled. Since all attempts to create a widget fail, there is no such thing as a valid widget handle, and any time you try to use one, we tell you that the handle is invalid. This also avoids the problem of having to produce dummy aliases for widgets. Since there are no widgets, there is no legitimate case where an app could ask a widget for its aliases. Bonus chatter: To clear up some confusion: The idea here is that the printing API has always existed on desktop, where printing is supported, and the "get me the list of printers" function is documented not to throw an exception. If you want to port the printing API to Xbox, how do you do it in a way that allows existing desktop apps to continue to run on Xbox? The inert behavior is completely truthful: There are no printers on an Xbox. Nobody expects the answer to the question, "How many printers are there?" to be "How dare you ask me such a thing!" Another scenario where you need to create an inert API surface is if you want to retire an existing API. How do you make the behavior of the API consistent with its contract while still doing nothing useful? [png] Raymond Chen Follow Tagged Code Read next Registered command lines are just command lines, not a programming language If you want a programming language, you know where to find one. [png]Raymond Chen February 15, 2024 3 comments Functions that return the size of a required buffer generally return upper bounds, not tight bounds An over-estimate is better than an under-estimate. [png]Raymond Chen February 14, 2024 6 comments 0 comments Leave a commentCancel reply Log in to join the discussion. Archive * February 2024 * January 2024 * December 2023 * November 2023 * October 2023 * September 2023 * August 2023 * July 2023 * June 2023 * May 2023 * April 2023 * March 2023 * February 2023 * January 2023 * December 2022 * November 2022 * October 2022 * September 2022 * August 2022 * July 2022 * June 2022 * May 2022 * April 2022 * March 2022 * February 2022 * January 2022 * December 2021 * November 2021 * October 2021 * September 2021 * August 2021 * July 2021 * June 2021 * May 2021 * April 2021 * March 2021 * February 2021 * January 2021 * December 2020 * November 2020 * October 2020 * September 2020 * August 2020 * July 2020 * June 2020 * May 2020 * April 2020 * March 2020 * February 2020 * January 2020 * December 2019 * November 2019 * October 2019 * September 2019 * August 2019 * July 2019 * June 2019 * May 2019 * April 2019 * March 2019 * February 2019 * January 2019 * December 2018 * November 2018 * October 2018 * September 2018 * August 2018 * July 2018 * June 2018 * May 2018 * April 2018 * March 2018 * February 2018 * January 2018 * December 2017 * November 2017 * October 2017 * September 2017 * August 2017 * July 2017 * June 2017 * May 2017 * April 2017 * March 2017 * February 2017 * January 2017 * December 2016 * November 2016 * October 2016 * September 2016 * August 2016 * July 2016 * June 2016 * May 2016 * April 2016 * March 2016 * February 2016 * January 2016 * December 2015 * November 2015 * October 2015 * September 2015 * August 2015 * July 2015 * June 2015 * May 2015 * April 2015 * March 2015 * February 2015 * January 2015 * December 2014 * November 2014 * October 2014 * September 2014 * August 2014 * July 2014 * June 2014 * May 2014 * April 2014 * March 2014 * February 2014 * January 2014 * December 2013 * November 2013 * October 2013 * September 2013 * August 2013 * July 2013 * June 2013 * May 2013 * April 2013 * March 2013 * February 2013 * January 2013 * December 2012 * November 2012 * October 2012 * September 2012 * August 2012 * July 2012 * June 2012 * May 2012 * April 2012 * March 2012 * February 2012 * January 2012 * December 2011 * November 2011 * October 2011 * September 2011 * August 2011 * July 2011 * June 2011 * May 2011 * April 2011 * March 2011 * February 2011 * January 2011 * December 2010 * November 2010 * October 2010 * September 2010 * August 2010 * July 2010 * June 2010 * May 2010 * April 2010 * March 2010 * February 2010 * January 2010 * December 2009 * November 2009 * October 2009 * September 2009 * August 2009 * July 2009 * June 2009 * May 2009 * April 2009 * March 2009 * February 2009 * January 2009 * December 2008 * November 2008 * October 2008 * September 2008 * August 2008 * July 2008 * June 2008 * May 2008 * April 2008 * March 2008 * February 2008 * January 2008 * December 2007 * November 2007 * October 2007 * September 2007 * August 2007 * July 2007 * June 2007 * May 2007 * April 2007 * March 2007 * February 2007 * January 2007 * December 2006 * November 2006 * October 2006 * September 2006 * August 2006 * July 2006 * June 2006 * May 2006 * April 2006 * March 2006 * February 2006 * January 2006 * December 2005 * November 2005 * October 2005 * September 2005 * August 2005 * July 2005 * June 2005 * May 2005 * April 2005 * March 2005 * February 2005 * January 2005 * December 2004 * November 2004 * October 2004 * September 2004 * August 2004 * July 2004 * June 2004 * May 2004 * April 2004 * March 2004 * February 2004 * January 2004 * December 2003 * November 2003 * October 2003 * September 2003 * August 2003 * July 2003 Relevant Links I wrote a book Ground rules Disclaimers and such My necktie's Twitter Categories Code History Tips/Support Other Non-Computer Stay informed [ ] [Subscribe] By subscribing you agree to our Terms of Use and Privacy Policy Share on Social media * * * Login Theme * light-theme-iconLight * dark-theme-iconDark Insert/edit link Close Enter the destination URL URL [ ] Link Text [ ] [ ] Open link in a new tab Or link to existing content Search [ ] No search term specified. Showing recent items. Search or use up and down arrow keys to select an item. Cancel [Add Link] Code Block x Paste your code snippet [ ] Cancel Ok Feedback usabilla icon What's new * Surface Laptop Studio 2 * Surface Laptop Go 3 * Surface Pro 9 * Surface Laptop 5 * Surface Studio 2+ * Copilot in Windows * Microsoft 365 * Windows 11 apps Microsoft Store * Account profile * Download Center * Microsoft Store support * Returns * Order tracking * Certified Refurbished * Microsoft Store Promise * Flexible Payments Education * Microsoft in education * Devices for education * Microsoft Teams for Education * Microsoft 365 Education * How to buy for your school * Educator training and development * Deals for students and parents * Azure for students Business * Microsoft Cloud * Microsoft Security * Dynamics 365 * Microsoft 365 * Microsoft Power Platform * Microsoft Teams * Microsoft Industry * Small Business Developer & IT * Azure * Developer Center * Documentation * Microsoft Learn * Microsoft Tech Community * Azure Marketplace * AppSource * Visual Studio Company * Careers * About Microsoft * Company news * Privacy at Microsoft * Investors * Diversity and inclusion * Accessibility * Sustainability Your Privacy Choices Your Privacy Choices * Sitemap * Contact Microsoft * Privacy * Manage cookies * Terms of use * Trademarks * Safety & eco * Recycling * About our ads * (c) Microsoft 2024