NetAlertRaise 函数 (lmalert.h)

项目
02/28/2024

[自 Windows Vista 起不支持此函数，因为不支持警报器服务。]

发生特定事件时 ，NetAlertRaise 函数会通知所有已注册的客户端。

若要简化发送警报消息，可以改为调用扩展函数 NetAlertRaiseEx 。 NetAlertRaiseEx 不需要指定 STD_ALERT 结构。

语法

NET_API_STATUS NET_API_FUNCTION NetAlertRaise(
  [in] LPCWSTR AlertType,
  [in] LPVOID  Buffer,
  [in] DWORD   BufferSize
);

参数

[in] AlertType

指向常量字符串的指针，该字符串指定要引发的警报类 (警报) 类型。此参数可以是以下预定义值之一，也可以是网络应用程序的用户定义的警报类。警报的事件名称可以是任何文本字符串。

名称	含义
ALERT_ADMIN_EVENT	需要管理员的干预。
ALERT_ERRORLOG_EVENT	错误日志中添加了一个条目。
ALERT_MESSAGE_EVENT	用户或应用程序收到了广播消息。
ALERT_PRINT_EVENT	打印作业已完成或发生打印错误。
ALERT_USER_EVENT	使用了应用程序或资源。

[in] Buffer

指向要发送到侦听中断消息的客户端的数据的指针。数据应以固定长度 STD_ALERT 结构开头，后跟一个 ADMIN_OTHER_INFO、 ERRLOG_OTHER_INFO、 PRINT_OTHER_INFO或 USER_OTHER_INFO 结构中的其他消息数据。最后，缓冲区应包含任何必需的可变长度信息。有关详细信息，请参阅以下“备注”部分中的代码示例。

调用应用程序必须为所有结构和变量数据分配和释放内存。有关详细信息，请参阅网络管理功能缓冲区。

[in] BufferSize

消息缓冲区的大小（以字节为单位）。

返回值

如果函数成功，则返回值NERR_Success。

如果函数失败，则返回值为系统错误代码，可以是以下错误代码之一。有关所有可能的错误代码的列表，请参阅系统错误代码。

返回代码	说明
ERROR_INVALID_PARAMETER	参数不正确。如果 AlertEventName 参数为 NULL 或空字符串、 Buffer 参数为 NULL 或 BufferSize 参数小于 STD_ALERT 结构的大小加上附加消息数据结构的固定大小，则返回此错误。
ERROR_NOT_SUPPORTED	不支持该请求。此错误在 Windows Vista 和更高版本上返回，因为不支持警报器服务。

注解

无需特殊的组成员身份即可成功执行 NetAlertRaise 函数。

调用 NetAlertRaise 函数时，警报器服务必须在客户端计算机上运行，否则该函数因ERROR_FILE_NOT_FOUND而失败。

示例

以下代码示例演示如何通过调用 NetAlertRaise 函数并指定 STD_ALERT 和 ADMIN_OTHER_INFO 结构来引发管理警报。首先，该示例计算消息缓冲区的大小。然后，它通过调用 GlobalAlloc 函数来分配缓冲区。代码将值分配给 STD_ALERT 成员和缓冲区 的ADMIN_OTHER_INFO 部分。该示例通过调用 ALERT_OTHER_INFO 宏来检索指向 ADMIN_OTHER_INFO 结构的指针。它还通过调用 ALERT_VAR_DATA 宏来检索指向缓冲区的变量数据部分的指针。最后，代码示例通过调用 GlobalFree 函数释放为缓冲区分配的内存。

#ifndef UNICODE
#define UNICODE
#endif
#pragma comment(lib, "netapi32.lib")

#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_s(pStdAlert->alrt_eventname, EVLEN + 1, ALERT_ADMIN_EVENT);
   wcscpy_s(pStdAlert->alrt_servicename, SNLEN + 1, 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_s((wchar_t*) pVarData, ALERT_VAR_DATA_SIZE/2, 
           argv[1],
           ALERT_VAR_DATA_SIZE/2 );
   //
   // 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);
}

要求

要求	值
最低受支持的客户端	Windows 2000 Professional [仅限桌面应用]
最低受支持的服务器	Windows 2000 Server [仅限桌面应用]
目标平台	Windows
标头	lmalert.h (包括 Lm.h)
Library	Netapi32.lib
DLL	Netapi32.dll