Yesterday, I took a look at the varying perspectives taken with regards to the Zune 30 debacle. Today, I’ll take a look at what exactly led the Zune 30s to freeze. If you’d like to see the code for the entire driver, click here.

Below the fold lies a sufficiently sized code sample with everything you’ll need to understand what happened with the Zune 30 bug.

Relevant code is non-gray code:

#define ORIGINYEAR 1980 
BOOL ConvertDays(UINT32 days, SYSTEMTIME* lpTime)
{
    int dayofweek, month, year;
    UINT8 *month_tab;

    //Calculate current day of the week
    dayofweek = GetDayOfWeek(days);

    year = ORIGINYEAR;

    while (days > 365)
    {
        if (IsLeapYear(year))
        {
            if (days > 366)
            {
                days -= 366;
                year += 1;
            }
        }
        else
        {
            days -= 365;
            year += 1;
        }
    }

    // Determine whether it is a leap year
    month_tab = (UINT8 *)((IsLeapYear(year))? monthtable_leap : monthtable);

    for (month=0; month<12; month++)
    {
        if (days <= month_tab[month])
            break;
        days -= month_tab[month];
    }

    month += 1;

    lpTime->wDay = days;
    lpTime->wDayOfWeek = dayofweek;
    lpTime->wMonth = month;
    lpTime->wYear = year;

    return TRUE;
}

So what’s the purpose of the while loop? To put it simply, it’s designed to get the number of years from the number of days since 1980 as well as a remainder of days out of the current year. Well, let’s look at how the code plays out in my confusingly simple While Loop in Plain English™. Keep in mind that you’re never supposed to retry the loop without committing some sort of action which will ultimately exit the loop:

1. year is set to ORIGINYEAR. Since ORIGINYEAR is 1980, any addition to year is added on top of 1980. This is fine because the hardware is passing the number of days since January 1, 1980.
2. Is the number of days greater than 365? If so, proceed. Otherwise, skip to number 6.
3. Is the current year a leap year? If so, proceed. Otherwise, subtract 365 from the number of days, add 1 to the number of years, and skip to number 5.
4. Is the number of days greater than 366? If so, subtract 366 from the number of days, add 1 to the number of years, and proceed.
5. retry number 2.
6. …
7. Profit?

The problem lies in the fact that there is one case which can never escape the loop. If it’s a leap year, the number 366 will stay within the loop forever because 366 will never be greater than 366, but 366 will also always be greater than 365. 366 days will pass through, in our Plain English While Loop, without having any action committed upon it.

There’s a very quick solution to this: Since 366 is a valid remainder of days in a leap year (December 31 is the 366th day in a leap year), 366 can technically exit the loop without any problems. All we need to do is add a way to exit the loop when the number of days is 366. Let’s see how things go with this new breakpoint:

1. year is set to ORIGINYEAR. Since ORIGINYEAR is 1980, any addition to year is added on top of 1980. This is fine because the hardware is passing the number of days since January 1, 1980.
2. Is the number of days greater than 365? If so, proceed. Otherwise, skip to number 6.
3. Is the current year a leap year? If so, proceed. Otherwise, subtract 365 from the number of days, add 1 to the number of years, and skip to number 5.
4. Is the number of days greater than 366? If so, subtract 366 from the number of days, add 1 to the number of years, and proceed. Otherwise, skip to number 6.
5. retry number 2.
6. …
7. Profit!

Thanks to the break (represented by “Otherwise, skip to number 6”), 366 days can escape the loop properly. This would lead to the end result for December 31, 2008 being years == 2008 and days == 366.

This is what the break would look in the while loop:

    while (days > 365)
    {
        if (IsLeapYear(year))
        {
            if (days > 366)
            {
                days -= 366;
                year += 1;
            }
            else
            {
                break;
            }
        }
        else
        {
            days -= 365;
            year += 1;
        }
    }

Clarifying one quick thing: A number of people on outlets such as Digg suggested that changing “if (days > 366)” to “if (days >= 366)”:

The problem with doing this is that the end result, upon hitting “if (days >= 366)” with the value 366, one would end up with the year going up by one and the operation “366 –= 366” playing out. End result: December 31 of the leap year is suddenly January 0 of the following year.

