Raising and Displaying Alerts

  • Article

Server Appliance Kit

You can raise and display alerts on both status pages and the local UI.

To raise and display an alert

  1. Add element definitions for the alert under the HKLM\Software\Microsoft\ServerAppliance\ElementManager\WebElementDefinitions registry key.

    You must create one definition per alert for each display location. If you want the same alert to appear on the Web UI main status page, the Shutdown status page, and the local UI, you must create three definitions.

  2. Use the IApplianceServices::RaiseAlert method to raise the alert, as described in the appsrvcs.idl file. This file is located in the \SDK\Chime\Idl folder on the Server Appliance Kit 3.0 CD-ROM.

    The following table lists the arguments in the order in which they are to be passed and describes each one.

    Argument Description
    AlertType This is one of the SA_ALERT_TYPE values as defined in appsrvcs.idl.
    • SA_ALERT_TYPE_ATTENTION is used to indicate some information is available.
    • SA_ALERT_TYPE_MALFUNCTION is used to indicate a warning.
    • SA_ALERT_TYPE_FAILURE is used to indicate a critical error.
    AlertID The identifier for the alert. This is used along with the AlertLog value to uniquely identify the alert. There must be a corresponding entry under the ElementManager registry key for the alert to be displayed.
    AlertLog The text string used to help identify the alert. Past convention used the name of the resource file that contains the resource strings for the alert.
    AlertSource Obsolete. This is the name of the subkey under HKLM\Software\Microsoft\ServerAppliance\LocalDisplayManager\Resources. This value must be VT_EMPTY.
    TimeToLive This determines the length of time, in milliseconds (ms), that the alert must exist. If an alert does not time out, this value must be SA_ALERT_DURATION_ETERNAL, as defined in appsrvcs.idl.
    ReplacementStrings These are strings that can be plugged into the message obtained from the resource DLL. If the message does not take any replacement strings, this value must be set to VT_EMPTY. For more information, see the appsrvcs.idl file.
    RawData This is for any additional date that might be needed. This value must be set to VT_EMPTY if no additional data is needed. For more information, see the appsrvcs.idl file.
    Cookie This is the return value identifying which alert is raised.

To clear an alert

  • Use the cookie obtained on RaiseAlert to call the IApplianceServices::ClearAlert method. 

    /* This function uses the cookie obtained on RaiseAlert to clear the alert. */
HRESULT lApplianceServices::ClearAlert ([in] LONG lAlertCookie)

    lAlertCookie is the alert cookie returned by the RaiseAlert() function.

  • Alternatively, all alerts with a given Alert ID and Alert Log can be cleared by calling the lApplianceServices::ClearAlertAll method. 

    /* This function clears all alerts with a given Alert ID and Alert Log. */
HRESULT lApplianceServices::ClearAlert ( [in] LONG lAlertID, [in] BSTR bstrAlertLog )

    lAlertID is the ID of the alert to clear, and bstrAlertLog is the alert log where the alert resides.

If a call fails, or the alert does not appear, you can use the following procedure to debug the problem.

To debug an alert

  1. If the RaiseAlert call fails, check the HRESULT returned as described in the WMI software development kit (SDK). To view the SDK, see this Microsoft Web site.
  2. If the call succeeds, but no alert can be seen on the LCD or browser, try using the WBEMTEST tool that ships with the WMI SDK. To find the WBEMTEST tool, see this Microsoft Web site.

To use the WBEMTEST tool

  1. Start WBEMTEST.

  2. Connect to ROOT\CIMV2.

  3. Select the Enum_Instances button.

  4. Enter Microsoft_SA_Alert for the superclass name.

    If you can see alerts, it means the alerts are being generated but the registry keys are incorrect.

    Note

    • It is important that the application developer creates a Web UI alert definition for every alert that can be raised. This means that every alert that appears on the shutdown page and the local UI needs to also appear on the main status page of the Web UI.

Defining the Replacement Strings

When you raise an alert, you pass in an array of strings for the varReplacementStrings parameter. When the alert is displayed, the strings that were passed in to the alert replace the %n strings in the order specified in the message.

The following code sample shows how replacement strings are used.

  // Constants
const long TIME_TO_LIVE=30000      // in milliseconds

// Declare variables
DWORD      dwAlertType = SA_ALERT_TYPE_ATTENTION;
DWORD      dwAlertId = SA_SAMPLEAPP_CHIME_CHIME_ALERT; // from the resource dll header file
_bstr_t      bstrAlertLog(RESOURCE_DLL_NAME);
_bstr_t      bstrAlertSource(L"");
_variant_t   varReplacementStrings;
_variant_t   varRawData;
LONG       lCookie;

