NetAlertRaiseEx 函数 (lmalert.h)

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

发生特定事件时 ，NetAlertRaiseEx 函数会通知所有已注册的客户端。 可以调用此扩展函数来简化警报消息的发送，因为 NetAlertRaiseEx 不需要指定 STD_ALERT 结构。

语法

NET_API_STATUS NET_API_FUNCTION NetAlertRaiseEx(
  [in] LPCWSTR AlertType,
  [in] LPVOID  VariableInfo,
  [in] DWORD   VariableInfoSize,
  [in] LPCWSTR ServiceName
);

parameters

[in] AlertType

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

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

[in] VariableInfo

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

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

[in] VariableInfoSize

VariableInfo 参数指向的缓冲区中变量信息的字节数。

[in] ServiceName

指向常量字符串的指针，该字符串指定引发中断消息的服务的名称。

返回值

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

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

返回代码	说明
ERROR_INVALID_PARAMETER	参数不正确。 如果 AlertEventName 参数为 NULL 或空字符串、 ServiceName 参数为 NULL 或空字符串、 VariableInfo 参数为 NULL 或 VariableInfoSize 参数大于 512 减去 STD_ALERT 结构的大小，则返回此错误。
ERROR_NOT_SUPPORTED	不支持该请求。 此错误在 Windows Vista 和更高版本上返回，因为不支持警报器服务。

注解

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

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

示例