Extra credit: This loop can be fixed such that the loop’s condition is based on the year’s status as a leap year. The change needed is simple:

    while (days > (IsLeapYear(year) ? 366 : 365))
    //The above line basically says “Is it a leap year? Check days against 366.
    //Otherwise, check it against 365”
    {
        if (IsLeapYear(year))
        {
            days -= 366;
            year += 1;
            /*You’ll notice we no longer need a break. The loop condition now
             *checks the days properly. Because the loop properly checks
             *whether days is greater than 365 or 366, the second days > 366
             *check is no longer needed. */
        }
        else
        {
            days -= 365;
            year += 1;
        }
    }

However, if this change is made, IsLeapYear() is now being called twice. This is inefficient, especially on small devices (like the devices which would be using this driver). In order to reduce the number of times IsLeapYear() is being called, it would be best to store the value of IsLeapYear() in a variable.

    int leap = IsLeapYear(year);
    //leap is determined before the loop begins.
    //In this case, it would be true (1980 is a leap year)
    while (days > (leap ? 366 : 365))
    {
        if (leap)
        {
            days -= 366;
            year += 1;
        }
        else
        {
            days -= 365;
            year += 1;
        }
        leap = IsLeapYear(year);
        //leap is determined again now that the year has changed.
    }

This can actually be reduced even further. If you look at how the if/else statement is operating, you can see that it’s basically saying “If it’s a leap year, subtract 366. Otherwise, subtract 365,” which is similar to the while loop’s condition!

    int leap = IsLeapYear(year);
    while (days > (leap ? 366 : 365))
    {
        days -= (leap ? 366 : 365);
        //days is equal to days - 366 if it's a leap year,
        //                 days - 365 if it isn't.
        year += 1;
        leap = IsLeapYear(year);
    }

If you wanted to reduce the number of times (leap ? 366 : 365) is checked, you could do this instead:

    int daysThisYear = (IsLeapYear(year) ? 366 : 365);
    //The number of days in the current year is now calculated instead. 
    while (days > daysThisYear)
    {
        days -= daysThisYear;
        year += 1;
        daysThisYear = (IsLeapYear(year) ? 366 : 365);
    }

It’s questionable whether or not this code is any better than the original solution with the break, but this would be the “proper” way to do it (instead of using an arbitrary break in your code). It’s also easier to understand if you know C.

The irony in all of this is that this specific driver is used in multiple Windows CE devices, not just the Zune. This is why quality assurance is so necessary.

There are three morals here:

1. Test every condition which could happen in every single loop in your code (though, as Matt Boehm points out in the comments, this might be a tad bit hard).
2. Don’t visit Digg for programming advice. What you’ll hear is questionable at best
3. Make your code easy to read for other developers.

Using GlassLib in your program

GlassLib is going to be main focus of this part of the series. It supersedes DwmWrapper by implementing a framework around GlassBar which can be used as a complement to your visually-rich forms. In order to use this library in your project, you have to do the following:

1. Include a) a reference to the DLL in your project from Visual Studio: Project menu => Add reference, or b) the actual code files to your C# project (adding them as links (shortcuts) as opposed to copying them is more suitable if you wish include the files in multiple projects and/or wish to make changes to the code yourself).
2. Remember that all of the functionality lies in the GlassLib namespace. You can use the using or Imports clause in the beginning of your C# or VB.NET code file, respectively, or the global imports if you code exclusively in VB.NET.

Exploring the GlassLib Test app

Let’s begin exploring the framework by opening the project file for GlassLibTest. Included in the GlassLib solution, it depends on the GlassLib project reference, which on its part has all the DwmWrapper code.

Open the frmMain.cs file which is the form which is to be executed right at start up. As described in the first part, the first thing the class constructor public frmMain() should do is to set Dwm.ThrowExceptionTypes to DwmExceptionTypes.None in order to avoid any exceptions from being raised when DWM is not enabled or available on the OS, or if any function failed. The next thing the program does is to enable dragging from the Glass-extended area.

Dwm.Glass[this].DragExtendedArea = true; is useful if you want the extended area to act as the caption bar does, like in Windows Media Player. This is what the GlassBar toolbar does as well (more on this later in this part).

Switch to Designer mode (View => Designer) and you can see the layout of the form: the usual Windows Forms buttons, combo and text boxes et cetera, but also GlassBar. To add the latter to your own forms, open the Toolbox (View => Toolbox) and drag it to your form (see figure on right). The toolbar will automatically dock to the bottom of it and extend Glass from this side of the form. You are free to dock it to the whole form (or container for that matter) or one of the other sides.

