Функция 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
);
Параметры
[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
Обратите внимание, что вызывающее приложение должно выделять и освобождать память для всех структур и данных переменной длины в буфере сообщений оповещений.
Чтобы передать определяемую пользователем структуру и допустимые строки в оповещении пользователя, необходимо создать файл сообщения о событиях и связать его с приложением. Также необходимо зарегистрировать приложение в подразделе EventMessageFile в разделе EventLog реестра. Если приложение не зарегистрировано, оповещение пользователя будет содержать сведения, которые вы передаете в строки переменной длины, которые соответствуют структуре 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 |
| Header | lmalert.h (включая Lm.h) |
| Библиотека | Netapi32.lib |
| DLL | Netapi32.dll |
См. также раздел
Обратная связь
Ожидается в ближайшее время: в течение 2024 года мы постепенно откажемся от GitHub Issues как механизма обратной связи для контента и заменим его новой системой обратной связи. Дополнительные сведения см. в разделе https://aka.ms/ContentUserFeedback.
Отправить и просмотреть отзыв по