NetAlertRaise 函数 (lmalert.h)
[自 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
指向常量字符串的指针，该字符串指定要引发的警报类 (警报) 类型。 此参数可以是以下预定义值之一，也可以是网络应用程序的用户定义的警报类。 警报的事件名称可以是任何文本字符串。
| 名称 | 含义 |
|---|---|
|
需要管理员的干预。 |
|
错误日志中添加了一个条目。 |
|
用户或应用程序收到了广播消息。 |
|
打印作业已完成或发生打印错误。 |
|
使用了应用程序或资源。 |
[in] Buffer
指向要发送到侦听中断消息的客户端的数据的指针。 数据应以固定长度 STD_ALERT 结构开头，后跟一个 ADMIN_OTHER_INFO、 ERRLOG_OTHER_INFO、 PRINT_OTHER_INFO或 USER_OTHER_INFO 结构中的其他消息数据。 最后，缓冲区应包含任何必需的可变长度信息。 有关详细信息，请参阅以下“备注”部分中的代码示例。
调用应用程序必须为所有结构和变量数据分配和释放内存。 有关详细信息，请参阅 网络管理功能缓冲区。
[in] BufferSize
消息缓冲区的大小（以字节为单位）。
返回值
如果函数成功，则返回值NERR_Success。
如果函数失败，则返回值为系统错误代码，可以是以下错误代码之一。 有关所有可能的错误代码的列表，请参阅 系统错误代码。
| 返回代码 | 说明 |
|---|---|
|
参数不正确。 如果 AlertEventName 参数为 NULL 或空字符串、 Buffer 参数为 NULL 或 BufferSize 参数小于 STD_ALERT 结构的大小加上附加消息数据结构的固定大小，则返回此错误。 |
|
不支持该请求。 此错误在 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 |