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
指向常量字符串的指针,该字符串指定要引发的警报类 (警报) 类型。 此参数可以是以下预定义值之一,也可以是网络应用程序的用户定义的警报类。 (警报的事件名称可以是任何文本字符串。)
名称 | 含义 |
---|---|
|
需要管理员的干预。 |
|
错误日志中添加了一个条目。 |
|
用户或应用程序收到了广播消息。 |
|
打印作业已完成或发生打印错误。 |
|
使用了应用程序或资源。 |
[in] VariableInfo
指向要发送到侦听中断消息的客户端的数据的指针。 数据应包含一个 ADMIN_OTHER_INFO、 ERRLOG_OTHER_INFO、 PRINT_OTHER_INFO或 USER_OTHER_INFO 结构,后跟任何所需的可变长度信息。 有关详细信息,请参阅以下“备注”部分中的代码示例。
调用应用程序必须为所有结构和变量数据分配和释放内存。 有关详细信息,请参阅 网络管理功能缓冲区。
[in] VariableInfoSize
VariableInfo 参数指向的缓冲区中变量信息的字节数。
[in] ServiceName
指向常量字符串的指针,该字符串指定引发中断消息的服务的名称。
返回值
如果函数成功,则返回值NERR_Success。
如果函数失败,则返回值为系统错误代码,可以是以下错误代码之一。 有关所有可能的错误代码的列表,请参阅 系统错误代码。
返回代码 | 说明 |
---|---|
|
参数不正确。 如果 AlertEventName 参数为 NULL 或空字符串、 ServiceName 参数为 NULL 或空字符串、 VariableInfo 参数为 NULL 或 VariableInfoSize 参数大于 512 减去 STD_ALERT 结构的大小,则返回此错误。 |
|
不支持该请求。 此错误在 Windows Vista 和更高版本上返回,因为不支持警报器服务。 |
注解
无需特殊的组成员身份即可成功执行 NetAlertRaiseEx 函数。
调用 NetAlertRaiseEx 函数时,警报器服务必须在客户端计算机上运行,否则该函数因ERROR_FILE_NOT_FOUND而失败。
示例
以下代码示例演示如何通过调用 NetAlertRaiseEx 函数) 引发以下类型的中断消息 (警报:
- 通过指定 ADMIN_OTHER_INFO 结构来发出管理警报
- 通过指定 PRINT_OTHER_INFO 结构来打印警报
- 通过指定 USER_OTHER_INFO 结构的用户警报
请注意,调用应用程序必须为警报消息缓冲区中的所有结构和可变长度数据分配和释放内存。
若要在用户警报中传递用户定义的结构和有效字符串,必须创建事件消息文件并将其与应用程序链接。 还必须在注册表的 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 |