Because DWM only supports Glass on top-level windows, in designer mode GlassBar falls back to UXTheme API in order to get the theme-specific background image or brush which is suitable for all non-Aero Glass themes such as Aero Basic, Luna (on Windows XP) or Windows Classic on any supported Windows version. On top of this, you can choose to write your own GlassBarRenderer.

This feature provides two key benefits to your application’s design:

• For Windows Vista systems and future OS with support for Glass: rich, seamless Glass UI
• For Windows Vista systems where DWM is disabled or unavailable, and all previous Windows releases: seamless UI deriving from the appropriate Windows theme, including custom themes created with software such as WindowBlinds.

Managing the GlassBar items

Adding your items to GlassBar is quite easy. While in Design Mode, make sure that the Properties pane is visible (View menu => Properties Window to invoke it), select Items and expand the Collection Editor. You can add, remove and rearrange the items. For each one of them you can customize their:

	Name	Used in code only (does not appear in UI)
	Enabled	Enables/disables the item from the UI
	Icon	Preferably translucent PNG image 25×25 pixels in size
	IsSeparator	Denotes whether the item is a separator (its Icon will be disregarded)
	Overlay	Image, useful for ‘hover’ effects
	Text	Alternative text shown when the item is hovered
	Visible	Shows/hides the item

You can of course manage items programmatically using the Items property, for example adding one:

Image img = Image.FromFile(“someFile.png”);

GlassBarItem gbi = new GlassBarItem(“Sample Text” + i, img);

glassBar.Items.Add(gbi);

When the logic of your program requires an item be disabled or hidden, e.g. an unavailable feature, you can use Enabled or Visible to prevent users from clicking it.

Custom renderers

Internally GlassBar defines a standard renderer which on Windows Vista with Aero Glass enables draws on a translucent surface and otherwise falls back to the system-defined theme. If you wish to code a custom renderer for your needs, what you have to do is:

1. Create a class deriving from (inheriting) from one of the following classes:
   • GlassLib.Rendering.DefaultGlassBarRenderer if you wish to customize only specific parts of the default renderer (images, background etc)
   • GlassLib.Rendering.GlassBarRenderer if you wish to build one from the ground up. This requires you to implement all of the methods and properties and is unlikely to be your choice.
2. Decide which functions or images you would like to change. You can assign any image to MainPiece, RightSecondaryStates, AnimationStrip etc.
3. The DrawBarBackground function is called every time the UI changes and needs to be redrawn. It is here where you can change most of the behavior of the default renderer and implement your own features.
4. Assign an instance of your custom renderer to GlassBar
   • glassBar.Renderer = new CustomRenderer(); or to revert to default:
   • glassBar.Renderer = new GlassLib.Rendering.DefaultGlassBarRenderer();

The test app

There is a test program added to the package, GlassLibTest, whose code and compiled binary you can explore and experiment with GlassBar and DWM.

If you have any comments, questions, wishes or just an opinion, I would be happy to hear it.

In a three-part blog post, I will show you how to use a wrapper around the Desktop Window Manager Application Programming Interface in order to control its state, change colorization, or change the rendering policy of windows from your Windows Forms and .NET 3 Presentation Foundation programs.

Getting Started

Windows Forms and Windows Presentation Foundation will be referred to in these posts as WF and WPF respectively.

The code you will need can be downloaded from here and is written in C# (as are the code samples in this post). That being said, you can use it in projects of any other .NET language — you can include the compiled libraries as references. Otherwise (if you code in C#), you also have the option to include the files in your project and not distribute a separate library. The solution is for use in Visual Studio 2005 but is also compatible with version 2008.

The whole framework is located under the GlassLib namespace and is the source to three main types of projects:

• DwmWrapper is a .NET wrapper around the DWM API, which can be compiled in the following flavors:
  • No dependency on WF or WPF. It can be used to avoid DLL clutter when coding command-line applications to manipulate the DWM.
  • Solely WF or WPF
  • Both for mixed-framework projects.
• GlassLib is a WF-powered layer above DwmWrapper and provides a set of classes, including the GlassBar control for use in your forms
• The Test Projects you can use to try the various features that the two other projects have. They will be used here ad hoc.

In this first part, we will explore the architecture of the wrapper, its core functionality and application in Windows Forms programs.

