Windows Mobile 6.5 Notification Balloon APIs Explained

In Windows Mobile 6.5, third-party developers relied on a dedicated set of shell notification APIs to display interactive, system-level balloon alerts to users. This article details how developers utilized the underlying aygshell.dll functions—specifically SHNotificationAdd, the SHNOTIFICATIONDATA structure, and HTML-based layout capabilities—to push dynamic alerts, capture user responses, and manage notification lifecycles within the mobile operating system.

The Notification Architecture

Windows Mobile 6.5 inherited its alert system from the Windows CE core, relying heavily on the AYGShell (Application-Yielding Graphics Shell) library. Rather than generating separate, floating window controls that could interfere with active tasks, developers called standardized shell functions to hand off alert duties to the operating system's notification manager. This manager queued alerts, determined visual hierarchy, and rendered balloon prompts over the top title bar or taskbar area.

Registering an Alert with SHNotificationAdd

The primary entry point for displaying balloon alerts was the SHNotificationAdd function. To create a notification, an application had to allocate and populate an SHNOTIFICATIONDATA structure and pass its pointer to the function:

LRESULT SHNotificationAdd(SHNOTIFICATIONDATA *pndAdd);

The SHNOTIFICATIONDATA structure defined the alert's appearance, behavior, and persistence:

  • Identification (clsid and dwID): Every notification required a unique Class ID (CLSID) and a 32-bit identifier. This combination allowed the system to distinguish between alerts from different applications and let the calling app target specific alerts for updates or dismissal.
  • Priority (npPriority): Developers defined urgency levels such as SHNP_INFORM for standard information bubbles or SHNP_ICONIC to simply show an icon in the tray area without immediately popping up the message bubble.
  • Duration (csDuration): This defined how long (in seconds) the bubble remained visible before automatically collapsing into a background icon.
  • Flags (grfFlags): Flags determined hardware triggers. Developers used values like SHNF_DISPLAYON to wake the screen, alongside options to play predefined alert sounds, trigger vibration motors, or repeat alerts until dismissed.

Formatting Content with HTML

Unlike earlier mobile operating systems that only accepted raw text strings, Windows Mobile 6.5 allowed developers to embed lightweight HTML directly inside notification balloons via the pszHTML field.

The notification engine rendered this markup using a stripped-down Pocket Internet Explorer layout component. This enabled third-party applications to:

  • Format text with headers, bold weights, and basic styling.
  • Present actionable links that, when tapped, executed custom command schemes.
  • Embed forms containing radio buttons, checkboxes, or plain text inputs directly inside the notification window.

Handling User Interaction

To capture user actions from the balloon, developers configured the hwnd and uMsg members of SHNOTIFICATIONDATA. When a user clicked a link, tapped a button, or manually dismissed the balloon, the system sent a window message back to the application's message loop.

For HTML links, the notification manager intercepted anchor tags with a custom URL scheme (such as cmd:#). When tapped, the system forwarded the command parameter back to the target window procedure in a WM_NOTIFY message containing an NMPRNOTIFY structure. This allowed an application to process user confirmations, snoozes, or custom shortcuts without bringing the full application to the foreground.

Updating and Dismissing Notifications

Third-party applications retained full control over active notifications via their unique identifier pair:

  • SHNotificationUpdate: If status information changed (such as download progress or new incoming data), an application could modify the text or HTML content on the fly without closing and reopening the balloon, preventing screen flicker.
  • SHNotificationRemove: When the alert was no longer relevant or when the user handled the condition elsewhere in the app, the developer called this function to instantly clear the balloon and its corresponding taskbar icon.