Working with Notifications

The Windows Home Server notification infrastructure provides a way for an application to alert end users or other applications on the home server about events that are important to the application, such as a serious application error.

Windows Home Server also uses the notification infrastructure to alert end users and applications about important Windows Home Server events. When a significant event occurs—for example, when a hard disk fails—applications that are registered to receive notifications receive notification of the event.

Some types of notifications also appear in the Home Network Health dialog in Windows Home Server, as well as in the notification area of each client computer that is joined to the Windows Home Server network.

By using Windows Home Server, you can write applications that add notifications, that are registered to receive notifications, or both.

Important

The Notification API is available for use on Windows clients that have the Windows Home Server Connector software installed as well as Windows Home Server for use in the implementation of custom notification applications.

Create a Notification Example

Step 1: Create an instance of WHSInfoClass

To create a notification, you first need to create an instance of WHSInfoClass, as follows:

WHSInfoClass pInfo = new WHSInfoClass();

Dim pInfo As New WHSInfoClass()

Step 2: Optional: Call the Init(System.String) method

It is not necessary to call this method, since the SDK automatically initializes the WHSInfoClass object the first time any SDK functionality is used.

Note

The default initialization uses the friendly name of the application domain as the application name. If you want to use a different name as the application identifier, you must initialize the WHSInfoClass yourself before using any of the SDK functionality. Calling the Init method after the object has already been initialized raises an exception.

Have your application signal the Windows Home Server notification infrastructure by using the Init method. When you call this method, the notification infrastructure associates your application with the unique identifier that you passed in with the Init method call.

For this example, identify an application named MyWHSApp to the Windows Home Server notification infrastructure, as follows:

pInfo.Init("MyWHSApp");

pInfo.Init("MyWHSApp")

Important

The Windows Home Server notification infrastructure does not work correctly if multiple instances of an application are running on the same computer and are using the same application name. To run multiple instances of your application on the same computer, you must provide a unique identifier for each instance. You can use a GUID as a unique identifier.

Step 3: Call the AddNotification(System.String,Microsoft.HomeServer.SDK.Interop.v1.WHS_Notification_Severity,System.String,System.String) method

When a condition occurs in your application for which you want to send a notification, you need to add the notification to the Windows Home Server notification infrastructure. To do so, use the AddNotification method.

This method takes the following parameters:

Parameter	Description
UniqueID	A string that contains a unique identifier for the notification.
State	An enumeration of type WHS_Notification_Severity. Depending upon the severity, some notifications appear in the Home Network Health dialog on Windows Home Server and are further identified by color: Red: Notifications with a WHS_Notification_Severity type of WHS_ERROR. Yellow: Notifications with a WHS_Notification_Severity type of WHS_WARNING.
textHeader	A string containing the notification caption.
textDescription	A string containing the notification message text.
helpFilename	A string that contains the absolute path to a help file. For example, "C:\HelpDocs\help.chm".
helpSection	A string that contains the name of a topic in the help file.
helpLinkText	A string that contains the link text for a hyperlink to the file.

In this example, create a notification with a WHS_Notification_Severity type of WHS_INFO and the caption "Hello, World!" as follows:

pInfo.AddNotification("????????-92c0-43bb-b432-a519d120663a", 
  WHS_Notification_Severity.WHS_INFO, "Hello, World", "Hello World!", "", "", "");

pInfo.AddNotification("????????-92c0-43bb-b432-a519d120663a", WHS_Notification_Severity.WHS_INFO, "Hello, World", "Hello World!", "", "", "")

Note

Because this notification has a WHS_Notification_Severity type of WHS_INFO, it does not appear in the Home Network Health dialog on Windows Home Server or in the notification area of client computers. However, all applications that are registered for notifications receive the notification.

Step 4: Call the RemoveNotification(System.String) method

After the condition that caused your application to send a notification is resolved or no longer reflects the system state, you should call the RemoveNotification to remove your notification from the list of notifications. Additionally, this removes your notification from the notifications that appear in the Home Network Health dialog and the notification area of the client computers.

