Platform SDK: Network Management

NetAlertRaise

The NetAlertRaise function notifies all registered clients when a particular event occurs.

To simplify sending an alert message, you can call the extended function NetAlertRaiseEx instead. NetAlertRaiseEx does not require that you specify a STD_ALERT structure.

Security Requirements

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

NET_API_STATUS NetAlertRaise(
  LPCWSTR AlertEventName,  
  LPVOID Buffer,           
  DWORD BufferSize         
);

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.

Buffer

[in] Pointer to the data to send to the clients listening for the interrupting message. The data should begin with a fixed-length STD_ALERT structure followed by additional message data in one ADMIN_OTHER_INFO, ERRLOG_OTHER_INFO, PRINT_OTHER_INFO, or USER_OTHER_INFO structure. Finally, the buffer should include 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.

BufferSize

[in] Specifies the size of the message buffer, in bytes.

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 NetAlertRaise function, or the function fails with ERROR_FILE_NOT_FOUND.

The following code sample demonstrates how to raise an administrative alert by calling the NetAlertRaise function and specifying STD_ALERT and ADMIN_OTHER_INFO structures. First, the sample calculates the size of the message buffer. Then it allocates the buffer with a call to the GlobalAlloc function. The code assigns values to the members of the STD_ALERT and the ADMIN_OTHER_INFO portions of the buffer. The sample retrieves a pointer to the ADMIN_OTHER_INFO structure by calling the ALERT_OTHER_INFO macro. 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 <time.h>
#include <lm.h>

const int ALERT_VAR_DATA_SIZE = 216;

int wmain(int argc, wchar_t *argv[])
{
   int nBufferSize;
   LPVOID pAlertOtherInfo;
   PSTD_ALERT pStdAlert;              // STD_ALERT structure
   PADMIN_OTHER_INFO pAdminOtherInfo; // ADMIN_OTHER_INFO structure
   LPVOID pVarData; 
   time_t now;
   DWORD dwResult;
   //
   // Check command line arguments.
   //
   if (argc != 2)
   {
      fwprintf(stderr, L"Usage: %s LogFileName\n", argv[0]);
      exit(1);
   }
   // Calculate the buffer size;
   //  then allocate the memory for the buffer.
   //
   nBufferSize  = sizeof(STD_ALERT) + ALERT_VAR_DATA_SIZE;
   pAlertOtherInfo = (LPVOID) GlobalAlloc(GPTR, nBufferSize);

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

   //
   // Assign values to the STD_ALERT portion of the buffer.
   //   (This is required when you call NetAlertRaise.)
   //
   pStdAlert = (PSTD_ALERT)pAlertOtherInfo;
   time( &now );
   pStdAlert->alrt_timestamp = (DWORD)now;
   wcscpy(pStdAlert->alrt_eventname, ALERT_ADMIN_EVENT);
   wcscpy(pStdAlert->alrt_servicename, argv[0]);
   //
   // Retrieve the pointer to the ADMIN_OTHER_INFO structure 
   //  that follows the STD_ALERT portion of the buffer.
   /   Do this by calling the ALERT_OTHER_INFO macro.
   //
   pAdminOtherInfo = (PADMIN_OTHER_INFO)ALERT_OTHER_INFO(pAlertOtherInfo);
   //
   // Assign values to the ADMIN_OTHER_INFO structure.
   //
   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_DATASIZE – (pVarData – pStdAlert) - 1);
   //
   // Send an administrative alert by calling the
   //  NetAlertRaise function.
   //
   dwResult = NetAlertRaise(ALERT_ADMIN_EVENT,
                            pAlertOtherInfo,
                            nBufferSize);
   //
   // Display the results of the function call.
   //
   if (dwResult != NERR_Success)
      wprintf(L"NetAlertRaise failed: %d\n", dwResult);
   else
      wprintf(L"Administrative alert raised successfully.\n");
   //
   // Free the allocated memory.
   //
   GlobalFree(pAlertOtherInfo);

   return (dwResult);
}

Requirements