HRESULT    hrRet=S_OK;

// Initalize the varReplacementStrings variant.
VariantInit(&varReplacementStrings);

// Create the SAFEARRAY.
SAFEARRAY *psa;
V_ARRAY(&varReplacementStrings) = SafeArrayCreateVector(VT_BSTR, 0, 1);
psa=V_ARRAY(&varReplacementStrings); //initialize the psa pointer

if (psa == NULL)
{
   // error handling here...
}

// Set the type.
V_VT(&varReplacementStrings) = VT_ARRAY | VT_BSTR;

// Lock the array data.
BSTR *pData;
hrRet = SafeArrayAccessData(psa, (void**)&pData);

if (FAILED(hrRet))
{
      // error handling here...
}

// Pass a string into the variant structure
pData[0]=SysAllocString(L"Value1");

// Call RaiseAlert
hrRet = pAppSrvcs->RaiseAlert(dwAlertType,
            dwAlertId,
            bstrAlertLog,
            bstrAlertSource,
            TIME_TO_LIVE,
            &varReplacementStrings,
            &varRawData,
            &lCookie);

In this example, the AlertDefinition caption of Chime %1 would become Chime Value1.

SA_GetLocString works similarly in regards to replacement strings. An additional advantage of replacement strings is that a localizer can change the string to match the word order of a different language.

Raising and Clearing an Alert from an ASP Page

The following sample code demonstrates how to raise an alert from an ASP page. To view the alert, you an alert definition that matches the AlertLog and AlertID used when raising the alert.

  Call TestAlerts()
 
Public Function TestAlerts()
   On Error Resume Next
   Err.Clear
 
   Const SA_ALERT_CLASS = "Microsoft_SA_Resource"
   Const SA_ALERT_DURATION_ETERNAL = 2147483647
   
   Const SA_ALERT_TYPE_WARNING = 0
   Const SA_ALERT_TYPE_FAILURE = 1
   Const SA_ALERT_TYPE_INFORMATION = 2
   
   Const SA_ALERT_NORMAL = 0
   Const SA_ALERT_SINGLETON = 1
   
   Const AUTOLANGCONFIG_LOG = "AutoLangConfig"
   Const AUTOLANGCONFIG_ALERT_RestartRequired = 1
 
   Dim oAppServices
   Dim rawData
   Dim nullRepStrings
   Dim idCookie
 
   '
   ' Create Appliance Services object
   '
   Set oAppServices = CreateObject("Appsrvcs.ApplianceServices")
   If Err.Number <> 0 Then
       ' Object was not created; handle appropriately 
       Exit Function
   End If
   
   '
   ' Initialize it
   '
   oAppServices.Initialize()
   If Err.Number <> 0 Then
       ' Initialization failed; handle appropriately 
       Exit Function
   End If
 
   '
   ' Check to see if the alert is present
   '
   bIsPresent = oAppServices.IsAlertPresent(AUTOLANGCONFIG_ALERT_RestartRequired, AUTOLANGCONFIG_LOG)
   If ( Err.Number <> 0 ) Then
      ' Unexpected error; handle appropriately
   Else
      ' Alert is present; handle appropriately
   End If
      
   '
   ' Raise Singleton Alert
   '
   idCookie = oAppServices.RaiseAlertEx(SA_ALERT_TYPE_WARNING, _
               AUTOLANGCONFIG_ALERT_RestartRequired, _
               AUTOLANGCONFIG_LOG, _
               SA_ALERT_CLASS, _
               SA_ALERT_DURATION_ETERNAL, _
               nullRepStrings, _
               rawData, _
               SA_ALERT_SINGLETON)
   If ( Err.Number <> 0 ) Then
      ' Unexpected error; handle appropriately
   Else
      If ( idCookie <> 0 ) Then
         ' Alert was successfully raised; handle appropriately
      Else
         ' Alert already existed; handle appropriately
      End If
   End If
 
   '
   ' Clear the alert
   '
   Call oAppServices.ClearAlertAll(AUTOLANGCONFIG_ALERT_RestartRequired, AUTOLANGCONFIG_LOG)
   If ( Err.Number <> 0 ) Then
      ' Unexpected error; handle appropriately
   Else
      ' Alert was cleared successfully; handle appropriately
   End If
 
   oAppServices.Shutdown()                              
   oAppServices = Nothing
End Function