Функция 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

Указатель на константную строку, указывающую класс оповещения (тип оповещения), который требуется создать. Этот параметр может быть одним из следующих предопределенных значений или определяемым пользователем классом оповещений для сетевых приложений. Имя события для оповещения может быть любой текстовой строкой.

Имя Значение
ALERT_ADMIN_EVENT
 Требуется вмешательство администратора.
ALERT_ERRORLOG_EVENT
 В журнал ошибок добавлена запись.
ALERT_MESSAGE_EVENT
 Пользователь или приложение получили широковещательное сообщение.
ALERT_PRINT_EVENT
 Задание печати завершено или произошла ошибка печати.
ALERT_USER_EVENT
 Было использовано приложение или ресурс.

[in] Buffer

Указатель на данные, отправляемые клиентам, прослушивающим сообщение о прерывании. Данные должны начинаться с структуры STD_ALERT фиксированной длины, за которой следуют дополнительные данные сообщений в одной структуре ADMIN_OTHER_INFO, ERRLOG_OTHER_INFO, PRINT_OTHER_INFO или USER_OTHER_INFO . Наконец, буфер должен содержать все необходимые сведения о переменной длине. Дополнительные сведения см. в примере кода в следующем разделе Примечаний.

Вызывающее приложение должно выделить и освободить память для всех структур и переменных данных. Дополнительные сведения см. в разделе Буферы функций управления сетью.

[in] BufferSize

Размер буфера сообщений (в байтах).

Возвращаемое значение

Если функция выполнена успешно, возвращаемое значение будет NERR_Success.

Если функция завершается сбоем, возвращаемое значение представляет собой системный код ошибки, а может быть одним из следующих кодов ошибок. Список всех возможных кодов ошибок см. в разделе Системные коды ошибок.

Код возврата Описание
ERROR_INVALID_PARAMETER
 Неправильный параметр. Эта ошибка возвращается, если параметр AlertEventName имеет значение NULL или пустую строку, параметр Buffer имеет значение NULL или параметр BufferSize меньше размера структуры STD_ALERT плюс фиксированный размер для дополнительной структуры данных сообщения.
ERROR_NOT_SUPPORTED
 Запрос не поддерживается. Эта ошибка возвращается в 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

См. также раздел

ADMIN_OTHER_INFO

ALERT_OTHER_INFO

ALERT_VAR_DATA

Функции оповещений

ERRLOG_OTHER_INFO

NetAlertRaiseEx

Функции управления сетью

Общие сведения об управлении сетью

PRINT_OTHER_INFO

STD_ALERT

USER_OTHER_INFO