For example, if you previously added a notification describing a hardware component that is no longer connected to Windows Home Server, call RemoveNotification to remove the notification from the system.

Note

When your application stops running, the notification infrastructure removes all notifications that are currently associated with your application. For example, if your application adds a notification with a WHS_Notification_Severity type of WHS_ERROR and then the application stops running, the notification infrastructure removes the WHS_ERROR from the list of existing notifications.

The RemoveNotification method takes a single parameter of type System.String, which uniquely identifies the notification that you want to remove. In this example, remove the notification that you created in Step 2:

pInfo.RemoveNotification("????????-92c0-43bb-b432-a519d120663a");

pInfo.RemoveNotification("????????-92c0-43bb-b432-a519d120663a")

Registering for Notifications

If you are creating an application that needs to consume notifications from Windows Home Server, you can register your application for notifications by using the Windows Home Server API.

Step 1: Implement the Microsoft.HomeServer.SDK.Interop.v1.INotificationCallback interface

To register for notifications on Windows Home Server, create a class that implements the INotificationCallback interface.

For example, if your application displays Windows Home Server notification events to an LCD panel, you can create a class, called pMyLCDDisplay, that implements INotificationCallback. When the Windows Home Server notification infrastructure processes a notification event, it calls the appropriate INotificationCallback methods in the pMyLCDDisplay class:

class pMyLCDDisplay : Microsoft.HomeServer.SDK.Interop.v1.INotificationCallback
  {
     // Implement the Microsoft.HomeServer.SDK.Interop.v1.INotificationCallback methods here
  }

Class pMyLCDDisplay
    Inherits Microsoft.HomeServer.SDK.Interop.v1.INotificationCallback

End Class

Step 2: Create an instance of WHSInfoClass

After you create a class that implements INotificationCallback, pMyLCDDisplay, create an instance of WHSInfoClass in order to call the RegisterForNotifications method:

WHSInfoClass pInfo = new WHSInfoClass();

Dim pInfo As New WHSInfoClass()

Step 3: (Optional) Call the Init(System.String) method

It is not necessary to call this method, since the SDK automatically initializes the WHSInfoClass object the first time any SDK functionality is used.

Note

The default initialization uses the friendly name of the application domain as the application name. If you want to use a different name as the application identifier, you must initialize the WHSInfoClass yourself before using any of the SDK functionality. Calling the Init method after the object has already been initialized raises an exception.

For this example, identify an application named MyWHSApp to the Windows Home Server notification infrastructure, as follows:

pInfo.Init("MyWHSApp");

pInfo.Init("MyWHSApp")

Step 4: Call the WHSInfoClass.RegisterForNotifications(Microsoft.HomeServer.SDK.Interop.v1.INotificationCallback) method

The RegisterForNotifications method takes a parameter of type INotificationCallback. The pMyLCDDisplay class that you created is of type INotificationCallback, so you can pass it in as the parameter to the RegisterForNotifications method call:

pInfo.RegisterForNotifications(pMyLCDDisplay);

pInfo.RegisterForNotifications(pMyLCDDisplay)

With that method call, your LCD display application is registered for notifications with the Windows Home Server notification infrastructure. When any notification is processed, the notification infrastructure calls the appropriate methods from your pMyLCDDisplay class.

Step 5: (Optional) Call the WHSInfoClass.UnRegisterForNotifications() method

If you no longer want your application to be registered for Windows Home Server notifications, you can call the UnRegisterForNotifications to stop your application from listening for Windows Home Server notifications:

pInfo.UnRegisterForNotifications();

pInfo.UnRegisterForNotifications()

The notification infrastructure removes your application from the list of applications that are registered to receive notifications.

See Also

Reference

WHSInfoClass
INotificationCallback
WHS_Notification_Severity
WHS_Notification_Type

Concepts

Extending Windows Home Server
Working with WHSInfoClass
Working with Client Computers
Working with Application Folders
Working with Managed Volumes
Working with Hard Disks
Working with Backups

Other Resources

Working with Shared Folders