Функция 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 частям буфера. В примере извлекается указатель на структуру ADMIN_OTHER_INFO путем вызова макроса ALERT_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 |
| Header | lmalert.h (включая Lm.h) |
| Библиотека | Netapi32.lib |
| DLL | Netapi32.dll |