Platform SDK: Network Management

NetAlertRaiseEx

The NetAlertRaiseEx function notifies all registered clients when a particular event occurs. You can call this extended function to simplify the sending of an alert message because NetAlertRaiseEx does not require that you specify a STD_ALERT structure.

Security Requirements

No special group membership is required to successfully execute the NetAlertRaiseEx function.

NET_API_STATUS NetAlertRaiseEx(
  LPCWSTR AlertEventName,  
  LPVOID VariableInfo,     
  DWORD VariableInfoSize,  
  LPCWSTR ServiceName      
);

Parameters

AlertEventName

[in] Pointer to a constant Unicode string that specifies the alert class (type of alert) to raise. This parameter can be one of the following predefined values, or a user-defined alert class for network applications. (The event name for an alert can be any text string.)

Name	Meaning
ALERT_ADMIN_EVENT	An administrator's intervention is required.
ALERT_ERRORLOG_EVENT	An entry was added to the error log.
ALERT_MESSAGE_EVENT	A user or application received a broadcast message.
ALERT_PRINT_EVENT	A print job completed or a print error occurred.
ALERT_USER_EVENT	An application or resource was used.

VariableInfo

[in] Pointer to the data to send to the clients listening for the interrupting message. The data should consist of one ADMIN_OTHER_INFO, ERRLOG_OTHER_INFO, PRINT_OTHER_INFO, or USER_OTHER_INFO structure followed by any required variable-length information. For more information, see the code sample in the following Remarks section.

The calling application must allocate and free the memory for all structures and variable data.

VariableInfoSize

[in] Specifies the number of bytes of variable information in the buffer pointed to by the VariableInfo parameter.

ServiceName

[in] Pointer to a constant Unicode string that specifies the name of the service raising the interrupting message.

Return Values

If the function succeeds, the return value is NERR_Success.

If the function fails, the return value is a Win32 API error code. For a list of error codes, see Error Codes.

Remarks

The alerter service must be running on the client computer when you call the NetAlertRaiseEx function, or the function fails with ERROR_FILE_NOT_FOUND.

The following code sample demonstrates how to raise an administrative alert by calling the NetAlertRaiseEx function and specifying an ADMIN_OTHER_INFO structure. First, the sample allocates the message buffer with a call to the GlobalAlloc function. The code assigns values to the members of the ADMIN_OTHER_INFO portion of the buffer. It also retrieves a pointer to the variable data portion of the buffer by calling the ALERT_VAR_DATA macro. Finally, the code sample frees the memory allocated for the buffer with a call to the GlobalFree function.

#ifndef UNICODE
#define UNICODE
#endif

#include <windows.h>
#include <stdio.h>
#include <lm.h>

const int ALERT_VAR_DATA_SIZE = 216;

int wmain(int argc, wchar_t *argv[])
{
   PADMIN_OTHER_INFO pAdminOtherInfo; // ADMIN_OTHER_INFO structure
   LPVOID pVarData;
   DWORD dwResult;
   //
   // Check command line arguments.
   //
   if (argc != 2)
   {
      fwprintf(stderr, L"Usage: %s LogFileName\n", argv[0]);
      exit(1);
   }
   //
   // Allocate memory for the buffer, and
   //  assign values to the ADMIN_OTHER_INFO structure.
   //
   pAdminOtherInfo = (PADMIN_OTHER_INFO)GlobalAlloc(GPTR, ALERT_VAR_DATA_SIZE);

   if (pAlertOtherInfo == NULL)
   {
       fwprintf(stderr, L"Unable to allocate memory\n");
       exit(1);
   }

   pAdminOtherInfo->alrtad_numstrings = 1;
   //
   // Error 2377, NERR_LogOverflow, indicates
   //  a log file is full.
   //
   pAdminOtherInfo->alrtad_errcode = 2377;
   //
   // Retrieve the pointer to the variable data portion
   //  of the buffer by calling the ALERT_VAR_DATA macro.
   //
   pVarData = (LPTSTR)ALERT_VAR_DATA(pAdminOtherInfo);
   //
   // Supply the log file name for error 2377.
   //
   wcsncpy(pVarData,
                 argv[1],
                 ALERT_VAR_DATA_SIZE –
                 (pVarData – pAdminOtherInfo) - 1);
   //
   // Send an administrative alert by calling the
   //  NetAlertRaiseEx function.
   //
   dwResult = NetAlertRaiseEx(ALERT_ADMIN_EVENT,
                              (LPVOID)pAdminOtherInfo,
                              ALERT_VAR_DATA_SIZE,
                              argv[0]);
   //
   // Display the results of the function call.
   //
   if (dwResult != NERR_Success)
      wprintf(L"NetAlertRaiseEx failed: %d\n", dwResult);
   else
      wprintf(L"Administrative alert raised successfully.\n");
   //
   // Free the allocated memory.
   //
   GlobalFree(pAdminOtherInfo);

   return (dwResult);
}

Requirements