Поделиться через

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

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

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

[in] VariableInfo

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

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

[in] VariableInfoSize

Количество байтов сведений о переменных в буфере, на которые указывает параметр VariableInfo .

[in] ServiceName

Указатель на константную строку, указывающую имя службы, вызывающей сообщение о прерывании.

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

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

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

Код возврата Описание
ERROR_INVALID_PARAMETER
 Неправильный параметр. Эта ошибка возвращается, если параметр AlertEventName имеет значение NULL или пустую строку, параметр ServiceName имеет значение NULL или пустую строку, параметр VariableInfo имеет значение NULL или параметр VariableInfoSize больше 512 за вычетом размера структуры STD_ALERT .
ERROR_NOT_SUPPORTED
 Запрос не поддерживается. Эта ошибка возвращается в Windows Vista и более поздних версиях, так как служба оповещений не поддерживается.

Комментарии

Для успешного выполнения функции NetAlertRaiseEx не требуется специальное членство в группе.

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

Примеры

В следующем примере кода показано, как вызывать функцию NetAlertRaiseEx следующих типов сообщений прерываний (оповещений):

В каждом экземпляре код присваивает значения членам соответствующей структуры сведений об оповещении. После этого в примере извлекается указатель на часть буфера сообщений, следующую за структурой, путем вызова макроса ALERT_VAR_DATA . Код также заполняет строки переменной длины в этой части буфера. Наконец, пример вызывает NetAlertRaiseEx для отправки оповещения.

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

Чтобы передать определяемую пользователем структуру и допустимые строки в оповещении пользователя, необходимо создать файл сообщения о событиях и связать его с приложением. Также необходимо зарегистрировать приложение в подразделе 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

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

ADMIN_OTHER_INFO

ALERT_VAR_DATA

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

ERRLOG_OTHER_INFO

NetAlertRaise

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

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

PRINT_OTHER_INFO

USER_OTHER_INFO