Microsoft provides an API for DWM in the equivocal DwmApi library. Encapsulating it for easier use in .NET programs is the wrapper’s main purpose.

Since all necessary classes are located under the GlassLib namespace, in order to avoid writing it every time, I would suggest that you insert it in your C# or VB code file’s “imports” or, if you are working exclusively with VB, in your project’s “Imported Namespaces” list in order to avoid doing the first as well.

The most important class is Dwm and can be used to control virtually any aspect of DWM as long as the public API allows it. The various features are available via the following properties of Dwm:

	Blur	Enables/disables the black background transition when a window (not necessarily your window) is maximized, sets custom blur region
	Colorization	Gets/sets the Aero Glass colorization
	Composition	Enable/disable DWM, check if running and if the system is DWM-capable
	Events	Used to set up notifications for colorization, composition, non-client rendering or window-maximized changes
	Flip3D	Start/Stop Windows Flip3D or Flip
	Glass	Enable/disable Glass on a given form (via its instance, e.g. this) or window (via its handle/hWnd, an IntPtr)
	NonClientArea	For advanced users only, gets or sets how DWM is handing the painting of a given form or window (see Glass above)

Using the Wrapper

Note that DWM is only available on Windows Vista, so I would suggest that you select how to handle the wrapper’s behavior on earlier operating systems. Otherwise, exceptions will be raised which you will have to catch.

The first option is to limit the exceptions the wrapper will raise by setting Dwm.ThrowExceptionTypes to one of the available DwmExceptionTypes

	None
	UnsupportedFeatures
	DesktopWindowManager

Raising no exception will most likely suit your needs best so adjust this property before you make any other changes to DWM, preferably at program startup or in the form’s constructor.

Dwm.ThrowExceptionTypes = DwmExceptionTypes.None;

Now you can make any changes you want to your form’s state in the DWM, for example enable Glass–it is as easy as writing

Dwm.Glass[this] = new DwmMargins(100, 4, 8, 20);

where this is the instance of the form (you can replace this with any other form instance you would like) and the margins are defined as left-right-top-bottom. You can use DwmMargins.EntireWindow instead to extend glass in the whole window client area, like Mobility Center does in Windows Vista.

Restoring the default borders is done by calling the Restore method.

Dwm.Glass[this].Restore();

Receiving notifications on the global DWM state or on your forms’ is important in order to know how you should handle painting backgrounds or the non-client area. You can choose to get notified when the Aero Glass colorization is changed or DWM starts up or shuts down. In GlassLib this is straightforward: each form that you wish to be notification-aware, GlassLib will include in its list and you have to attach your handlers to the colorization, composition, non-client rendering or window-maximized changes.

Dwm.Events[this].AddHandlers(); // Notifying GlassLib…

// Add our handlers

Dwm.Events[this].CompositionChanged += new DwmEventHandler(OnCompositionChanged);
Dwm.Events[this].ColorizationChanged += new DwmEventHandler(OnColorizationChanged);

…

private void OnCompositionChanged(object sender, DwmEventArgs e)
{
// Update the UI on composition change (extend glass if DWM is enabled, otherwise restore)
if (Dwm.Glass[this].Enabled)
Dwm.Glass[this].Margins = new DwmMargins(100, 4, 8, 20);
else
Dwm.Glass[this].Restore();
}

private void OnColorizationChanged(object sender, DwmEventArgs e)
{
MessageBox.Show(e.Colorization.ToString());
}

Although the public DWM API does not make it easy for one to change the colorization programmatically, DwmWrapper exposes this functionality through the Dwm.Colorization property. Controlling the Desktop Window Manager is also as easy as setting Dwm.Composition.Enabled to the desired value, either true or false. Other useful “one-liners” include invoking Windows Flip and Flip 3D: Dwm.Flip3D.EnterAltTab(); and Dwm.Flip3D.Enter();, respectively.

You can tinker with the full GlassLib source code and the included test projects to see how all of the aforementioned features work in a real environment. In the next part I am going to cover the more advanced functionality of the wrapper, the Windows Forms test app and how it manages DWM thumbnails.

If you have any comments, questions, wishes or just an opinion, feel free to post it here.

Part 2 coming soon…

You are free to use GlassLib in your freeware programs, but please at least acknowledge it in your release notes/about dialog/website. In case your program is commercial/shareware, I would appreciate it if you could contact me beforehand. Thanks.

How to work with the System Tray from .Net (PDF)