以下代码示例演示如何通过调用 NetAlertRaiseEx 函数) 引发以下类型的中断消息 (警报：

• 通过指定 ADMIN_OTHER_INFO 结构来发出管理警报
• 通过指定 PRINT_OTHER_INFO 结构来打印警报
• 通过指定 USER_OTHER_INFO 结构的用户警报

在每个实例中，代码将值分配给相关警报信息结构的成员。 在此之后，此示例通过调用 ALERT_VAR_DATA 宏检索指向结构后面的消息缓冲区部分的指针。 代码还会填充缓冲区的此部分的可变长度字符串。 最后，该示例调用 NetAlertRaiseEx 发送警报。

请注意，调用应用程序必须为警报消息缓冲区中的所有结构和可变长度数据分配和释放内存。

若要在用户警报中传递用户定义的结构和有效字符串，必须创建事件消息文件并将其与应用程序链接。 还必须在注册表的 EventLog 节的 EventMessageFile 子项中注册应用程序。 如果未注册应用程序，则用户警报将包含你在 USER_OTHER_INFO 结构后面的可变长度字符串中传递的信息。 有关 EventMessageFile 的详细信息，请参阅 事件日志记录。

#ifndef UNICODE
#define UNICODE
#endif

#pragma comment(lib, "netapi32.lib")

#include <windows.h>
#include <lm.h>
#include <stdio.h>
#include <time.h>
//
// Define default strings.
//
#define PROGRAM_NAME    TEXT("NETALRT")
#define szComputerName  TEXT("\\\\TESTCOMPUTER")
#define szUserName      TEXT("TEST")
#define szQueueName     TEXT("PQUEUE")
#define szDestName      TEXT("MYPRINTER")
#define szStatus        TEXT("OK")
//
// Define structure sizes.
//
#define VAREDSIZE 312  // maximum size of the variable length message
char buff[VAREDSIZE];
//
int main()
{
   time_t             now;
   PADMIN_OTHER_INFO  pAdminInfo; // ADMIN_OTHER_INFO structure
   PPRINT_OTHER_INFO  pPrintInfo; // PRINT_OTHER_INFO structure
   PUSER_OTHER_INFO   pUserInfo;  // USER_OTHER_INFO structure
   TCHAR              *p;
   DWORD dwResult; 

   time( &now );  // Retrieve the current time to print it later.

   //
   // Sending an administrative alert 
   //
   // Assign values to the members of the ADMIN_OTHER_INFO structure.
   //
   pAdminInfo = (PADMIN_OTHER_INFO) buff; 
   ZeroMemory(pAdminInfo, VAREDSIZE);
   //
   // Error 2377, NERR_LogOverflow, indicates
   //  a log file is full.
   //
   pAdminInfo->alrtad_errcode = 2377;
   pAdminInfo->alrtad_numstrings = 1;
   //
   // Retrieve a pointer to the variable data portion at the 
   //  end of the buffer by calling the ALERT_VAR_DATA macro.
   //
   p = (LPTSTR) ALERT_VAR_DATA(pAdminInfo); 
   //
   // Fill in the variable-length, concatenated strings 
   //  that follow the ADMIN_OTHER_INFO structure. These strings
   //  will be written to the message log.
   //
   wcscpy_s(p,VAREDSIZE/2, TEXT("'C:\\MYLOG.TXT'")); 
   //
   // Call the NetAlertRaiseEx function to raise the
   //  administrative alert.
   //
   dwResult = NetAlertRaiseEx(ALERT_ADMIN_EVENT, pAdminInfo, 255 , TEXT("MYSERVICE"));
   //
   // Display the results of the function call.
   //
   if (dwResult != NERR_Success)
   {
      wprintf(L"NetAlertRaiseEx failed: %d\n", dwResult);
      return -1;
   }
   else
      wprintf(L"Administrative alert raised successfully.\n");


   //
   // Sending a print alert
   //
   // Assign values to the members of the PRINT_OTHER_INFO structure.
   //
   pPrintInfo = (PPRINT_OTHER_INFO) buff; 
   ZeroMemory(pPrintInfo, VAREDSIZE);        
   pPrintInfo->alrtpr_jobid = 5457;
   pPrintInfo->alrtpr_status = 0;
   pPrintInfo->alrtpr_submitted = (DWORD) now;
   pPrintInfo->alrtpr_size = 1000;
   //
   // Retrieve a pointer to the variable data portion at the 
   //  end of the buffer by calling the ALERT_VAR_DATA macro. 
   //
   p = (LPTSTR) ALERT_VAR_DATA(pPrintInfo);  
   //
   // Fill in the variable-length, concatenated strings 
   //  that follow the PRINT_OTHER_INFO structure. 
   //
   wcscpy_s(p, VAREDSIZE/2, szComputerName); // computername 
   p += lstrlen(p) + 1;
   wcscpy_s(p, (VAREDSIZE/2)-wcslen(szComputerName)-1, szUserName);     // user name
   p += lstrlen(p) + 1;
   wcscpy_s(p, (VAREDSIZE/2)-wcslen(szComputerName)-wcslen(szUserName)-2, 
       szQueueName);    // printer queuename
   p += lstrlen(p) + 1;
   wcscpy_s(p, (VAREDSIZE/2)-wcslen(szComputerName)-wcslen(szUserName)-wcslen(szQueueName)-3,
       szDestName);     // destination or printer name (optional)
   p += lstrlen(p) + 1;
   wcscpy_s(p, (VAREDSIZE/2)-wcslen(szComputerName)-wcslen(szUserName)-wcslen(szQueueName) 
       - wcslen(szDestName)-4, szStatus);       // status of the print job (optional)
   //
   // Call the NetAlertRaiseEx function to raise the
   //  print alert.
   //
   dwResult = NetAlertRaiseEx(ALERT_PRINT_EVENT, pPrintInfo, VAREDSIZE, TEXT("MYSERVICE"));
   //
   // Display the results of the function call.
   //
   if (dwResult != NERR_Success)
   {
      wprintf(L"NetAlertRaiseEx failed: %d\n", dwResult);
      return -1;
   }
   else
      wprintf(L"Print alert raised successfully.\n");


   //
   // Sending a user alert
   //
   // Assign values to the members of the USER_OTHER_INFO structure.
   //
   pUserInfo  = (PUSER_OTHER_INFO)  buff; 
   ZeroMemory(pUserInfo, VAREDSIZE);
   pUserInfo->alrtus_errcode = 0xffff;
   pUserInfo->alrtus_numstrings = 1;
   //
   // Retrieve a pointer to the variable data portion at the 
   //  end of the buffer by calling the ALERT_VAR_DATA macro.
   //
   p = (LPTSTR) ALERT_VAR_DATA(pUserInfo); 
   //
   // Fill in the variable-length, concatenated strings 
   //  that follow the USER_OTHER_INFO structure.
   //
   wcscpy_s(p,(VAREDSIZE/2), TEXT("C:\\USERLOG.TXT"));
   p += lstrlen(p) + 1;
   wcscpy_s(p, (VAREDSIZE/2) - wcslen(TEXT("C:\\USERLOG.TXT"))-1, szUserName);
   //
   // Call the NetAlertRaiseEx function to raise the
   //  user alert.
   //
   dwResult = NetAlertRaiseEx(ALERT_USER_EVENT, pUserInfo, VAREDSIZE, TEXT("MYSERVICE"));
   //
   // Display the results of the function call.
   //
   if (dwResult != NERR_Success)
   {
      wprintf(L"NetAlertRaiseEx failed: %d\n", dwResult);
      return -1;
   }
   else
      wprintf(L"User alert raised successfully.\n");

   return(dwResult);   
}

要求

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

另请参阅

ADMIN_OTHER_INFO

ALERT_VAR_DATA

警报函数

ERRLOG_OTHER_INFO

NetAlertRaise

网络管理功能

网络管理概述

PRINT_OTHER_INFO

USER_OTHER_INFO